User Reference for SIMPLE

The simple namespace contains everything necessary for normal usage of the package.

simple

simple.asarray

asarray(values, dtype=None, saving=False)

Convert data to a numpy array.

If data is a string or a sequence of strings and saving=False, either a single string or a tuple of string will be returned. If saving is True the values will be converted to an array with a byte dtype. This ensures values are compatible with the hdf5 library.

Arrays with a bytes dtype will automatically be converted to the str dtype. If saving is False then this values will be converted to either a string or a tuple of strings (see above).

Parameters:

• values –

  An values like object.

• dtype –

  The data type of the returned values.

• saving –

  Should be True is the data is to be saved in a hdf5 file.

Source code in simple/utils.py

def asarray(values, dtype=None, saving=False):
    """
    Convert ``data`` to a numpy array.

    If ``data`` is a string or a sequence of strings and ``saving=False``, either a single string or a tuple
    of string will be returned. If ``saving`` is ``True`` the values will be converted to an array with a byte dtype.
    This ensures values are compatible with the hdf5 library.

    Arrays with a ``bytes`` dtype will automatically be converted to the ``str`` dtype. If ``saving`` is ``False`` then
    this values will be converted to either a string or a tuple of strings (see above).

    Args:
        values (): An values like object.
        dtype (): The data type of the returned values.
        saving (): Should be ``True`` is the data is to be saved in a hdf5 file.

    """
    values = np.asarray(values, dtype=dtype)

    if values.dtype.type is np.bytes_:
        values = values.astype(np.str_)

    if not saving and values.dtype.type is np.str_:
        values = values.tolist()
        if type(values) is list:
            values = tuple(values)

    if saving and values.dtype.type is np.str_:
        values = values.astype(np.bytes_)

    return values

simple.aselement

aselement(string, without_suffix=False, allow_invalid=False)

Returns a Element representing an element symbol.

The returned element format is the capitalised element symbol followed by the suffix, if present. E.g. Pd-104* where * is the suffix.

The case of the element symbol is not considered.

Parameters:

• string (str) –

  A string containing an element symbol.

• without_suffix –

  If True the suffix part of the string is ignored.

• allow_invalid –

  If False, and string cannot be parsed into an element string, an exception is raised. If True then string.strip() is returned instead.

Examples:

>>> ele = simple.asisotope("pd"); ele
"Pd"

Source code in simple/utils.py

def aselement(string, without_suffix=False, allow_invalid=False):
    """
    Returns a [``Element``][simple.utils.Element] representing an element symbol.

    The returned element format is the capitalised element
    symbol followed by the suffix, if present. E.g. ``Pd-104*`` where
    ``*`` is the suffix.

    The case of the element symbol is not considered.

    Args:
        string (str): A string containing an element symbol.
        without_suffix (): If ``True`` the suffix part of the string is ignored.
        allow_invalid ():  If ``False``, and ``string`` cannot be parsed into an element string, an exception is
            raised. If ``True`` then ``string.strip()`` is returned instead.

    Examples:
        >>> ele = simple.asisotope("pd"); ele
        "Pd"


    """
    if type(string) is Element:
        if without_suffix:
            return string.without_suffix()
        else:
            return string
    elif isinstance(string, str):
        string = string.strip()
    else:
        raise TypeError(f'``string`` must a str not {type(string)}')

    try:
        return Element(string, without_suffix=without_suffix)
    except ValueError:
        if allow_invalid:
            return string
        else:
            raise

simple.aselements

aselements(strings, without_suffix=False, allow_invalid=False)

Returns a tuple of Element strings where each string represents an element symbol.

Parameters:

• strings –

  Can either be a string with element symbol seperated by a , or a sequence of strings.

• without_suffix –

  If True the suffix part of each isotope string is ignored.

• allow_invalid –

  If False, and a string cannot be parsed into an isotope string, an exception is raised. If True then string.strip() is returned instead.

Examples:

>>> simple.asisotopes('ru, pd, cd')
('Ru', 'Pd', 'Cd')

>>> simple.asisotopes(['ru', 'pd', 'cd'])
('Ru', 'Pd', 'Cd')

Source code in simple/utils.py

def aselements(strings, without_suffix=False, allow_invalid=False):
    """
    Returns a tuple of [``Element``][simple.utils.Element] strings where each string represents an element symbol.

    Args:
        strings (): Can either be a string with element symbol seperated by a ``,`` or a sequence of strings.
        without_suffix (): If ``True`` the suffix part of each isotope string is ignored.
        allow_invalid ():  If ``False``, and a string cannot be parsed into an isotope string, an exception is
            raised. If ``True`` then ``string.strip()`` is returned instead.

    Examples:
        >>> simple.asisotopes('ru, pd, cd')
        ('Ru', 'Pd', 'Cd')

        >>> simple.asisotopes(['ru', 'pd', 'cd'])
        ('Ru', 'Pd', 'Cd')
    """
    if type(strings) is str:
        strings = [s for s in strings.split(',')]

    return tuple(aselement(string, without_suffix=without_suffix, allow_invalid=allow_invalid) for string in strings)

simple.asisolist

asisolist(isolist, without_suffix=False, allow_invalid=False)

Return a dictionary consisting of an isotope key mapped to a tuple of isotopes that should make up the key isotope.

If isolist is list or tuple of keys then each key will be mapped only to itself.

Parameters:

• isolist –

  Either a dictionary mapping a single isotope to a list of isotopes or a sequence of isotopes that will be mapped to themselfs.

• without_suffix –

  If True the suffix part of each isotope string is ignored.

• allow_invalid –

  If True invalid isotopes string are allowed. If False they will instead raise an exception.

Source code in simple/utils.py

def asisolist(isolist, without_suffix=False, allow_invalid=False):
    """
    Return a dictionary consisting of an isotope key mapped to a tuple of isotopes that should make up the
    key isotope.

    If ``isolist`` is list or tuple of keys then each key will be mapped only to itself.

    Args:
        isolist (): Either a dictionary mapping a single isotope to a list of isotopes or a sequence of isotopes that
            will be mapped to themselfs.
        without_suffix (): If ``True`` the suffix part of each isotope string is ignored.
        allow_invalid (): If ``True`` invalid isotopes string are allowed. If ``False`` they will instead raise
            an exception.
    """
    if type(isolist) is not dict:
        isolist = asisotopes(isolist, without_suffix=without_suffix, allow_invalid=allow_invalid)
        return {iso: (iso,) for iso in isolist}
    else:
        return {asisotope(k, without_suffix=without_suffix, allow_invalid=allow_invalid):
                asisotopes(v, without_suffix=without_suffix, allow_invalid=allow_invalid)
                for k,v in isolist.items()}

simple.asisotope

asisotope(string, without_suffix=False, allow_invalid=False)

Returns a Isotope representing an isotope.

The returned isotope format is the capitalised element symbol followed by a dash followed by the mass number followed by the suffix, if present. E.g. Pd-104* where * is the suffix.

The order of the element symbol and mass number in string is not important, but they must proceed the suffix. The element symbol and mass number may be seperated by -. The case of the element symbol is not considered.

Parameters:

• string (str) –

  A string element symbol and a mass number.

• without_suffix –

  If True the suffix part of the isotope string is ignored.

• allow_invalid –

  If False, and string cannot be parsed into an isotope string, an exception is raised. If True then string.strip() is returned instead.

Examples:

>>> iso = simple.asisotope("104pd"); iso # pd104, 104-Pd etc are also valid
"Pd-104"
>>> iso.symbol, iso.mass
"Pd", "104"

Source code in simple/utils.py

def asisotope(string, without_suffix=False, allow_invalid=False):
    """
    Returns a [``Isotope``][simple.utils.Isotope] representing an isotope.

    The returned isotope format is the capitalised element
    symbol followed by a dash followed by the mass number followed by the suffix, if present. E.g. ``Pd-104*`` where
    ``*`` is the suffix.

    The order of the element symbol and mass number in ``string`` is not important, but they must proceed the suffix.
    The element symbol and mass number may be seperated by ``-``. The case of the element symbol is not
    considered.

    Args:
        string (str): A string element symbol and a mass number.
        without_suffix (): If ``True`` the suffix part of the isotope string is ignored.
        allow_invalid ():  If ``False``, and ``string`` cannot be parsed into an isotope string, an exception is
            raised. If ``True`` then ``string.strip()`` is returned instead.

    Examples:
        >>> iso = simple.asisotope("104pd"); iso # pd104, 104-Pd etc are also valid
        "Pd-104"
        >>> iso.symbol, iso.mass
        "Pd", "104"

    """
    if type(string) is Isotope:
        if without_suffix:
            return string.without_suffix()
        else:
            return string
    elif isinstance(string, str):
        string = string.strip()
    else:
        raise TypeError(f'``string`` must a str not {type(string)}')

    try:
        return Isotope(string, without_suffix=without_suffix)
    except ValueError:
        if allow_invalid:
            return string
        else:
            raise

simple.asisotopes

asisotopes(strings, without_suffix=False, allow_invalid=False)

Returns a tuple of Isotope strings where each string represents an isotope.

Parameters:

• strings –

  Can either be a string with isotopes seperated by a , or a sequence of strings.

• without_suffix –

  If True the suffix part of each isotope string is ignored.

• allow_invalid –

  If False, and a string cannot be parsed into an isotope string, an exception is raised. If True then string.strip() is returned instead.

Examples:

>>> simple.asisotopes('104pd, pd105, 106-Pd')
('Pd-104', 'Pd-105, 106-Pd')

>>> simple.asisotopes(['104pd', 'pd105', '106-Pd'])
('Pd-104', 'Pd-105, 106-Pd')

Source code in simple/utils.py

def asisotopes(strings, without_suffix=False, allow_invalid=False):
    """
    Returns a tuple of [``Isotope``][simple.utils.Isotope] strings where each string represents an isotope.

    Args:
        strings (): Can either be a string with isotopes seperated by a ``,`` or a sequence of strings.
        without_suffix (): If ``True`` the suffix part of each isotope string is ignored.
        allow_invalid ():  If ``False``, and a string cannot be parsed into an isotope string, an exception is
            raised. If ``True`` then ``string.strip()`` is returned instead.

    Examples:
        >>> simple.asisotopes('104pd, pd105, 106-Pd')
        ('Pd-104', 'Pd-105, 106-Pd')

        >>> simple.asisotopes(['104pd', 'pd105', '106-Pd'])
        ('Pd-104', 'Pd-105, 106-Pd')
    """
    if type(strings) is str:
        strings = [s for s in strings.split(',')]

    return tuple(asisotope(string, without_suffix=without_suffix, allow_invalid=allow_invalid) for string in strings)

simple.askeyarray

askeyarray(values, keys, dtype=None)

Returns a numpy array where the columns can be accessed by the column key.

Parameters:

• values –

  An array consisting of 2 dimensions where first dimension is the row and the second

• keys –

  The keys for each column in values. Must be the same length as the second dimension of values.

• dtype –

  The values type of the returned array. All columns will have the same dtype.

Notes If values has less then 2 dimensions then it is assumed to represent a single row of values.

It is not possible to save this type of array in hdf5 files if they have more than a few hundred columns.

Examples:

>>> a = simple.askeyarray([[1,2,3],[4,5,6]], ['Pd-104','Pd-105','Pd-106']); a
array([(1, 2, 3), (4, 5, 6)],
      dtype=[('Pd-104', '<i8'), ('Pd-105', '<i8'), ('Pd-106', '<i8')])
>>> a['Pd-104']
array([1, 4])

Source code in simple/utils.py

def askeyarray(values, keys, dtype=None):
    """
    Returns a numpy array where the columns can be accessed by the column key.

    Args:
        values (): An array consisting of 2 dimensions where first dimension is the row and the second
        dimension is the column.
        keys (): The keys for each column in ``values``. Must be the same length as the second dimension of ``values``.
        of ``array``.
        dtype (): The values type of the returned array. All columns will have the same dtype.

    **Notes**
    If ``values`` has less then 2 dimensions then it is assumed to represent a single row of values.

    It is not possible to save this type of array in hdf5 files if they have more than a few hundred columns.

    Examples:
        >>> a = simple.askeyarray([[1,2,3],[4,5,6]], ['Pd-104','Pd-105','Pd-106']); a
        array([(1, 2, 3), (4, 5, 6)],
              dtype=[('Pd-104', '<i8'), ('Pd-105', '<i8'), ('Pd-106', '<i8')])
        >>> a['Pd-104']
        array([1, 4])

    """
    if type(keys) is str:
        keys = [k.strip() for k in keys.split(',')]

    a = np.asarray(values, dtype=dtype)
    dtype = [(k, a.dtype) for k in keys]

    if a.ndim < 2:
        a = a.reshape((-1, a.size))
    elif a.ndim > 2:
        raise ValueError('``values`` cannot have more than 2 dimensions')

    if a.shape[1] != len(keys):
        raise ValueError(
            f'item (r:{a.shape[0]}, c:{a.shape[1]}) must have same number of columns as there are keys ({len(keys)})')

    return np.array([tuple(r) for r in a], dtype=dtype)

simple.asratio

asratio(string, without_suffix=False, allow_invalid=False)

Returns a Ratio string representing the ratio of two isotopes.

The format of the returned string is the numerator followed by a / followed by the normiso. The numerator and normiso string be parsed by asisotope together with the given without_suffix and allow_invalid arguments passed to this function.

Parameters:

• string (str) –

  A string contaning two strings seperated by a single /.

• without_suffix (bool, default: False ) –

  If True the suffix part of the numerator and normiso string is ignored.

• allow_invalid (bool, default: False ) –

  Whether the numerator and normiso has to be a valid isotope string.

If the returned string is an isotope string it will have the following attributes and methods.

Attributes:

• numer (str) –

  The numerator string

• denom (str) –

  The normiso string

Functions:

• latex –

  Returns a latex formatted version of the isotope.

• without_suffix –

  Returns a ratio string omitting the numerator and normiso suffix.

Source code in simple/utils.py

def asratio(string, without_suffix=False, allow_invalid=False):
    """
    Returns a [``Ratio``][simple.utils.Isotope] string representing the ratio of two isotopes.

    The format of the returned string is the numerator followed by
    a ``/`` followed by the normiso. The numerator and normiso string be parsed by ``asisotope`` together with
    the given ``without_suffix`` and ``allow_invalid`` arguments passed to this function.

    Args:
        string (str): A string contaning two strings seperated by a single ``/``.
        without_suffix (bool): If ``True`` the suffix part of the numerator and normiso string is ignored.
        allow_invalid (bool): Whether the numerator and normiso has to be a valid isotope string.

    If the returned string is an isotope string it will have the following attributes and methods.

    Attributes:
        numer (str): The numerator string
        denom (str): The normiso string

    Methods:
        latex(string): Returns a latex formatted version of the isotope.
        without_suffix(): Returns a ratio string omitting the numerator and normiso suffix.

    """
    if type(string) is Ratio:
        return string
    elif isinstance(string, str):
        string = string.strip()
    else:
        raise TypeError(f'``string`` must a str not {type(string)}')

    try:
        return Ratio(string, without_suffix=without_suffix)
    except ValueError:
        if allow_invalid:
            return string
        else:
            raise

simple.asratios

asratios(strings, without_suffix=False, allow_invalid=False)

Returns a tuple of Ratio strings where each string represents the ratio of two isotopes.

Parameters:

• strings –

  Can either be a string with isotope ratios seperated by a , or a sequence of strings.

• without_suffix –

  If True the suffix part of each isotope string is ignored.

• allow_invalid –

  If False, and a string cannot be parsed into an isotope string, an exception is raised. If True then string.strip() is returned instead.

Source code in simple/utils.py

def asratios(strings, without_suffix=False, allow_invalid=False):
    """
    Returns a tuple of [``Ratio``][simple.utils.Isotope] strings where each string represents the ratio of two isotopes.

    Args:
        strings (): Can either be a string with isotope ratios seperated by a ``,`` or a sequence of strings.
        without_suffix (): If ``True`` the suffix part of each isotope string is ignored.
        allow_invalid ():  If ``False``, and a string cannot be parsed into an isotope string, an exception is
            raised. If ``True`` then ``string.strip()`` is returned instead.
    """
    if type(strings) is str:
        strings = [s.strip() for s in strings.split(',')]

    return tuple(asratio(string, without_suffix=without_suffix, allow_invalid=allow_invalid) for string in strings)

simple.create_legend

create_legend(ax, outside=False, outside_margin=0.01, **kwargs)

Add a legend to a plot.

Parameters:

• ax –

  The working axes. Accepted values are any matplotlib Axes object or plt instance.

• outside (bool, default: False ) –

  If True the legend will be drawn just outside the upper left corner of the plot. This will overwrite any loc and bbox_to_anchor arguments in kwargs.

• outside_margin –

  Margin between the plot and the legend. Relative to the width of the plot.

• **kwargs –

  Any valid argument for matplotlibs legend function.

Source code in simple/plotting.py

@utils.set_default_kwargs()
def create_legend(ax, outside = False, outside_margin=0.01, **kwargs):
    """
    Add a legend to a plot.

    Args:
        ax (): The working axes. Accepted values are any matplotlib Axes object or plt instance.
        outside (bool): If ``True`` the legend will be drawn just outside the upper left corner of the plot. This will
            overwrite any ``loc`` and ``bbox_to_anchor`` arguments in ``kwargs``.
        outside_margin (): Margin between the plot and the legend. Relative to the width of the plot.
        **kwargs (): Any valid argument for matplotlibs
            [``legend``](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.legend.html) function.
    """
    ax = get_axes(ax)

    if outside:
        kwargs['loc'] = 'upper left'
        kwargs['bbox_to_anchor'] = (1+outside_margin, 1)

    ax.legend(**kwargs)

simple.create_rose_plot

create_rose_plot(ax=None, *, vmin=None, vmax=None, log=False, cmap='turbo', colorbar_show=True, colorbar_label=None, colorbar_fontsize=None, xscale=1, yscale=1, segment=None, rres=None, **fig_kw)

Create a plot with a rose projection.

The rose ax is a subclass of matplotlibs polar ax.

Parameters:

• ax –

  If no preexisting ax is given then a new figure with a single rose ax is created. If an existing

• vmin (float, default: None ) –

  The lower limit of the colour map. If no value is given the minimum value is 0 (or 1E-10 if

• vmax (float, default: None ) –

  The upper limit of the colour map. If no value is given then vmax is set to 1 and all bin default_weight are divided by the heaviest bin weight in each histogram.

• log (bool, default: False ) –

  Whether the color map scale is logarithmic or not.

• cmap –

  The prefixes of the colormap to use. See, [matplotlib documentation][https://matplotlib.org/stable/users/explain/colors/colormaps.html] for a list of available colormaps.

• colorbar_show –

  Whether to add a colorbar to the right of the ax.

• colorbar_label –

  The label given to the colorbar.

• colorbar_fontsize –

  The fontsize of the colorbar label.

• xscale –

  The scale of the x axis.

• yscale –

  The scale of the y axis.

• segment –

  Which segment of the rose diagram to show. Options are N, E, S, W, None. If None the entire circle is shown.

• rres –

  The resolution of lines drawn along the radius r. The number of points in a line is calculated as

• **fig_kw –

  Additional figure keyword arguments passed to the pyplot.figure call. Only used when ax is not given.

Returns:

• RoseAxes –

  The new rose ax.

Source code in simple/plotting.py

def create_rose_plot(ax=None, *, vmin= None, vmax=None, log = False, cmap='turbo',
                     colorbar_show=True, colorbar_label=None, colorbar_fontsize=None,
                     xscale=1, yscale=1,
                     segment = None, rres=None,
                     **fig_kw):
    """
    Create a plot with a [rose projection](simple.plot.RoseAxes).

    The rose ax is a subclass of matplotlibs
    [polar ax](https://matplotlib.org/stable/api/projections/polar.html#matplotlib.projections.polar.PolarAxes).

    Args:
        ax (): If no preexisting ax is given then a new figure with a single rose ax is created. If an existing
        ax is passed this ax will be deleted and replaced with a [RoseAxes][#RoseAxes].
        vmin (float): The lower limit of the colour map. If no value is given the minimum value is ``0`` (or ``1E-10`` if
        ``log=True``)
        vmax (float): The upper limit of the colour map. If no value is given then ``vmax`` is set to ``1`` and all bin
            default_weight are divided by the heaviest bin weight in each histogram.
        log (bool): Whether the color map scale is logarithmic or not.
        cmap (): The prefixes of the colormap to use. See,
                [matplotlib documentation][https://matplotlib.org/stable/users/explain/colors/colormaps.html]
                 for a list of available colormaps.
        colorbar_show (): Whether to add a colorbar to the right of the ax.
        colorbar_label (): The label given to the colorbar.
        colorbar_fontsize (): The fontsize of the colorbar label.
        xscale (): The scale of the x axis.
        yscale (): The scale of the y axis.
        segment (): Which segment of the rose diagram to show. Options are ``N``, ``E``, ``S``, ``W``, ``None``.
            If ``None`` the entire circle is shown.
        rres (): The resolution of lines drawn along the radius ``r``. The number of points in a line is calculated as
        ``r*rres+1`` (Min. 2).
        **fig_kw (): Additional figure keyword arguments passed to the ``pyplot.figure`` call. Only used when ``ax``
            is not given.

    Returns:
        RoseAxes : The new rose ax.
    """
    if ax is None:
        figure_kwargs = {'layout': 'constrained'}
        figure_kwargs.update(fig_kw)
        fig, ax = plt.subplots(subplot_kw={'projection': 'rose'}, **figure_kwargs)
    else:
        ax = get_axes(ax)
        fig = ax.get_figure()
        rows, cols, start, stop = ax.get_subplotspec().get_geometry()

        ax.remove()
        ax = fig.add_subplot(rows, cols, start + 1, projection='rose')

    if colorbar_label is None:
        if vmax is None:
            colorbar_label = f'Bin weight normalised to largest bin'
        else:
            colorbar_label = f'Bin weight'
    elif colorbar_label is False:
        colorbar_label = None

    ax.set_colorbar(vmin=vmin, vmax=vmax, log=log, cmap=cmap,
                    label=colorbar_label, show=colorbar_show, fontsize=colorbar_fontsize)
    ax.set_xyscale(xscale, yscale)

    if segment:
        ax.set_segment(segment)

    if rres:
        ax.set_rres(rres)

    return ax

simple.get_data

get_data(models, axis_names, *, where=None, latex_labels=True, key=None, default_attrname=None, unit=None, default_value=np.nan, key_in_label=None, numer_in_label=None, denom_in_label=None, model_in_label=None, unit_in_label=None, attrname_in_label=None, axis_name_in_label=None, label=True, prefix_label=None, suffix_label=None, mask=None, mask_na=True, _kwargs=None, **kwargs)

Get one or more datasets from a group of models together with suitable labels.

Each data point is a dictionary that contains a value for each of the axis given in axis_names plus a label describing the data point. The value for each axis is determined by the key argument. This argument has two possible components; the name of the attribute and the index, or key, to be applied this, or the default_attrname, attribute.

The name of the attribute must start with a . followed by the path to the attribute relative to the Model object using successive . for nested attributes, e.g. .intnorm.eRi.

The index, or key, part of the key can either be an integer, a slice or a sequence of keys seperated by ,. The keys will be parsed into either Isotope, Ratio, or Element strings. If a key is given it is assumed that the attribute contains an isotope key array. Therefore, Element strings will be replaced with all the isotopes of that element present in the attribute (Across all models) and Ratio strings will return the numerator value divided by the denominator value.

If the attribute name is given in key then the index, or key, part must be enclosed in square brackets, e.g. .intnorm.eRi[105Pd]. If the default_attrname should be used then key should only contain the index, or key.

By the default the label for each data point only contains the information is not shared with all other data points. Information that is shared between all data points is instead included in the axis labels.

Parameters:

• models –

  A collection of models to plot. A subselection of these models can be made using the where argument.

• axis_names –
• where (str, default: None ) –

  If given will be used to create a subselection of models. Any kwargs prefixed with where_ will be supplied as keyword arguments. See ModelCollection.where for more details.

• latex_labels (bool, default: True ) –

  Whether to use the latex formatting in the labels, when available.

• key ((str, int, slice), default: None ) –

  This can either be a valid index to the default_attrname array or the path, with or without a valid index, of a different attribute. Accepts either single universal value or a list of values, one for each axis (See below for details).

• default_attrname –

  The name of the default attribute to use if xkey and ykey are indexes. By default, the default key array is used. Accepts either single universal value or a list of values, one for each axis (See below for details).

• unit –

  The desired unit for the xkey and ykey. Different units for xkey and ykey can be specified by supplying a (<xkey_unit>, <ykey_unit>) sequence. Accepts either single universal value or a list of values, one for each axis (See below for details).

• default_value –

  The value given to invalid indexes of arrays. Must have a shape compatible with the size of the indexed array. Accepts either single universal value or a list of values, one for each axis (See below for details).

• key_in_label (bool, default: None ) –

  Whether to include the key index in the label. Accepts either single universal value or a list of values, one for each axis (See below for details).

• numer_in_label (bool, default: None ) –

  Whether to include the numerator of a key index in the label. Accepts either single universal value or a list of values, one for each axis (See below for details).

• denom_in_label (bool, default: None ) –

  Whether to include the denominator of a key index in the label. Accepts either single universal value or a list of values, one for each axis (See below for details).

• model_in_label (bool, default: None ) –

  Whether to include the model name in the label. Accepts either single universal value or a list of values, one for each axis (See below for details).

• unit_in_label (bool, default: None ) –

  Whether to include the unit in the label. Accepts either single universal value or a list of values, one for each axis (See below for details).

• attrname_in_label (bool, default: None ) –

  Whether to include the attribute name in the label. By default the name is only included if it is different from the default_attrname. Accepts a single universal value or a list of values, one for each axis (See below for details).

• axis_name_in_label (bool, default: None ) –

  Whether to include the axis name in the label. Accepts either single universal value or a value for each axis (See below for details).

• label ((str, bool, None), default: True ) –

  The label for individual datapoints. Accepts either a single universal value or a list of values, one per data point (See below for details).

• prefix_label –

  Text to be added to the beginning of each data point label. Accepts either a single universal value or a list of values, one per data point (See below for details).

• suffix_label –

  Text to be added at the end of each data point label. Accepts either a single universal value or a list of values, one per data point (See below for details).

• mask ((str, int, slice), default: None ) –

  Can be used to apply a mask to the data which is plotted. See the get_mask function of the Model object. Accepts either a single universal value or a list of values, one per model (See below for details).

• mask_na (bool, default: True ) –

  If True masked values will be replaced by np.nan values. Only works if all arrays in a dataset have a float based datatype. Accepts either a single universal value or a list of values, one per model (See below for details).

• **kwargs –

One per axis arguments

These arguments allow you to set a different value for each axis in axis_names. This can be either a single value used for all the axis or a sequence of values, one per axis.

It is also possible to define the value for a specific axis by including a keyword argument consiting of the axis name followed directly by the argument name. The value specified this way will take presidence over the value given by the argument itself. For example xkey=102Pd will set the key argument for the x axis to 102Pd.

One per data point arguments

These arguments allow you to set a different value for each data point. The number of data points is equal to the number of models multiplied by the number of datasets generated. This can be either a single value used for all the axis or a sequence of values, one per data point.

One per model arguments

These arguments allow you to set a different value for each model in models. This can be either a single value used for all the axis or a sequence of values, one per model.

Returns:

• –

  Tuple[dict, dict]: Two dictionaries containing:

  • A dictionary with the data points for each model, mapped to the model name

  • A dictionary containing labels for each axis, mapped to the axis name.

Examples:

Here is an example of how the return data can be used.

model_datapoints, axis_labels = simple.get_data(models, 'x, y', xkey=..., ykey=...)

# Set the axis labels
plt.set_xlabel(axis_labels['x'])
plt.set_ylabel(axis_labels['y'])

# Iterate though the data and plot it
for model_name, datapoints in model_datapoints.items():
    for dp in datapoints:
        plt.plot(dp['x'], dp['y'], label=dp['label'])

Source code in simple/plotting.py

@utils.set_default_kwargs()
def get_data(models, axis_names, *, where=None, latex_labels = True,
             key=None, default_attrname=None, unit=None, default_value = np.nan,
             key_in_label=None, numer_in_label=None, denom_in_label=None,
             model_in_label=None, unit_in_label=None, attrname_in_label=None, axis_name_in_label=None,
             label = True, prefix_label = None, suffix_label = None,
             mask = None, mask_na = True,
             _kwargs = None, **kwargs):
    """
    Get one or more datasets from a group of models together with suitable labels.

    Each data point is a dictionary that contains a value for each of the axis given in *axis_names* plus a label
    describing the data point. The value for each axis is determined by the *key* argument. This argument has two
    possible components; the name of the attribute and the index, or key, to be applied this, or the
    *default_attrname*, attribute.

    The name of the attribute must start with a ``.`` followed by the path to the attribute relative to the Model
    object using successive ``.`` for nested attributes, e.g. ``.intnorm.eRi``.

    The index, or key, part of the *key* can either be an integer, a slice or a sequence of keys seperated by ``,``.
    The keys will be parsed into either [Isotope](simple.utils.Isotope), [Ratio](simple.utils.Ratio), or
    [Element](simple.utils.Element) strings. If a key is given it is assumed that the attribute contains an isotope
    key array. Therefore, Element strings will be replaced with all the isotopes of that element
    present in the attribute (Across all models) and Ratio strings will return the numerator value divided by the
    denominator value.

    If the attribute name is given in *key* then the index, or key, part must be enclosed in square brackets, e.g.
    ``.intnorm.eRi[105Pd]``. If the *default_attrname* should be used then *key* should only contain the index, or key.

    By the default the label for each data point only contains the information is not shared with all other data points.
    Information that is shared between all data points is instead included in the axis labels.

    Args:
        models (): A collection of models to plot. A subselection of these models can be made using the *where*
            argument.
        axis_names ():
        where (str): If given will be used to create a subselection of *models*. Any *kwargs* prefixed
            with ``where_`` will be supplied as keyword arguments. See
             [``ModelCollection.where``](simple.models.ModelCollection.where) for more details.
        latex_labels (bool): Whether to use the latex formatting in the labels, when available.
        key (str, int, slice): This can either be a valid index to the *default_attrname* array or the path, with
            or without a valid index, of a different attribute. Accepts either single universal value
            or a list of values, one for each axis (See below for details).
        default_attrname (): The name of the default attribute to use if *xkey* and *ykey* are indexes. By default,
            the default key array is used. Accepts either single universal value or a list of values, one for each
            axis (See below for details).
        unit (): The desired unit for the *xkey* and *ykey*. Different units for *xkey* and *ykey* can be specified
            by supplying a ``(<xkey_unit>, <ykey_unit>)`` sequence. Accepts either single universal value
            or a list of values, one for each axis (See below for details).
        default_value (): The value given to invalid indexes of arrays. Must have a shape compatible with the size
            of the indexed array. Accepts either single universal value
            or a list of values, one for each axis (See below for details).
        key_in_label (bool): Whether to include the key index in the label. Accepts either single universal value
            or a list of values, one for each axis (See below for details).
        numer_in_label (bool): Whether to include the numerator of a key index in the label. Accepts either single
            universal value or a list of values, one for each axis (See below for details).
        denom_in_label (bool): Whether to include the denominator of a key index in the label. Accepts either single
            universal value or a list of values, one for each axis (See below for details).
        model_in_label (bool): Whether to include the model name in the label. Accepts either single universal value
            or a list of values, one for each axis (See below for details).
        unit_in_label (bool): Whether to include the unit in the label. Accepts either single universal value
            or a list of values, one for each axis (See below for details).
        attrname_in_label (bool): Whether to include the attribute name in the label. By default
            the name is only included if it is different from the *default_attrname*. Accepts a single universal
            value or a list of values, one for each axis (See below for details).
        axis_name_in_label (bool): Whether to include the axis name in the label. Accepts either single universal value
            or a value for each axis (See below for details).
        label (str, bool, None): The label for individual datapoints. Accepts either a single universal value or
            a list of values, one per data point (See below for details).
        prefix_label (): Text to be added to the beginning of each data point label. Accepts either a single universal
            value or a list of values, one per data point (See below for details).
        suffix_label (): Text to be added at the end of each data point label. Accepts either a single universal
            value or a list of values, one per data point (See below for details).
        mask (str, int, slice): Can be used to apply a mask to the data which is plotted. See the
            ``get_mask`` function of the Model object. Accepts either a single universal
            value or a list of values, one per model (See below for details).
        mask_na (bool): If ``True`` masked values will be replaced by ``np.nan`` values. Only works if all arrays
            in a dataset have a float based datatype. Accepts either a single universal
            value or a list of values, one per model (See below for details).
        **kwargs:

    One per axis arguments:
        These arguments allow you to set a different value for each axis in *axis_names*. This can be
        either a single value used for all the axis or a sequence of values, one per axis.

        It is also possible to define the value for a specific axis by  including a keyword argument consiting
        of the axis name followed directly by the argument name. The value specified this way will take presidence over
        the value given by the argument itself. For example ``xkey=102Pd`` will set the *key* argument for
        the *x* axis to ``102Pd``.


    One per data point arguments:
        These arguments allow you to set a different value for each data point. The number of data points is
        equal to the number of models multiplied by the number of datasets generated. This can be
        either a single value used for all the axis or a sequence of values, one per data point.


    One per model arguments:
        These arguments allow you to set a different value for each model in *models*. This can be
        either a single value used for all the axis or a sequence of values, one per model.


    Returns:
        Tuple[dict, dict]: Two dictionaries containing:

            - A dictionary with the data points for each model, mapped to the model name

            - A dictionary containing labels for each axis, mapped to the axis name.

    Examples:
        Here is an example of how the return data can be used.
        ```
        model_datapoints, axis_labels = simple.get_data(models, 'x, y', xkey=..., ykey=...)

        # Set the axis labels
        plt.set_xlabel(axis_labels['x'])
        plt.set_ylabel(axis_labels['y'])

        # Iterate though the data and plot it
        for model_name, datapoints in model_datapoints.items():
            for dp in datapoints:
                plt.plot(dp['x'], dp['y'], label=dp['label'])
        ```

    """

    if _kwargs and kwargs:
        raise ValueError('Only one of `kwargs` or `kwargs_` can be specified.')
    else:
        kwargs = _kwargs or kwargs

    where_kwargs = utils.extract_kwargs(kwargs, prefix='where')
    models = get_models(models, where=where, where_kwargs=where_kwargs)

    if type(axis_names) is dict:
        axis_name_args = list(axis_names.keys())
        axis_key_args = list(axis_names.values())
    elif type(axis_names) is str:
        if ',' in axis_names:
            axis_name_args = list(n.strip() for n in axis_names.split(','))
        else:
            axis_name_args = list(n.strip() for n in axis_names.split())
        axis_key_args = None
    else:
        raise TypeError('``axis_name`` must be a string or a dict')

    lenargs = len(axis_name_args)
    lenmodels = len(models)

    def one_per_n(n, n_name, arg_name, arg_value):
        if isinstance(arg_value, str) or not isinstance(arg_value, Sequence):
            return [arg_value for i in range(n)]
        elif len(arg_value) == n:
            if type(arg_value) is list:
                return arg_value
            else:
                return list(arg_value)
        else:
            raise ValueError(f'Length of ``{arg_name}`` ({len(arg_value)}) must be equal to number of {n_name} ({n})')

    def one_per_arg(name, value):
        args = one_per_n(lenargs, 'axis', name, value)

        for i, axis in enumerate(axis_name_args):
            if (k:=f'{axis}{name}') in kwargs:
                args[i] = kwargs.pop(k)
            if (k:=f'{axis}{name}') in kwargs:
                args[i] = kwargs.pop(k)

        return args


    def parse_key_string(key, data_arrays):
        try:
            return utils.asisotopes(key), 'iso'
        except:
            pass

        try:
            return utils.asratios(key), 'rat'
        except:
            pass

        try:
            elements =  utils.aselements(key)
        except:
            raise ValueError(f'Unable to parse "{key}" into a sequence of valid Element, Isotope or Ratio string.')
        else:
            # Because the key list should be the same for all models we need to go through them all here
            # incase some have more or less isotopes in the specified data array
            all_isotopes = ()
            for element in elements:
                element_isotopes = []
                for data in data_arrays:
                    if not isinstance(data, (np.ndarray)) or data.dtype.fields is None:
                        raise ValueError(f'Data array "{attrname}" of model {model.name} is not a key array. '
                                         f'Cannot extract isotope keys.')

                    for iso in utils.get_isotopes_of_element(data.dtype.fields, element):
                        if iso not in element_isotopes:
                            element_isotopes.append(iso)
                all_isotopes += tuple(sorted(element_isotopes, key=lambda iso: float(iso.mass)))
            return all_isotopes, 'iso'

    def get_data_label(keylabels, keys, key_in_label, numer_in_label, denom_in_label):
        labels = []
        for key in keys:
            if type(key) is utils.Isotope:
                if key_in_label:
                    label = keylabels.get(key, f"!{key}")
                else:
                    label = ''
            elif key_in_label:
                if numer_in_label and denom_in_label:
                    label = f'{keylabels.get(key.numer, f"!{key.numer}")}/{keylabels.get(key.denom, f"!{key.denom}")} '
                elif numer_in_label:
                    label = keylabels.get(key.numer, f"!{key.numer}")
                elif denom_in_label:
                    label = keylabels.get(key.denom, f"!{key.denom}")
                else:
                    label = ''
            else:
                label = ''
            labels.append(label)
        return labels

    def get_data_index(data_array, index, mi, ai):
        try:
            return data_array[index]
        except ValueError as error:
            if isinstance(index, str):
                logger.warning(f'{models[mi]}.{attrname_a[ai]}: Missing field "{index}" replaced by the default value ({default_value})')
                return np.full(len(data_array), default_value_args[ai])
            else:
                raise error

    if axis_key_args is None:
        axis_key_args = one_per_arg('key', key)

    default_attrname_args = one_per_arg('default_attrname', default_attrname)
    desired_unit_args = one_per_arg('unit', unit)
    default_value_args = one_per_arg('default_value', default_value)
    key_in_label_args = one_per_arg('key_in_label', key_in_label)
    numer_in_label_args = one_per_arg('numer_in_label', numer_in_label)
    denom_in_label_args = one_per_arg('denom_in_label', denom_in_label)
    model_in_label_args = one_per_arg('model_in_label', model_in_label)
    unit_in_label_args = one_per_arg('unit_in_label', unit_in_label)
    attrname_in_label_args = one_per_arg('attrname_in_label', attrname_in_label)
    axis_name_in_label_args = one_per_arg('axis_name_in_label', axis_name_in_label)

    mask_args = one_per_n(lenmodels, 'models', 'mask', mask)
    mask_na_args = one_per_n(lenmodels, 'models', 'mask_na', mask_na)

    # _a -   [arg1, arg2, ...]
    # _am -  [(arg1_model1, arg1_model2, ...), (arg2_model1, arg2_model2, ...)]
    # _amk - [({arg1_model1_key1, arg1_model1_key2, ...}, {arg1_model2_key1, arg1_model2_key2, ...}), ...]
    attrname_a, keys_ak, keytype_a = [], [], []
    data_arrays_am, data_units_am = [], []
    data_label_am, data_keylabels_am = [], []
    for ai, arg in enumerate(axis_key_args):
        if type(arg) is not str:
            attrname = utils.parse_attrname(default_attrname_args[ai])
            key = arg
        else:
            if arg.startswith('.'):
                m = re.match(r'^([A-Za-z0-9_.]+)(?:\[(.*?)\])?$', arg)
                if m:
                    attrname = utils.parse_attrname(m.group(1))
                    key = m.group(2)
                    if attrname_in_label_args[ai] is None:
                        attrname_in_label_args[ai] = True
                else:
                    raise ValueError(f'Invalid arg: {key}')
            else:
                attrname = utils.parse_attrname(default_attrname_args[ai])
                key = arg

        if attrname_in_label_args[ai] is None and attrname is None:
            attrname_in_label_args[ai] = True

        attrname_a.append(attrname)

        # Here we get all the data arrays
        # For this we only need the attrname
        data_arrays_am.append([])
        data_units_am.append([])
        data_label_am.append([])
        data_keylabels_am.append([])
        for model in models:
            data, data_unit = model.get_array(attrname, desired_unit_args[ai])
            data_arrays_am[-1].append(data)
            data_units_am[-1].append(data_unit)

            attr_label, key_labels = model.get_array_labels(attrname, latex=latex_labels)
            data_label_am[-1].append(attr_label)
            data_keylabels_am[-1].append(key_labels)


        # Parse the key
        # Is the key is an element symbol it will extract all isotopes of that element from the data
        # Hence why we need to get the data arrays before this step
        if type(key) is str:
            # Check if key is an integer index or slice
            m = re.match(r'^\s*(-?\d+)\s*$|^\s*(-?\d*)\s*:\s*(-?\d*)\s*(?::\s*(-?\d*))?\s*$', key)
            if m:
                if m.group(1):
                    key = int(m.group(1))
                else:  # Slice
                    key = slice(int(m.group(2)) if m.group(2) is not None else None,
                                int(m.group(3)) if m.group(3) is not None else None,
                                int(m.group(4)) if m.group(4) is not None else None)
                key = (key,)
                keytype = 'index'

            else:
                key, keytype = parse_key_string(key, data_arrays_am[-1])
        elif type(key) is int or type(key) is slice:
            key = (key,)
            keytype = 'index'
        elif key is None:
            key = (key, )
            keytype = 'none'
        else:
            key, keytype = parse_key_string(key, data_arrays_am[-1])

        keys_ak.append(key)
        keytype_a.append(keytype)

    # Make sure the size of the keys is the same for all args
    size = {len(k) for k in keys_ak}
    size.discard(1)
    if len(size) > 1:
        raise ValueError(f'Length of indexes for not compatible {[len(k) for k in attrname_a]}')
    elif len(size) == 1:
        lenkeys = size.pop()
    else:
        lenkeys = 1

    for ai in range(lenargs):
        if len(keys_ak[ai]) != lenkeys:
            # current size can only be 1. Repeat until it is the correct length
            keys_ak[ai] = [keys_ak[ai][0] for i in range(lenkeys)]

    axis_label_args = [kwargs.pop(f'{name}label', True) for name in axis_name_args]
    axis_prefix_label_args = [kwargs.pop(f'{name}prefix_label', '') for name in axis_name_args]
    axis_suffix_label_args = [kwargs.pop(f'{name}suffix_label', '') for name in axis_name_args]
    label_args = one_per_n(lenmodels * lenkeys, 'datapoints', 'label', label)
    prefix_label_args = one_per_n(lenmodels * lenkeys, 'datapoints', 'prefix_label', prefix_label)
    suffix_label_args = one_per_n(lenmodels * lenkeys, 'datapoints', 'suffix_label', suffix_label)

    result_data = {}
    result_axis_label = {}
    data_labels_amk = []

    # Get the arg label which can be used as an axis label
    # Get the data point label for each arg. These are all combined later
    # Model name is not added. It will be added once the individual arg labels have been joined
    for ai in range(lenargs):
        keys = keys_ak[ai]
        keytype = keytype_a[ai]

        # Find common keys that can go into the arg label
        if keytype == 'iso':
            unique_keylabels = set()
            for mi, keylabels in enumerate(data_keylabels_am[ai]):
                if keylabels is None:
                    raise ValueError(f"Data array '{attrname_a[ai]}' of model '{models[mi].name}' is not a key array.")
                unique_keylabels = {*unique_keylabels, *(keylabels.get(k, None) for k in keys)}

            unique_keylabels.discard(None)
            if len(unique_keylabels) == 1: # Same label for all data points
                arg_label = unique_keylabels.pop()
                if key_in_label_args[ai] is None:
                    key_in_label_args[ai] = False
                if axis_name_in_label_args[ai] is None:
                    axis_name_in_label_args[ai] = False
            else:
                arg_label = f"<{axis_name_args[ai]}>"
                if key_in_label_args[ai] is None:
                    key_in_label_args[ai] = True
                if axis_name_in_label_args[ai] is None:
                    axis_name_in_label_args[ai] = True

        elif keytype == 'rat':
            unique_n_keylabels = {}
            unique_d_keylabels = {}
            for keylabels in data_keylabels_am[ai]:
                if keylabels is None:
                    raise ValueError(f"Data array '{attrname[ai]}' of model '{models[ai].name}' is not a key array.")

                unique_n_keylabels = {*unique_n_keylabels, *(keylabels.get(k.numer, None) for k in keys)}
                unique_d_keylabels = {*unique_d_keylabels, *(keylabels.get(k.denom, None) for k in keys)}

            unique_n_keylabels.discard(None)
            unique_d_keylabels.discard(None)

            if key_in_label_args[ai] is not None:
                if numer_in_label_args[ai] is None:
                    numer_in_label_args[ai] = key_in_label_args[ai]
                if denom_in_label_args[ai] is None:
                    denom_in_label_args[ai] = key_in_label_args[ai]

            if len(unique_n_keylabels) == 1 and len(unique_d_keylabels) == 1:
                arg_label = f"{unique_n_keylabels.pop()} / {unique_d_keylabels.pop()}"
                if key_in_label_args[ai] is None:
                    key_in_label_args[ai] = False
                if numer_in_label_args[ai] is None:
                    numer_in_label_args[ai] = False
                if denom_in_label_args[ai] is None:
                    denom_in_label_args[ai] = False
                if axis_name_in_label_args[ai] is None:
                    axis_name_in_label_args[ai] = False
            elif len(unique_n_keylabels) == 1:
                arg_label = f'{unique_n_keylabels.pop()} / <{axis_name_args[ai]}>'
                if key_in_label_args[ai] is None:
                    key_in_label_args[ai] = True
                if numer_in_label_args[ai] is None:
                    numer_in_label_args[ai] = False
                if denom_in_label_args[ai] is None:
                    denom_in_label_args[ai] = True
                if axis_name_in_label_args[ai] is None:
                    axis_name_in_label_args[ai] = True
            elif len(unique_d_keylabels) == 1:
                arg_label = f"<{axis_name_args[ai]}> / {unique_d_keylabels.pop()}"
                if key_in_label_args[ai] is None:
                    key_in_label_args[ai] = True
                if numer_in_label_args[ai] is None:
                    numer_in_label_args[ai] = True
                if denom_in_label_args[ai] is None:
                    denom_in_label_args[ai] = False
                if axis_name_in_label_args[ai] is None:
                    axis_name_in_label_args[ai] = True
            else:
                arg_label = f"<{axis_name_args[ai]}>"
                if key_in_label_args[ai] is None:
                    key_in_label_args[ai] = True
                if numer_in_label_args[ai] is None:
                    numer_in_label_args[ai] = True
                if denom_in_label_args[ai] is None:
                    denom_in_label_args[ai] = True
                if axis_name_in_label_args[ai] is None:
                    axis_name_in_label_args[ai] = True

        else:
            arg_label = ''

            # Neither are possible so just set to False
            key_in_label_args[ai] = False
            axis_name_in_label_args[ai] = False

        # Create labels for each key
        data_labels_amk.append([])
        if keytype == 'iso' or keytype == 'rat':
            for keylabels in data_keylabels_am[ai]:
                data_labels_amk[-1].append(get_data_label(keylabels, keys,
                                                          key_in_label_args[ai], numer_in_label_args[ai], denom_in_label_args[ai]))
                if attrname_in_label_args[ai] is None:
                    attrname_in_label_args[ai] = False

        else:
            # No keys so just creates an empty label
            data_labels_amk[-1].extend([['' for i in range(lenkeys)] for j in range(lenmodels)])
            if attrname_in_label_args[ai] is None:
                attrname_in_label_args[ai] = True

        # Add the unit either to arg label if common across all models or to each key label
        # [unit] added to the end of the string
        if unit_in_label_args[ai] is not False:
            unique_data_units = {*data_units_am[ai]}
            unique_data_units.discard(None)
            if len(unique_data_units) == 1:
                arg_label = f'{arg_label} [{unique_data_units.pop()}]'
            elif len(unique_data_units) > 1:
                for mi, arg_data_labels_k in enumerate(data_labels_amk[-1]):
                    for ki, key in enumerate(arg_data_labels_k):
                        if data_units_am[ai][mi] is not None:
                            data_labels_amk[-1][mi][ki] = f'{key} [{data_units_am[ai][mi]}]'.strip()

        # Add the attrname either to arg label if common across all models or to each key label
        # arrname added to the start of the string
        if attrname_in_label_args[ai]:
            unique_data_label = {*data_label_am[ai]}
            unique_data_label.discard(None)
            if len(unique_data_label) == 1:
                if arg_label == '':
                    arg_label = unique_data_label.pop().strip()
                else:
                    arg_label = f'{unique_data_label.pop()} | {arg_label}'.strip()
            elif len(unique_data_label) > 1:
                for mi, arg_data_labels_k in enumerate(data_labels_amk[-1]):
                    for ki, key in enumerate(arg_data_labels_k):
                        if data_label_am[ai][mi] is not None:
                            if key == '':
                                data_labels_amk[-1][mi][ki] = data_label_am[ai][mi].strip()
                            else:
                                data_labels_amk[-1][mi][ki] = f'{data_label_am[ai][mi]} | {key}'.strip()

        axis_label_arg = axis_label_args[ai]
        if axis_label_arg is True:
            prefix = axis_prefix_label_args[ai]
            suffix = axis_suffix_label_args[ai]
            if prefix:
                arg_label = f"{prefix}{arg_label}"
            if suffix:
                arg_label = f"{arg_label}{suffix}"

            result_axis_label[axis_name_args[ai]] = arg_label or None
        else:
            result_axis_label[axis_name_args[ai]] = axis_label_arg or None

    for mi in range(lenmodels):
        results = []
        for ki in range(lenkeys):
            results.append({})

            label = ''
            for ai in range(lenargs):
                data_array = data_arrays_am[ai][mi]
                keytype = keytype_a[ai]

                if keytype == 'rat':
                    key = keys_ak[ai][ki]
                    n = get_data_index(data_array, key.numer, mi, ai)
                    d = get_data_index(data_array, key.denom, mi, ai)
                    data = n/d

                elif keytype == 'iso' or keytype == 'index':
                    key = keys_ak[ai][ki]
                    data = get_data_index(data_array, key, mi, ai)
                else: # keytype == 'none'
                    data = data_array

                results[-1][axis_name_args[ai]] = data

                data_label = data_labels_amk[ai][mi][ki].strip()
                if data_label != '':
                    if axis_name_in_label_args[ai]:
                        label += f"<{axis_name_args[ai]}: {data_label}>"
                    else:
                        label += data_label

            if mask_args[mi] is not None:
                imask = models[mi].get_mask(mask, **results[-1])
                if mask_na_args[mi] and False not in (np.issubdtype(v.dtype, np.floating) for v in results[-1].values()):
                    for k, v in results[-1].items():
                        v = v.copy()
                        v[np.logical_not(imask)] = np.nan
                        results[-1][k] = v
                else:
                    for k, v in results[-1].items():
                        results[-1][k] = v[imask]

            label_arg = label_args[(mi * lenkeys) + ki]
            if label_arg is True:
                prefix = prefix_label_args[mi * lenkeys + ki]
                suffix = suffix_label_args[mi * lenkeys + ki]

                if model_in_label_args[ai] or (model_in_label_args[ai] is None and lenmodels > 1):
                    if label == '':
                        label = models[mi].name
                    else:
                        label = f'{label} ({models[mi].name})'.strip()
                if type(prefix) is str:
                    label = f"{prefix}{label}"
                if type(suffix) is str:
                    label = f"{label}{suffix}"

                results[-1]['label'] = label.strip() or None
            else:
                results[-1]['label'] = label_arg or None

        result_data[models[mi].name] = tuple(results)

    return result_data, result_axis_label

simple.get_isotopes_of_element

get_isotopes_of_element(isotopes, element, isotopes_without_suffix=False)

Returns a tuple of all isotopes in a sequence that contain the given element symbol.

Note The strings in isotopes will be passed through asisotopes before the evaluation and therefore do not have to be correcly formatted. Invalid isotope string are allowed but will be ignored by the evaluation.

Parameters:

• isotopes –

  An iterable of strings representing isotopes.

• element (str) –

  The element symbol.

• suffix (str) –

  If given the isotopes must also have this suffix.

• isotopes_without_suffix (bool, default: False ) –

  If True suffixes will be removed from the isotopes in isotopes before the evaluation takes place.

Examples:

>>> simple.utils.get_isotopes_of_element(["Ru-101", "Pd-102", "Rh-103", "Pd-104"], "Pd")
>>> ("Pd-102", "Pd-104")

Source code in simple/utils.py

def get_isotopes_of_element(isotopes, element, isotopes_without_suffix=False):
    """
    Returns a tuple of all isotopes in a sequence that contain the given element symbol.

    **Note** The strings in ``isotopes`` will be passed through [asisotopes][simple.asisotopes] before
    the evaluation and therefore do not have to be correcly formatted. Invalid isotope string are allowed
    but will be ignored by the evaluation.

    Args:
        isotopes (): An iterable of strings representing isotopes.
        element (str): The element symbol.
        suffix (str): If given the isotopes must also have this suffix.
        isotopes_without_suffix (bool): If ``True`` suffixes will be removed from the isotopes in ``isotopes``
            before the evaluation takes place.

    Examples:
        >>> simple.utils.get_isotopes_of_element(["Ru-101", "Pd-102", "Rh-103", "Pd-104"], "Pd")
        >>> ("Pd-102", "Pd-104")
    """
    isotopes = asisolist(isotopes, without_suffix=isotopes_without_suffix, allow_invalid=True)
    element = aselement(element)
    return tuple(iso for iso in isotopes if (type(iso) is Isotope and iso.element == element))

simple.load_collection

load_collection(filename, dbfilename=None, *, default_isolist=None, convert_unit=True, overwrite=False, where=None, **where_kwargs)

Loads a selection of models from a file.

If that file does not exist it will create the file from the specified models file. Only when doing this is the default_isolist applied. If filename already exits the assumption is it has the correct isolist.

*Notes

The entire file will be read into memory. This might be an issue if reading very large files. The hdf5 are compressed so will be significantly larger when stored in memory.

When reading the database file to create a subselection of the data using default_isolist, the subselection is made when each model is loaded which reduces the amount of memory used.

Parameters:

• filename (str) –

  Name of the file to load or create.

• dbfilename (str, default: None ) –

  Name of the raw models file

• default_isolist –

  Isolist applied to loaded models from dbfilename.

• convert_units (bool) –

  If True and data is stored in a mass unit all values will be divided by the mass number of the isotope before summing values together. The final value is then multiplied by the mass number of the output isotope.

• overwrite (bool, default: False ) –

  If True a new file will be created even if filename already exists.

• where (str, default: None ) –

  Used to select which models to load.

• **where_kwargs –

  Keyword arguments used in combination with where.

Returns:

• –

  A ModelCollection object containing all the loaded models.

Source code in simple/models.py

def load_collection(filename, dbfilename=None, *, default_isolist=None, convert_unit=True, overwrite=False,
                    where=None, **where_kwargs):
    """
    Loads a selection of models from a file.

    If that file does not exist it will create the file from the specified models file. Only when doing this
    is the ``default_isolist`` applied. If ``filename`` already exits the **assumption** is it has the correct isolist.

    ***Notes**

    The entire file will be read into memory. This might be an issue if reading very large files. The hdf5 are
    compressed so will be significantly larger when stored in memory.

    When reading the database file to create a subselection of the data using ``default_isolist``, the subselection is
     made when each model is loaded which reduces the amount of memory used.

    Args:
        filename (str): Name of the file to load or create.
        dbfilename (str): Name of the raw models file
        default_isolist (): Isolist applied to loaded models from ``dbfilename``.
        convert_units (bool): If ``True``  and data is stored in a mass unit all values will be divided by the
            mass number of the isotope before summing values together. The final value is then multiplied by the
            mass number of the output isotope.
        overwrite (bool): If ``True`` a new file will be created even if ``filename`` already exists.
        where (str): Used to select which models to load.
        **where_kwargs (): Keyword arguments used in combination with ``where``.

    Returns:
        A [ModelCollection][simple.models.ModelCollection] object containing all the loaded models.
    """
    mc = ModelCollection()
    if os.path.exists(filename) and not overwrite:
        logger.info(f'Loading existing file: {filename}')
        mc.load_file(filename, where=where, **where_kwargs)
    elif filename[-5:].lower() != '.hdf5' and os.path.exists(f'{filename}.hdf5') and not overwrite:
        logger.info(f'Loading existing file: {filename}.hdf5')
        mc.load_file(f'{filename}.hdf5', where=where, **where_kwargs)
    elif dbfilename is None:
        raise ValueError(f'File {filename} does not exist')
    elif os.path.exists(dbfilename):
        logger.info(f'Creating: "{filename}" from database: "{dbfilename}"')
        mc.load_file(dbfilename, isolist=default_isolist, convert_unit=convert_unit, where=where, **where_kwargs)
        mc.save(filename)
    else:
        raise ValueError(f'Neither "{filename}" or "{dbfilename}" exist')
    return mc

simple.load_defaults

load_defaults(filename)

Loads default arguments for functions from a YAML formatted file.

To use a set of default values, unpack the arguments in the function call (See example).

You can still arguments and keyword arguments as normal as long as they are not included in the default dictionary.

Returns:

• –

  A named dictionary containing mapping the prefixes given in the yaml file to another dictionary mapping the arguments

• –

  to the specified values.

Examples:

The file default.yaml is expected to look like this:

somefunction:
    arg: value
    listarg:
        - first thing in list
        - second thing in list

anotherfunction:
    arg: value

It can be used like this

>>> defaults = simple.load_defaults('defaults.yaml')
>>> somefunction(**defaults['somefunction']) # Unpack arguments into function call

Source code in simple/utils.py

def load_defaults(filename: str):
    """
    Loads default arguments for functions from a YAML formatted file.

    To use a set of default values, unpack the arguments in the function call (See example).

    You can still arguments and keyword arguments as normal as long as they are not included in the default dictionary.

    Returns:
        A named dictionary containing mapping the prefixes given in the yaml file to another dictionary mapping the arguments
        to the specified values.

    Examples:
        The file ``default.yaml`` is expected to look like this:
        ```
        somefunction:
            arg: value
            listarg:
                - first thing in list
                - second thing in list

        anotherfunction:
            arg: value
        ```

        It can be used like this
        >>> defaults = simple.load_defaults('defaults.yaml')
        >>> somefunction(**defaults['somefunction']) # Unpack arguments into function call


    """
    return dict(yaml.safe_load(open(filename, 'r').read()))

simple.mcontour

mcontour(models, xkey, ykey, r=None, weights=1, *, default_attrname=None, unit=None, weights_default_attrname=None, weights_unit=None, weights_default_value=0, mask=None, ax=None, where=None, where_kwargs={}, legend=None, update_ax=True, update_fig=True, **kwargs)

Contour plot on a rose diagram.

Source code in simple/plotting.py

@utils.add_shortcut('stdnorm', default_attrname ='stdnorm.Ri', unit=None)
@utils.add_shortcut('intnorm', default_attrname='intnorm.eRi', unit=None)
@utils.set_default_kwargs(
    ax_kw_ylabel_labelpad=20,
    legend_outside=True,
    rose_colorbar_show=False, bar_outline=True,
    linestyle=True, color=True, marker=False,
    fixed_model_linestyle = None, fixed_model_color = None, fixed_model_marker = None
)
def mcontour(models, xkey, ykey, r=None, weights=1, *,
             default_attrname = None, unit=None,
             weights_default_attrname = None, weights_unit=None, weights_default_value=0,
             mask = None, ax = None, where=None, where_kwargs={},
             legend=None, update_ax = True, update_fig = True,
             **kwargs):
    """
    Contour plot on a rose diagram.
    """
    ax, models, r, modeldata_xy, modeldata_w, kwargs = _mprep(models, xkey, ykey, r, weights,
                                                            default_attrname=default_attrname, unit=unit,
                                                            weights_default_attrname=weights_default_attrname,
                                                            weights_unit=weights_unit, weights_default_value=weights_default_value,
                                                            mask=mask, ax=ax, where=where, where_kwargs=where_kwargs,
                                                            **kwargs)

    return _mcontour(ax, r, modeldata_xy, modeldata_w, legend=legend, update_ax=update_ax, update_fig=update_fig, **kwargs)

simple.mcontour_ccsne

mcontour_ccsne(models, xkey, ykey, r=None, weights=1, **kwargs)

Contour plot on a rose diagram for CCNSe models.

Source code in simple/ccsne.py

@utils.add_shortcut('abundance', default_attrname='abundance', unit='mass', xunit=None)
@utils.add_shortcut('intnorm', default_attrname='intnorm.eRi', unit=None, xunit=None)
@utils.add_shortcut('stdnorm', default_attrname='stdnorm.Ri', unit=None, xunit=None)
@utils.set_default_kwargs(inherits=plotting.mcontour,
    weights_default_attrname='abundance', weights_unit='mass',
)
def mcontour_ccsne(models, xkey, ykey, r=None, weights=1, **kwargs):
    """
    Contour plot on a rose diagram for CCNSe models.
    """
    ax, models, r, modeldata_xy, modeldata_w, kwargs = plotting._mprep(models, xkey, ykey, r, weights, **kwargs)
    modeldata_w = _mweights(models, modeldata_w)
    return plotting._mcontour(ax, r, modeldata_xy, modeldata_w, **kwargs)

simple.mhist

mhist(models, xkey, ykey, r=None, weights=1, *, default_attrname=None, unit=None, weights_default_attrname=None, weights_unit=None, weights_default_value=0, mask=None, ax=None, where=None, where_kwargs={}, legend=None, update_ax=True, update_fig=True, **kwargs)

Histogram plot on a rose diagram.

Source code in simple/plotting.py

@utils.add_shortcut('stdnorm', default_attrname ='stdnorm.Ri', unit=None)
@utils.add_shortcut('intnorm', default_attrname='intnorm.eRi', unit=None)
@utils.set_default_kwargs(
    ax_kw_ylabel_labelpad=20,
    rose_colorbar_show=True,
    legend_outside=True,)
def mhist(models, xkey, ykey, r=None, weights=1, *,
          default_attrname = None, unit=None,
          weights_default_attrname = None, weights_unit=None, weights_default_value=0,
          mask = None, ax = None, where=None, where_kwargs={},
          legend=None, update_ax = True, update_fig = True,
          **kwargs):
    """
    Histogram plot on a rose diagram.
    """
    ax, models, r, modeldata_xy, modeldata_w, kwargs = _mprep(models, xkey, ykey, r, weights,
                                                      default_attrname=default_attrname, unit=unit,
                                                      weights_default_attrname=weights_default_attrname,
                                                      weights_unit=weights_unit, weights_default_value=weights_default_value,
                                                      mask=mask, ax=ax, where=where, where_kwargs=where_kwargs,
                                                      **kwargs)

    return _mhist(ax, r, modeldata_xy, modeldata_w, legend=legend, update_ax=update_ax, update_fig=update_fig, **kwargs)

simple.mhist_ccsne

mhist_ccsne(models, xkey, ykey, r=None, weights=1, **kwargs)

Histogram plot on a rose diagram for CCNSe models.

Source code in simple/ccsne.py

@utils.add_shortcut('abundance', default_attrname='abundance', unit='mass', xunit=None)
@utils.add_shortcut('intnorm', default_attrname='intnorm.eRi', unit=None, xunit=None)
@utils.add_shortcut('stdnorm', default_attrname='stdnorm.Ri', unit=None, xunit=None)
@utils.set_default_kwargs(inherits=plotting.mhist,
    weights_default_attrname='abundance', weights_unit='mass',
)
def mhist_ccsne(models, xkey, ykey, r=None, weights=1, **kwargs):
    """
    Histogram plot on a rose diagram for CCNSe models.
    """
    ax, models, r, modeldata_xy, modeldata_w, kwargs = plotting._mprep(models, xkey, ykey, r, weights, **kwargs)
    modeldata_w = _mweights(models, modeldata_w)
    return plotting._mhist(ax, r, modeldata_xy, modeldata_w, **kwargs)

simple.new_collection

new_collection()

Return an empty ModelCollection object.

Source code in simple/models.py

def new_collection():
    """
    Return an empty [ModelCollection][simple.models.ModelCollection] object.
    """
    return ModelCollection()

simple.plot

plot(models, xkey, ykey, *, default_attrname=None, unit=None, where=None, mask=None, mask_na=True, ax=None, legend=None, update_ax=True, update_fig=True, **kwargs)

Plot xkey against ykey for each model in `models.

It is possible to plot multiple datasets if xkey and/or ykey is a list of multiple keys for a isotope key array. If only one of the arguments is a list then the second argument will be reused for each dataset. If a key is not present in an array then a default value is used. See get_data for more details.

The data to be plotted is retrieved using the get_data function. All arguments available for that function not included in the argument list here can be given as one of the kwargs to this function.

The data will be plotted using matplotlib's plot function. Additional arguments to this function can be passed as one of the kwargs to this function. Some plot arguments have enhanced behaviour detailed in a section below.

Parameters:

• models –

  A collection of models to plot. A subselection of these models can be made using the where argument.

• xkey, (ykey (str, int, slice) –

  This can either be a valid index to the default_attrname array or the path, with or without a valid index, of a different attribute. See get_data for more details.

• default_attrname (str, default: None ) –

  The name of the default attribute to use if xkey and ykey are indexes.

• unit (str, default: None ) –

  The desired unit for the xkey and ykey. Different units for xkey and ykey can be specified by supplying a (<xkey_unit>, <ykey_unit>) sequence.

• where (str, default: None ) –

  If given will be used to create a subselection of models. Any kwargs prefixed with where_ will be supplied as keyword arguments. See ModelCollection.where for more details.

• mask ((str, int, slice), default: None ) –

  Can be used to apply a mask to the data which is plotted. See the get_mask function of the Model object.

• mask_na (bool, default: True ) –

  If True masked values will be replaced by np.nan values. Only works if both xkey and ykey have a float based datatype.

• ax –

  The axes where the data is plotted. Accepted values are any matplotlib Axes object or plt instance. Defaults to plt.gca().

• legend (bool, default: None ) –

  Whether to create a legend. By default, a legend will be created if one or more datapoints have a valid label.

• update_ax, (update_fig (bool) –

  Whether to update the axes and figure objects using kwargs that have the prefix ax_ and fig_. See simple.plotting.update_axes for more details.

• **kwargs –

  Valid keyword arguments are those using one of the prefixes define by other arguments, any argument for the simple.get_data function, or any valid keyword argument for matplotlib's plot function.

Data and axis labels

Labels for each axis and individual datapoints will be automatically generated. By default, the axis labels will contain the information common to all datasets while the label for the individual datapoints will contain only the unique information. You can override the axis labels by passing ax_xlabel and ax_ylabel as one of the kwargs. You can also override the datapoint labels by passing a list of labels, one each for each datapoint in the legend. See get_data for more details on customising the labels.

Iterable plot arguments

The following arguments for matplotlibs plot function have enhanced behaviour that allows them to be iterated through when plotting different models and/or datasets.

• linestyle Can be a list of linestyles that will be iterated through. If True simple's predefined list of linestyles is used. If False no lines will be shown.

• color Can be a list of colors that will be iterated through. If True simple's predefined list of colors is used. If False the colour defaults to black.

• marker Can be a list of markers that will be iterated through. If True simple's predefined list of markers is used. If False no markers will be shown.

There are two ways these values can be iterated through. Either all the datapoints of a given model gets the same value or each set of datapoints across the different models gets the same value. By default, if there are multiple models then all the datasets for each model will have the same color. If there is only one model then the color will be different for the different datasets. If there are multiple datasets then each dataset across the different models will have the same linestyle and marker. If there is only one dataset then linestyle and marker will be different for each model.

This behaviour can be changed by passing fixed_model_linestyle, fixed_model_color and fixed_model_marker keyword arguments set to either True or False If True each model will have the same value. If False each dataset across the different models will have the same value.

Default kwargs and shortcuts

The default values for arguments can be updated by changing the plot.default_kwargs dictionary. Any argument not defined in the function description will be included in kwargs. Default values given in the function definition will be used only if a default value does not exist in plot.default_kwargs. Additionally, one or more shortcuts with additional/different default values are attached to this function. The following shortcuts exist for this function:

• plot.intnorm Default values to plot internally normalised data. This sets default_attrname to intnorm and the default_unit to None.

• plot.stdnorm Default values to plot the basic ratio normalised data. This sets default_attrname to stdnorm and the default_unit to None.

Returns:

• –

  The axes where the data was plotted.

Source code in simple/plotting.py

@utils.add_shortcut('abundance', default_attrname ='abundance', unit=None)
@utils.add_shortcut('stdnorm', default_attrname ='stdnorm.Ri', unit=None)
@utils.add_shortcut('intnorm', default_attrname='intnorm.eRi', unit=None)
@utils.set_default_kwargs(
    linestyle=False, color=True, marker=True,
    fixed_model_linestyle = None, fixed_model_color = None, fixed_model_marker = None,
    ax_kw_xlabel_fontsize=15,
    ax_kw_ylabel_fontsize=15,
    markersize=4,
    legend_outside=True,
    ax_tick_params=dict(axis='both', left=True, right=True, top=True),
    fig_size=(7,6.5),
    )
def plot(models, xkey, ykey, *,
         default_attrname=None, unit=None,
         where=None, mask = None, mask_na = True, ax = None,
         legend = None, update_ax = True, update_fig = True,
         **kwargs):
    """
    Plot *xkey* against *ykey* for each model in `*models*.

    It is possible to plot multiple datasets if *xkey* and/or *ykey* is a list of multiple keys for a isotope key
    array. If only one of the arguments is a list then the second argument will be reused for each dataset. If a key
    is not present in an array then a default value is used. See [``get_data``](simple.get_data) for more details.

    The data to be plotted is retrieved using the [``get_data``](simple.get_data) function. All arguments available
    for that function not included in the argument list here can be given as one of the *kwargs* to this function.

    The data will be plotted using matplotlib's ``plot`` function. Additional arguments to this function can be
    passed as one of the *kwargs* to this function. Some  ``plot`` arguments have enhanced behaviour detailed in a
    section below.

    Args:
        models (): A collection of models to plot. A subselection of these models can be made using the *where*
            argument.
        xkey, ykey (str, int, slice): This can either be a valid index to the *default_attrname* array or the path, with
            or without a valid index, of a different attribute. See [``get_data``](simple.get_data) for more details.
        default_attrname (str): The name of the default attribute to use if *xkey* and *ykey* are indexes.
        unit (str): The desired unit for the *xkey* and *ykey*. Different units for *xkey* and *ykey* can be specified
            by supplying a ``(<xkey_unit>, <ykey_unit>)`` sequence.
        where (str): If given will be used to create a subselection of *models*. Any *kwargs* prefixed
            with ``where_`` will be supplied as keyword arguments. See
             [``ModelCollection.where``](simple.models.ModelCollection.where) for more details.
        mask (str, int, slice): Can be used to apply a mask to the data which is plotted. See the ``get_mask`` function of the Model
            object.
        mask_na (bool): If ``True`` masked values will be replaced by ``np.nan`` values. Only works if both *xkey* and
            *ykey* have a float based datatype.
        ax (): The axes where the data is plotted. Accepted values are any matplotlib Axes object or plt instance.
            Defaults to ``plt.gca()``.
        legend (bool): Whether to create a legend. By default, a legend will be created if one or more datapoints have
            a valid label.
        update_ax, update_fig (bool): Whether to update the axes and figure objects using kwargs that have the prefix
            ``ax_`` and ``fig_``. See [``simple.plotting.update_axes``](simple.plotting.update_axes) for more details.
        **kwargs ():
            Valid keyword arguments are those using one of the prefixes define by other arguments, any argument
            for the [``simple.get_data``](simple.get_data) function, or any valid keyword argument for
            matplotlib's ``plot`` function.

    Data and axis labels:
        Labels for each axis and individual datapoints will be automatically generated. By default, the axis labels
        will contain the information common to all datasets while the label for the individual datapoints will contain
        only the unique information. You can override the axis labels by passing ``ax_xlabel`` and ``ax_ylabel`` as
        one of the *kwargs*. You can also override the datapoint labels by passing a list of labels, one each
        for each datapoint in the legend. See [``get_data``](simple.get_data) for more details on customising the
        labels.


    Iterable plot arguments:
        The following arguments for matplotlibs ``plot`` function have enhanced behaviour that allows them to be
        iterated through when plotting different models and/or datasets.

        - ``linestyle`` Can be a list of linestyles that will be iterated through. If ``True`` simple's predefined
        list of linestyles is used. If ``False`` no lines will be shown.

        - ``color`` Can be a list of colors that will be iterated through. If ``True`` simple's predefined
        list of colors is used. If ``False`` the colour defaults to black.

        - ``marker`` Can be a list of markers that will be iterated through. If ``True`` simple's predefined
        list of markers is used. If ``False`` no markers will be shown.

        There are two ways these values can be iterated through. Either all the datapoints of a given model gets the
        same value or each set of datapoints across the different models gets the same value. By default, if there are
        multiple models then all the datasets for each model will have the same *color*. If there is only one model
        then the color will be different for the different datasets. If there are multiple datasets then each dataset
        across the different models will have the same *linestyle* and *marker*. If there is only one dataset then
        *linestyle* and *marker* will be different for each model.

        This behaviour can be changed by passing ``fixed_model_linestyle``, ``fixed_model_color``
        and ``fixed_model_marker`` keyword arguments set to either ``True`` or ``False`` If ``True`` each model will
        have the same value. If ``False`` each dataset across the different models will have the same value.

    Default kwargs and shortcuts:
        The default values for arguments can be updated by changing the  ``plot.default_kwargs`` dictionary. Any
        argument not defined in the function description will be included in *kwargs*. Default values given in the
        function definition will be used only if a default value does not exist in ``plot.default_kwargs``.
        Additionally, one or more shortcuts with additional/different default values are attached to this function.
        The following shortcuts exist for this function:

        - ``plot.intnorm`` Default values to plot internally normalised data. This sets *default_attrname* to
            ``intnorm`` and the ``default_unit`` to ``None``.

        - ``plot.stdnorm`` Default values to plot the basic ratio normalised data. This sets
                *default_attrname* to ``stdnorm`` and the ``default_unit`` to ``None``.

    Returns:
        The axes where the data was plotted.
    """
    ax = get_axes(ax)  # We are working on the axes object proper

    where_kwargs = utils.extract_kwargs(kwargs, prefix='where')
    models = get_models(models, where=where, where_kwargs=where_kwargs)

    # Get the linestyle, color and marker for each thing to be plotted.
    linestyles, colors, markers = parse_lscm(kwargs.pop('linestyle', True),
                                             kwargs.pop('color', True),
                                             kwargs.pop('marker', False))
    fixed_model_linestyle = kwargs.pop('fixed_model_linestyle', None)
    fixed_model_color = kwargs.pop('fixed_model_color', None)
    fixed_model_marker = kwargs.pop('fixed_model_marker', None)

    legend_kwargs = utils.extract_kwargs(kwargs, prefix='legend')

    label_kwargs = utils.extract_kwargs(kwargs, 'label', 'prefix_label', 'suffix_label',
                                        'key_in_label', 'numer_in_label', 'denom_in_label',
                                        'model_in_label', 'unit_in_label', 'attrname_in_label')

    # If there is only one model it is set as the title to make the legend shorter
    model_in_label = label_kwargs.pop('model_in_label', None)
    if len(models) == 1 and model_in_label is None:
        label_kwargs['model_in_label'] = False
        legend_kwargs.setdefault('title', models[0].name)
    else:
        label_kwargs['model_in_label'] = model_in_label


    modeldata, axis_labels = get_data(models, {'x': xkey, 'y': ykey},
                                      default_attrname=default_attrname, unit=unit,
                                      mask=mask, mask_na=mask_na, _kwargs=kwargs, **label_kwargs)

    kwargs.setdefault('ax_xlabel', axis_labels['x'])
    kwargs.setdefault('ax_ylabel', axis_labels['y'])
    delayed_kwargs = update_axes(ax, kwargs, delay='ax_legend', update_ax=update_ax, update_fig=update_fig)

    mfc = kwargs.pop('markerfacecolor', None)

    has_labels = False
    for mi, (model_name, model_dataset) in enumerate(modeldata.items()):
        for ki, key_data in enumerate(model_dataset):
            if fixed_model_linestyle or (fixed_model_linestyle is None and len(model_dataset) == 1):
                ls = linestyles[mi]
            else:
                ls = linestyles[ki]
            if fixed_model_color is True or (fixed_model_color is None and len(modeldata) > 1):
                c = colors[mi]
            else:
                c = colors[ki]
            if fixed_model_marker is True or (fixed_model_marker is None and len(model_dataset) == 1):
                m = markers[mi]
            else:
                m = markers[ki]

            if not has_labels and key_data.get('label', None):
                has_labels = True

            ax.plot(key_data['x'], key_data['y'],
                    label = key_data.get('label', None),
                    color=c, ls=ls, marker=m,
                    markerfacecolor=mfc or c,
                    **kwargs)

    update_axes(ax, delayed_kwargs, update_ax=update_ax, update_fig=update_fig)
    if legend or (legend is None and has_labels):
        create_legend(ax, **legend_kwargs)

    return ax

simple.plot_ccsne

plot_ccsne(models, ykey, *, semilog=False, onion=None, **kwargs)

Plot for CCSNe models. Plots the mass coordinates on the x-axis.

Source code in simple/ccsne.py

@utils.add_shortcut('abundance', default_attrname='abundance', unit='mass')
@utils.add_shortcut('intnorm', default_attrname='intnorm.eRi', unit=None)
@utils.add_shortcut('stdnorm', default_attrname='stdnorm.Ri', unit=None)
@utils.set_default_kwargs(inherits=plotting.plot,
    linestyle = True, color=True, marker=False,
    fig_size= (10,5))
def plot_ccsne(models, ykey, *,
         semilog = False, onion=None,
         **kwargs):
    """
    Plot for CCSNe models. Plots the mass coordinates on the x-axis.
    """
    # Wrapper that adds the option to plot the onion structure of CCSNe models
    onion_kwargs = utils.extract_kwargs(kwargs, prefix='onion')

    # Do this here since we need to know the number of models for the onion shell
    where = kwargs.pop('where', None)
    where_kwargs = kwargs.pop('where_kwargs', {})
    where_kwargs.update(utils.extract_kwargs(kwargs, prefix='where'))
    models = plotting.get_models(models, where=where, where_kwargs=where_kwargs)

    if semilog: kwargs.setdefault('ax_yscale', 'log')

    ax = plotting.plot(models, '.masscoord', ykey, xunit=None, **kwargs)

    if onion or (onion is None and len(models) == 1):
        if len(models) > 1:
            raise ValueError(f"Can only plot onion structure for a single model")
        else:
            plot_onion_structure(models[0], ax=ax, **onion_kwargs)

    return ax

simple.plotm

plotm(models, xkey, ykey, xycoord=(0, 0), *, arrow=True, arrow_position=0.9, default_attrname=None, unit=None, where=None, mask=None, mask_na=True, ax=None, legend=None, update_ax=True, update_fig=True, **kwargs)

Plot the slope of ykey / xkey for each model in `models.

It is possible to plot multiple datasets if xkey and/or ykey is a list of multiple keys for a isotope key array. If only one of the arguments is a list then the second argument will be reused for each dataset. If a key is not present in an array then a default value is used. See get_data for more details.

The data to be plotted is retrieved using the get_data function. All arguments available for that function not included in the argument list here can be given as one of the kwargs to this function.

The data will be plotted using matplotlib's axline function. Additional arguments to this function can be passed as one of the kwargs to this function. Some arguments have enhanced behaviour detailed in a section below.

Parameters:

• models –

  A collection of models to plot. A subselection of these models can be made using the where argument.

• xkey, (ykey (str, int, slice) –

  This can either be a valid index to the default_attrname array or the path, with or without a valid index, of a different attribute. See get_data for more details.

• default_attrname (str, default: None ) –

  The name of the default attribute to use if xkey and ykey are indexes.

• unit (str, default: None ) –

  The desired unit for the xkey and ykey. Different units for xkey and ykey can be specified by supplying a (<xkey_unit>, <ykey_unit>) sequence.

• where (str, default: None ) –

  If given will be used to create a subselection of models. Any kwargs prefixed with where_ will be supplied as keyword arguments. See ModelCollection.where for more details.

• mask ((str, int, slice), default: None ) –

  Can be used to apply a mask to the data which is plotted. See the get_mask function of the Model object.

• mask_na (bool, default: True ) –

  If True masked values will be replaced by np.nan values. Only works if both xkey and ykey have a float based datatype.

• ax –

  The axes where the data is plotted. Accepted values are any matplotlib Axes object or plt instance. Defaults to plt.gca().

• legend (bool, default: None ) –

  Whether to create a legend. By default, a legend will be created if one or more datapoints have a valid label.

• update_ax, (update_fig (bool) –

  Whether to update the axes and figure objects using kwargs that have the prefix ax_ and fig_. See simple.plotting.update_axes for more details.

• **kwargs –

  Valid keyword arguments are those using one of the prefixes define by other arguments, any argument for the simple.get_data function, or any valid keyword argument for matplotlib's plot function.

Data and axis labels

Labels for each axis and individual datapoints will be automatically generated. By default, the axis labels will contain the information common to all datasets while the label for the individual datapoints will contain only the unique information. You can override the axis labels by passing ax_xlabel and ax_ylabel as one of the kwargs. You can also override the datapoint labels by passing a list of labels, one each for each datapoint in the legend. See get_data for more details on customising the labels.

Iterable plot arguments

The following arguments for matplotlibs plot function have enhanced behaviour that allows them to be iterated through when plotting different models and/or datasets.

• linestyle Can be a list of linestyles that will be iterated through. If True simple's predefined list of linestyles is used. If False no lines will be shown.

• color Can be a list of colors that will be iterated through. If True simple's predefined list of colors is used. If False the colour defaults to black.

There are two ways these values can be iterated through. Either all the datapoints of a given model gets the same value or each set of datapoints across the different models gets the same value. By default, if there are multiple models then all the datasets for each model will have the same color. If there is only one model then the color will be different for the different datasets. If there are multiple datasets then each dataset across the different models will have the same linestyle and marker. If there is only one dataset then linestyle and marker will be different for each model.

This behaviour can be changed by passing fixed_model_linestyle, fixed_model_color and fixed_model_marker keyword arguments set to either True or False If True each model will have the same value. If False each dataset across the different models will have the same value.

Default kwargs and shortcuts

The default values for arguments can be updated by changing the plot.default_kwargs dictionary. Any argument not defined in the function description will be included in kwargs. Default values given in the function definition will be used only if a default value does not exist in plot.default_kwargs. Additionally, one or more shortcuts with additional/different default values are attached to this function. The following shortcuts exist for this function:

• plotm.intnorm Default values to plot internally normalised data. This sets default_attrname to intnorm and the default_unit to None.

• plotm.stdnorm Default values to plot the basic ratio normalised data. This sets default_attrname to stdnorm and the default_unit to None.

Returns:

• –

  The axes where the data was plotted.

Source code in simple/plotting.py

@utils.add_shortcut('abundance', default_attrname ='abundance', unit=None)
@utils.add_shortcut('stdnorm', default_attrname ='stdnorm.Ri', unit=None)
@utils.add_shortcut('intnorm', default_attrname='intnorm.eRi', unit=None)
@utils.set_default_kwargs(
    linestyle=True, color=True,
    fixed_model_linestyle = None, fixed_model_color = None,
    ax_kw_xlabel_fontsize=15,
    ax_kw_ylabel_fontsize=15,
    markersize=4,
    legend_outside=True,
    ax_tick_params=dict(axis='both', left=True, right=True, top=True),
    fig_size=(7,6.5),
    arrow_linewidth=0, arrow_length_includes_head=True, arrow_head_width=0.05,
    arrow_zorder=3
    )
def plotm(models, xkey, ykey, xycoord=(0,0), *,
         arrow=True, arrow_position=0.9,
         default_attrname=None, unit=None,
         where=None, mask = None, mask_na = True, ax = None,
         legend = None, update_ax = True, update_fig = True,
         **kwargs):
    """
    Plot the slope of *ykey* / *xkey* for each model in `*models*.

    It is possible to plot multiple datasets if *xkey* and/or *ykey* is a list of multiple keys for a isotope key
    array. If only one of the arguments is a list then the second argument will be reused for each dataset. If a key
    is not present in an array then a default value is used. See [``get_data``](simple.get_data) for more details.

    The data to be plotted is retrieved using the [``get_data``](simple.get_data) function. All arguments available
    for that function not included in the argument list here can be given as one of the *kwargs* to this function.

    The data will be plotted using matplotlib's ``axline`` function. Additional arguments to this function can be
    passed as one of the *kwargs* to this function. Some arguments have enhanced behaviour detailed in a
    section below.

    Args:
        models (): A collection of models to plot. A subselection of these models can be made using the *where*
            argument.
        xkey, ykey (str, int, slice): This can either be a valid index to the *default_attrname* array or the path, with
            or without a valid index, of a different attribute. See [``get_data``](simple.get_data) for more details.
        default_attrname (str): The name of the default attribute to use if *xkey* and *ykey* are indexes.
        unit (str): The desired unit for the *xkey* and *ykey*. Different units for *xkey* and *ykey* can be specified
            by supplying a ``(<xkey_unit>, <ykey_unit>)`` sequence.
        where (str): If given will be used to create a subselection of *models*. Any *kwargs* prefixed
            with ``where_`` will be supplied as keyword arguments. See
             [``ModelCollection.where``](simple.models.ModelCollection.where) for more details.
        mask (str, int, slice): Can be used to apply a mask to the data which is plotted. See the ``get_mask`` function of the Model
            object.
        mask_na (bool): If ``True`` masked values will be replaced by ``np.nan`` values. Only works if both *xkey* and
            *ykey* have a float based datatype.
        ax (): The axes where the data is plotted. Accepted values are any matplotlib Axes object or plt instance.
            Defaults to ``plt.gca()``.
        legend (bool): Whether to create a legend. By default, a legend will be created if one or more datapoints have
            a valid label.
        update_ax, update_fig (bool): Whether to update the axes and figure objects using kwargs that have the prefix
            ``ax_`` and ``fig_``. See [``simple.plotting.update_axes``](simple.plotting.update_axes) for more details.
        **kwargs ():
            Valid keyword arguments are those using one of the prefixes define by other arguments, any argument
            for the [``simple.get_data``](simple.get_data) function, or any valid keyword argument for
            matplotlib's ``plot`` function.

    Data and axis labels:
        Labels for each axis and individual datapoints will be automatically generated. By default, the axis labels
        will contain the information common to all datasets while the label for the individual datapoints will contain
        only the unique information. You can override the axis labels by passing ``ax_xlabel`` and ``ax_ylabel`` as
        one of the *kwargs*. You can also override the datapoint labels by passing a list of labels, one each
        for each datapoint in the legend. See [``get_data``](simple.get_data) for more details on customising the
        labels.


    Iterable plot arguments:
        The following arguments for matplotlibs ``plot`` function have enhanced behaviour that allows them to be
        iterated through when plotting different models and/or datasets.

        - ``linestyle`` Can be a list of linestyles that will be iterated through. If ``True`` simple's predefined
        list of linestyles is used. If ``False`` no lines will be shown.

        - ``color`` Can be a list of colors that will be iterated through. If ``True`` simple's predefined
        list of colors is used. If ``False`` the colour defaults to black.

        There are two ways these values can be iterated through. Either all the datapoints of a given model gets the
        same value or each set of datapoints across the different models gets the same value. By default, if there are
        multiple models then all the datasets for each model will have the same *color*. If there is only one model
        then the color will be different for the different datasets. If there are multiple datasets then each dataset
        across the different models will have the same *linestyle* and *marker*. If there is only one dataset then
        *linestyle* and *marker* will be different for each model.

        This behaviour can be changed by passing ``fixed_model_linestyle``, ``fixed_model_color``
        and ``fixed_model_marker`` keyword arguments set to either ``True`` or ``False`` If ``True`` each model will
        have the same value. If ``False`` each dataset across the different models will have the same value.

    Default kwargs and shortcuts:
        The default values for arguments can be updated by changing the  ``plot.default_kwargs`` dictionary. Any
        argument not defined in the function description will be included in *kwargs*. Default values given in the
        function definition will be used only if a default value does not exist in ``plot.default_kwargs``.
        Additionally, one or more shortcuts with additional/different default values are attached to this function.
        The following shortcuts exist for this function:

        - ``plotm.intnorm`` Default values to plot internally normalised data. This sets *default_attrname* to
            ``intnorm`` and the ``default_unit`` to ``None``.

        - ``plotm.stdnorm`` Default values to plot the basic ratio normalised data. This sets
                *default_attrname* to ``stdnorm`` and the ``default_unit`` to ``None``.

    Returns:
        The axes where the data was plotted.
    """
    ax = get_axes(ax)  # We are working on the axes object proper

    where_kwargs = utils.extract_kwargs(kwargs, prefix='where')
    models = get_models(models, where=where, where_kwargs=where_kwargs)

    # Get the linestyle, color and marker for each thing to be plotted.
    linestyles, colors, markers = parse_lscm(kwargs.pop('linestyle', True),
                                             kwargs.pop('color', True),
                                             kwargs.pop('marker', False))
    fixed_model_linestyle = kwargs.pop('fixed_model_linestyle', None)
    fixed_model_color = kwargs.pop('fixed_model_color', None)

    legend_kwargs = utils.extract_kwargs(kwargs, prefix='legend')

    label_kwargs = utils.extract_kwargs(kwargs, 'label', 'prefix_label', 'suffix_label',
                                        'key_in_label', 'numer_in_label', 'denom_in_label',
                                        'model_in_label', 'unit_in_label', 'attrname_in_label')
    arrow_kwargs = utils.extract_kwargs(kwargs, prefix='arrow')

    # If there is only one model it is set as the title to make the legend shorter
    model_in_label = label_kwargs.pop('model_in_label', None)
    if len(models) == 1 and model_in_label is None:
        label_kwargs['model_in_label'] = False
        legend_kwargs.setdefault('title', models[0].name)
    else:
        label_kwargs['model_in_label'] = model_in_label


    modeldata, axis_labels = get_data(models, {'x': xkey, 'y': ykey},
                                      default_attrname=default_attrname, unit=unit,
                                      mask=mask, mask_na=mask_na, _kwargs=kwargs, **label_kwargs)

    kwargs.setdefault('ax_xlabel', axis_labels['x'])
    kwargs.setdefault('ax_ylabel', axis_labels['y'])
    delayed_kwargs = update_axes(ax, kwargs, delay='ax_legend', update_ax=update_ax, update_fig=update_fig)

    has_labels = False
    for mi, (model_name, model_dataset) in enumerate(modeldata.items()):
        for ki, key_data in enumerate(model_dataset):
            if fixed_model_linestyle or (fixed_model_linestyle is None and len(model_dataset) == 1):
                ls = linestyles[mi]
            else:
                ls = linestyles[ki]
            if fixed_model_color is True or (fixed_model_color is None and len(modeldata) > 1):
                c = colors[mi]
            else:
                c = colors[ki]

            if not has_labels and key_data.get('label', None):
                has_labels = True

            label = key_data.get('label', None)
            for i in range(len(key_data['x'])):
                x, y = key_data['x'][i], key_data['y'][i]
                slope = y / x
                ax.axline(xycoord, slope=slope, label=label,
                          color = c, ls=ls, **kwargs)
                label = None

                if arrow:
                    if np.abs(slope) > 1:
                        y_arrow = np.array([arrow_position, arrow_position + 0.01]) * (-1 if y < 0 else 1)
                        x_arrow = 1 / slope * y_arrow
                    else:
                        x_arrow = np.array([arrow_position, arrow_position + 0.01]) * (-1 if x < 0 else 1)
                        y_arrow = slope * x_arrow

                    ax.arrow(x_arrow[0], y_arrow[1], x_arrow[1] - x_arrow[0], y_arrow[1] - y_arrow[0],
                            facecolor=c, **arrow_kwargs)

    update_axes(ax, delayed_kwargs, update_ax=update_ax, update_fig=update_fig)
    if legend or (legend is None and has_labels):
        create_legend(ax, **legend_kwargs)

    return ax

simple.set_logging_level

set_logging_level(level)

Set the level of messages to be displayed.

Options are: DEBUG, INFO, WARNING, ERROR.

Source code in simple/utils.py

def set_logging_level(level):
    """
    Set the level of messages to be displayed.

    Options are: DEBUG, INFO, WARNING, ERROR.
    """
    if level.upper() == 'DEBUG':
        level = logging.DEBUG
    elif level.upper() == 'INFO':
        level = logging.INFO
    elif level.upper() == 'WARNING':
        level = logging.WARNING
    elif level.upper() == 'ERROR':
        level = logging.ERROR

    SimpleLogger.setLevel(level)

simple.update_axes

update_axes(ax, kwargs, *, delay=None, update_ax=True, update_fig=True, delay_all=False)

Updates the axes and figure objects.

Keywords beginning with ax_<name>, xax_<name>, yax_<name> and fig_<name> will be stripped from kwargs. These will then be used to call the set_<name> or <name> method of the axes, axis or figure object.

If the value mapped to the above arguments is: - A boolean it is used to determine whether to call the method. The boolean itself will not be passed to the method. To pass a boolean to a method place it in a tuple, e.g. (True, ). - A tuple then the contents of the tuple is unpacked as arguments for the method call. - A dictionary then the contents of the dictionary is unpacked as keyword arguments for the method call. - Any other value will be passed as the first argument to the method call.

Additional keyword arguments can be passed to methods by mapping e.g. <ax|xax|yax|fig>_kw_<name>_<keyword> kwargs to the value. These additional keyword arguments are only used if the <ax|xax|yax|fig>_<name> kwargs exists. Note however that they are always stripped from kwargs.

It is possible to delay calling certain method by adding <ax|xax|yax|fig>_<name> to *delay. Keywords associated with these method will then be included in the returned dictionary. This dictionary can be passed back to the function at a later time. To delay all calls but remove the relevant kwargs from kwargs use delay_all=True.

Returns dict: A dictionary containing the delayed method calls.

Source code in simple/plotting.py

def update_axes(ax, kwargs, *, delay=None, update_ax = True, update_fig = True, delay_all=False):
    """
    Updates the axes and figure objects.

    Keywords beginning with ``ax_<name>``, ``xax_<name>``, ``yax_<name>`` and ``fig_<name>`` will be stripped
    from kwargs. These will then be used to call the ``set_<name>`` or ``<name>`` method of the axes, axis or
    figure object.

    If the value mapped to the above arguments is:
    - A boolean it is used to determine whether to call the method. The boolean itself will not be passed to
        the method. To pass a boolean to a method place it in a tuple, e.g. ``(True, )``.
    - A tuple then the contents of the tuple is unpacked as arguments for the method call.
    - A dictionary then the contents of the dictionary is unpacked as keyword arguments for the method call.
    - Any other value will be passed as the first argument to the method call.

    Additional keyword arguments can be passed to methods by mapping e.g. ``<ax|xax|yax|fig>_kw_<name>_<keyword>``
    kwargs to the value. These additional keyword arguments are only used if the
    ``<ax|xax|yax|fig>_<name>`` kwargs exists. Note however that they are always stripped from ``kwargs``.

    It is possible to delay calling certain method by adding ``<ax|xax|yax|fig>_<name>`` to ``*delay``. Keywords
    associated with these method will then be included in the returned dictionary. This dictionary can be passed back
    to the function at a later time. To delay all calls but remove the relevant kwargs from *kwargs* use
    ``delay_all=True``.

    Returns
        dict: A dictionary containing the delayed method calls.
    """

    ax = get_axes(ax)
    axes_meth = utils.extract_kwargs(kwargs, prefix='ax')
    axes_kw = utils.extract_kwargs(axes_meth, prefix='kw')

    xaxes_meth = utils.extract_kwargs(kwargs, prefix='xax')
    xaxes_kw = utils.extract_kwargs(axes_meth, prefix='kw')

    yaxes_meth = utils.extract_kwargs(kwargs, prefix='yax')
    yaxes_kw = utils.extract_kwargs(axes_meth, prefix='kw')

    figure_meth = utils.extract_kwargs(kwargs, prefix='fig')
    figure_kw = utils.extract_kwargs(figure_meth, prefix='kw')

    # Special cases
    if 'size' in figure_meth: figure_meth.setdefault('size_inches', figure_meth.pop('size'))

    if delay is None:
        delay = []
    elif type(delay) is str:
        delay = [delay]
    delayed_kwargs = {}

    def update(obj, name, meth_kwargs, kw_kwargs):
        for var, arg in meth_kwargs.items():
            var_kwargs = utils.extract_kwargs(kw_kwargs, prefix=var)
            try:
                method = getattr(obj, f'set_{var}')
            except:
                try:
                    method = getattr(obj, var)
                except:
                    raise AttributeError(f'The {name} object has no method called ``set_{var}`` or ``{var}``')

            if f'{name}_{var}' in delay or delay_all:
                delayed_kwargs[f'{name}_{var}'] = arg
                delayed_kwargs.update({f'{name}_kw_{var}_{k}': v for k,v in var_kwargs.items()})
                continue

            elif arg is False:
                continue
            elif arg is True:
                arg = ()
            elif type(arg) is dict:
                var_kwargs.update(arg)
                arg = ()
            elif type(arg) is not tuple:
                arg = (arg, )

            method(*arg, **var_kwargs)

    if update_ax:
        update(ax, 'ax', axes_meth, axes_kw)
        if xaxes_meth:
            update(ax.xaxis, 'xax', xaxes_meth, xaxes_kw)
        if yaxes_meth:
            update(ax.yaxis, 'yax', yaxes_meth, yaxes_kw)

    if update_fig:
        update(ax.get_figure(), 'fig', figure_meth, figure_kw)

    return delayed_kwargs