Variables

Variables:

Combine(*args, **kwargs)	Combine variables into a tuple.
Compose(*args, **kwargs)	Composition of variables.
Variable(name, getter[, type])	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"
... )
>>> positron = Variable(
...    "positron", latex_name="e^+",
...    getter=lambda double_ev: double_ev[0], type="particle"
... )
>>> x_e = Compose(positron, x)
>>> x_e(data[0])[0]
1.05
>>> x_e(data[0])[1] == {
...    'variable': {
...        'name': 'x',
...        'coordinate': {'name': 'x'},
...        'type': 'coordinate',
...        'compose': ['particle', 'coordinate'],
...        'particle': {'name': 'positron', 'latex_name': 'e^+'}
...    }
... }
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 containing each variable’s context.

Attributes:

dim is the number of variables.

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

__getitem__(index)

Get variable at the given index.

class Compose(*args, **kwargs)

Composition of variables.

args are the variables to be composed.

A keyword argument name can set the name of the composed variable. If that is missing, it the name of the last variable is used.

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

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

class Variable(name, getter, type='', **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 could be “coordinate” or “particle”. It has a special meaning: if present, its value is added to variable’s context as a key with the context of this variable (see the example for this module). It is recommended to set the type, otherwise variable’s data will be lost after composition of variables.

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.