larray.AxisCollection.set_labels

AxisCollection.set_labels(self, axis=None, labels=None, inplace=False, **kwargs)

Replaces the labels of one or several axes.

Parameters:

axis : string or Axis or dict

Axis for which we want to replace labels, or mapping {axis: changes} where changes can either be the complete list of labels, a mapping {old_label: new_label} or a function to transform labels. If there is no ambiguity (two or more axes have the same labels), axis can be a direct mapping {old_label: new_label}.

labels : int, str, iterable or mapping or function, optional

Integer or list of values usable as the collection of labels for an Axis. If this is mapping, it must be {old_label: new_label}. If it is a function, it must be a function accepting a single argument (a label) and returning a single value. This argument must not be used if axis is a mapping.

inplace : bool, optional

Whether or not to modify the original object or return a new AxisCollection and leave the original intact. Defaults to False.

**kwargs :

axis`=`labels for each axis you want to set labels.

Returns:

AxisCollection

AxisCollection with modified labels.

Warning

Not passing a mapping but the complete list of new labels as the ‘labels’ argument must be done with caution. Make sure that the order of new labels corresponds to the exact same order of previous labels.

Examples

>>> from larray import ndtest
>>> axes = AxisCollection('nat=BE,FO;sex=M,F')
>>> axes
AxisCollection([
    Axis(['BE', 'FO'], 'nat'),
    Axis(['M', 'F'], 'sex')
])
>>> axes.set_labels('sex', ['Men', 'Women'])
AxisCollection([
    Axis(['BE', 'FO'], 'nat'),
    Axis(['Men', 'Women'], 'sex')
])

when passing a single string as labels, it will be interpreted to create the list of labels, so that one can use the same syntax than during axis creation.

>>> axes.set_labels('sex', 'Men,Women')
AxisCollection([
    Axis(['BE', 'FO'], 'nat'),
    Axis(['Men', 'Women'], 'sex')
])

to replace only some labels, one must give a mapping giving the new label for each label to replace

>>> axes.set_labels('sex', {'M': 'Men'})
AxisCollection([
    Axis(['BE', 'FO'], 'nat'),
    Axis(['Men', 'F'], 'sex')
])

to transform labels by a function, use any function accepting and returning a single argument:

>>> axes.set_labels('nat', str.lower)
AxisCollection([
    Axis(['be', 'fo'], 'nat'),
    Axis(['M', 'F'], 'sex')
])

to replace labels for several axes at the same time, one should give a mapping giving the new labels for each changed axis

>>> axes.set_labels({'sex': 'Men,Women', 'nat': 'Belgian,Foreigner'})
AxisCollection([
    Axis(['Belgian', 'Foreigner'], 'nat'),
    Axis(['Men', 'Women'], 'sex')
])

or use keyword arguments

>>> axes.set_labels(sex='Men,Women', nat='Belgian,Foreigner')
AxisCollection([
    Axis(['Belgian', 'Foreigner'], 'nat'),
    Axis(['Men', 'Women'], 'sex')
])

one can also replace some labels in several axes by giving a mapping of mappings

>>> axes.set_labels({'sex': {'M': 'Men'}, 'nat': {'BE': 'Belgian'}})
AxisCollection([
    Axis(['Belgian', 'FO'], 'nat'),
    Axis(['Men', 'F'], 'sex')
])

when there is no ambiguity (two or more axes have the same labels), it is possible to give a mapping between old and new labels

>>> axes.set_labels({'M': 'Men', 'BE': 'Belgian'})
AxisCollection([
    Axis(['Belgian', 'FO'], 'nat'),
    Axis(['Men', 'F'], 'sex')
])