Variables

Variables:

Combine(*args, **kwargs)	Combine variables into a tuple.
Compose(*args, **kwargs)	Composition of variables.
Variable(name, getter, **kwargs)	Function of data with context.

Variables

Variables are functions to transform data adding context.

A variable can represent a particle type, a coordinate, etc. They transform raw input data into Lena data with context. Variables have name and may have other attributes like LaTeX name, dimension or unit.

Variables can be composed using Compose, which corresponds to function composition.

Variables can be combined into multidimensional variables using Combine.

Examples:

>>> from lena.variables import Variable, Compose
>>> # data is pairs of (positron, neutron) coordinates
>>> data = [((1.05, 0.98, 0.8), (1.1, 1.1, 1.3))]
>>> x = Variable(
...    "x", lambda coord: coord[0], type="coordinate"
... )
>>> neutron = Variable(
...    "neutron", latex_name="n",
...    getter=lambda double_ev: double_ev[1], type="particle"
... )
>>> x_n = Compose(neutron, x)
>>> x_n(data[0])[0]
1.1
>>> x_n(data[0])[1] == {
...     'variable': {
...         'name': 'neutron_x', 'particle': 'neutron',
...         'latex_name': 'x_{n}', 'coordinate': 'x', 'type': 'coordinate',
...         'compose': {
...             'type': 'particle', 'latex_name': 'n',
...             'name': 'neutron', 'particle': 'neutron'
...         },
...     }
... }
True

Combine and Compose are subclasses of a Variable.

class Combine(*args, **kwargs)

Combine variables into a tuple.

Combine(var1, var2, …)(value) is ((var1.getter(value), var2.getter(value), …), context).

args are the variables to be combined.

Keyword arguments are passed to Variable’s __init__. For example, name is the name of the combined variable. If not provided, it is its variables’ names joined with ‘_’.

context.variable is updated with combine, which is a tuple of each variable’s context.

Attributes:

dim is the number of variables.

range. If all variables have an attribute range, the range of this variable is set to a list of them.

All args must be Variables and there must be at least one of them, otherwise LenaTypeError is raised.

class Compose(*args, **kwargs)

Composition of variables.

args are the variables to be composed.

Keyword arguments:

name is the name of the composed variable. If that is missing, it is composed from variables names joined with underscore.

latex_name is LaTeX name of the composed variable. If that is missing and if there are only two variables, it is composed from variables’ names (or their LaTeX names if present) as a subscript in the reverse order (latex2_{latex1}).

context.variable.compose contains contexts of the composed variables (the first composed variable is most nested).

If any keyword argument is a callable, it is used to create the corresponding variable attribute. In this case, all variables must have this attribute, and the callable is applied to the list of these attributes. If any attribute is missing, LenaAttributeError is raised. This can be used to create composed attributes other than latex_name.

If there are no variables or if kwargs contain getter, LenaTypeError is raised.

class Variable(name, getter, **kwargs)

Function of data with context.

name is variable’s name.

getter is a Python function (not a Variable) that performs the actual transformation of data. It must accept data and return data without context.

Other variable’s attributes can be passed as keyword arguments. Examples include latex_name, unit (like cm or keV), range, etc.

type is the type of the variable. It depends on your application, examples are “coordinate” or “particle_type”. It has a special meaning: if present, its value is added to variable’s context as a key with variable’s name (see example for this module). Thus variable type’s data is preserved during composition of different types.

Attributes

getter

var_context is the dictionary of attributes of the variable. It is added to context.variable during __call__().

All public attributes of a variable can be accessed using dot notation (for example, var.var_context[“latex_name”] can be written as var.latex_name). AttributeError is raised if an attribute is missing.

If getter is a Variable or is not callable, LenaTypeError is raised.

__call__(value)

Transform a value.

Data part of the value is transformed by getter.

context.variable is updated with the context of this variable (or created if missing). If context already contained variable, it is preserved as context.variable.compose subcontext.

get(key, default=None)

Return the attribute key if present, else default.

key can be a dot-separated string, a list or a dictionary (see context.get_recursively).

If default is not given, it defaults to None, so that this method never raises a KeyError.