dispel.data.values module#

A module to handle values and their definitions.

class dispel.data.values.AVEnum[source]#

Bases: Enum

A base class for abbreviated value enumerations.

When extracting measures from tasks they are often done for specific modalities. This base class allows to do this in a convenient fashion to address modalities both from a processing and representation form. The enumeration is ordered.

Examples

Assuming you have a task that has two modalities, e.g. the Cognitive Processing Speed test has two forms: symbol-to-digit and digit-to-digit. The respective modalities class would look like:

enum

>>> from dispel.data.values import AVEnum
>>> class CPSTypeModality(AVEnum):
...     SYMBOL_TO_DIGIT = ('symbol-to-digit', 'std')
...     DIGIT_TO_DIGIT = ('digit-to-digit', 'dtd')
...
>>> CPSTypeModality.SYMBOL_TO_DIGIT
<CPSTypeModality.SYMBOL_TO_DIGIT: symbol-to-digit (std) [1]>

The constants can be used directly in Series as well as can be converted to an integer representation:

enum

>>> int(CPSTypeModality.SYMBOL_TO_DIGIT)
1

In order to conventiently pass the constants to modalities of MeasureValueDefinition and MeasureValueDefinitionPrototype a property is exposed that contains the AbbreviatedValue:

enum

>>> CPSTypeModality.SYMBOL_TO_DIGIT.av
symbol-to-digit (std)

as well as for convenience the abbreviated value too:

enum

>>> CPSTypeModality.SYMBOL_TO_DIGIT.abbr
'std'

Since the enumeration is odered, one can also perform comparisons between them:

enum

>>> CPSTypeModality.DIGIT_TO_DIGIT < CPSTypeModality.SYMBOL_TO_DIGIT
False

The member can also be retrieved from the abbreviation:

enum

>>> CPSTypeModality.from_abbr('std')
<CPSTypeModality.SYMBOL_TO_DIGIT: symbol-to-digit (std) [1]>

As well as from the variable name (case-insensitive):

enum

>>> CPSTypeModality.from_variable('symbol_to_digit')
<CPSTypeModality.SYMBOL_TO_DIGIT: symbol-to-digit (std) [1]>

__init__(value, abbr=None)[source]#

property abbr#: Get the abbreviated value.

classmethod from_abbr(value)[source]#

Get the corresponding member from the abbreviated value.

Parameters:: value (str) –

classmethod from_variable(value)[source]#

Get the corresponding member from the variable name.

Parameters:: value (str) –

property variable#: Get the modality variable name.

class dispel.data.values.AbbreviatedValue[source]#

Bases: object

An abbreviated value.

Examples

This class allows to consistently handle abbreviated terms. Assuming you have a name of an assessment, e.g. Cognitive Processing Speed test and the respective abbreviation would be CPS, then you can create an abbreviated value like this:

>>> from dispel.data.values import AbbreviatedValue as AV
>>> value = AV('Cognitive Processing Speed test', 'CPS')
>>> value
Cognitive Processing Speed test (CPS)

While this seems like a lot of overhead, it comes in handy when describing value definitions or higher-level abstractions, such as measure definitions.

Parameters:

value – The full description of the value
abbr – The abbreviated form of the value

value#: The full description of the value

__init__(value, abbr=None)[source]#

Parameters:

value (str) –
abbr (str | None) –

property abbr#: Get the abbreviated form of the value.

format(*args, **kwargs)[source]#: Format an abbreviated value.

classmethod wrap(value)[source]#

Wrap a value into an abbreviated value.

This is a small helper class to conveniently wrap values into an abbreviated value, if they are not already one.

Parameters:: value – The value to be wrapped
Returns:: The passed value if it is an instance of AbbreviatedValue. If a string is passed, then the string is passed as value argument to the constructor.
Return type:: AbbreviatedValue
Raises:: ValueError – If the passed value is neither a string nor an instance of AbbreviatedValue.

class dispel.data.values.DefinitionId[source]#

Bases: object

The definition of a measure id.

This class provides the basic functionality around ids used to reference columns and definitions. Other structured ids inherit from this class.

Parameters:: id – The identifier of the definition.

__init__(id_)[source]#

Parameters:: id_ (str) –

classmethod from_str(value)[source]#

Create a class instance from string.

Parameters:: value (str) –
Return type:: DefinitionId

property id: str#: Get the identifier.

class dispel.data.values.Value[source]#

Bases: object

A value with definition and actual value.

Parameters:

definition – The definition of the value.
value – The actual value. If definition.precision is set, then the value will be rounded to the number of significant digits. The pre-rounded value is stored in raw_value.

__init__(definition, value)[source]#

Parameters:

definition (ValueDefinition) –
value (Any) –

property id: DefinitionId#: Get the identifier from the definition of the value.

class dispel.data.values.ValueDefinition[source]#

Bases: object

The definition of a value.

Parameters:

id – The identifier of the value definition
name – The human-readable name of the values
unit – The unit of the value
description – A more elaborate description of the values and how they were produced
data_type – The numpy data type of the value in question
validator – A function that ensures values comply with the definition. The module validators contains validators for common scenarios that can be used here.
precision – The number of significance for the values expected under definition. If set, the value will be rounded to the set number of digits.

__init__(id_, name, unit=None, description=None, data_type=None, validator=None, precision=None)[source]#

Parameters:

id_ (DefinitionId | str) –
name (str) –
unit (str | None) –
description (str | None) –
data_type (str | None) –
validator (Callable[[Any], None] | None) –
precision (int | None) –

derive(**kwargs)[source]#

Derive a value definition with updated properties.

Parameters:: kwargs – Keyword arguments to be set/updated in the derived definition.
Returns:: A new definition with updated parameters.
Return type:: ValueDefinition
Raises:: ValueError – If one of the provided arguments is not a parameter of the constructor.

class dispel.data.values.ValueDefinitionPrototype[source]#

Bases: object

The prototype of a ValueDefinition.

Measure processing often leads to various related measures. To ease the creation of such, the ValueDefinitionPrototype allows to specify prototypic measures that can be used to derive actual definitions.

Parameters:

cls – The class to be used when creating concrete instances with create_definition(). By default, the class used is :class:ValueDefinition`.
kwargs – All named parameters passed to the constructor will be passed to the measure definition class constructor. The parameter cls is reserved to pass a different measure definition class. Placeholders to be filled upon creation are specified with curly brackets, i.e., a {placeholder} value is populated when calling prototype.create_definition(placeholder='special').

Examples

Assuming we want to create a measure for different time windows one can create the following prototype:

>>> from dispel.data.values import ValueDefinitionPrototype
>>> prototype = ValueDefinitionPrototype(
...     id_='measure-{lower}-{upper}',
...     name='measure from {lower} to {upper}',
...     unit='s'
... )
>>> prototype.create_definition(lower=5, upper=6)
<ValueDefinition: measure-5-6 (measure from 5 to 6, s)>
>>> prototype.create_definition(lower=1, upper=5)
<ValueDefinition: measure-1-5 (measure from 1 to 5, s)>

__init__(**kwargs)[source]#

create_definition(**values)[source]#

Create a definition from this prototype.

Parameters:: values (Any) – The arguments and placeholders to be populated. All named arguments will be used to both provide additional named arguments to the measure definition class specified with cls during construction upon creation (the class is inspected for named parameters) and placeholders provided during construction of the prototype.
Returns:: The value definition created from the value definition prototype.
Return type:: ValueDefinition

Examples

An example is given above to populate placeholders. This is also possible with arguments required by the definition class:

>>> from dispel.data.values import ValueDefinitionPrototype
>>> prototype = ValueDefinitionPrototype(unit='s')
>>> prototype.create_definition(id_='foo', name='bar')
<ValueDefinition: foo (bar, s)>
>>> prototype.create_definition(id_='baz', name='bam')
<ValueDefinition: baz (bam, s)>

Raises:: ValueError – If a placeholder is missing from kwargs.
Parameters:: values (Any) –
Return type:: ValueDefinition

create_definitions(items)[source]#

Create multiple definitions.

This method provides a convenient way to specify multiple definitions at the same time for an iterable of dictionaries that are passed to create_definition().

Parameters:: items (Iterable[Dict[str, Any]]) – An iterable of dictionaries passed to create_definition().
Returns:: A list of the created value definitions.
Return type:: List[ValueDefinition]

derive(**kwargs)[source]#

Derive a prototype with updated properties.

Parameters:: kwargs – Keyword arguments to be set/updated in the derived prototype.
Returns:: A new prototype with updated parameters.
Return type:: ValueDefinitionPrototype

class dispel.data.values.ValueSet[source]#

Bases: object

A collection of multiple values.

Parameters:

values – The values of the value set. This can be a list of Values or a list of any value.
definitions – An optional list of definitions describing the passed values through the parameter values.

Notes

The constructor passes both values and definitions to ValueSet.set_values(). For details on how to specify values of the ValueSet please have a look there.

VALUE_CLS#: alias of Value

__init__(values=None, definitions=None)[source]#

Parameters:

values (List[Any] | None) –
definitions (List[ValueDefinition] | None) –

definitions()[source]#

Get all definitions of the set.

Returns:: An iterable of all value definitions from all values of the set.
Return type:: Iterable[ValueDefinition]

property empty: bool#: Get whether the value set is empty.

get(id_)[source]#

Get a value for an id.

Parameters:

id – The id or definition for which to obtain the value.
id_ (DefinitionId | str | ValueDefinition) –

Returns:

The respective Value matching the provided id_.

Return type:

Value

Raises:

KeyError – If the provided id_ is not present in the set.

get_definition(id_)[source]#

Get the definition of a value by its id.

Parameters:

id – The id for which to obtain the definition
id_ (DefinitionId | str | ValueDefinition) –

Returns:

The definition belonging to the passed id.

Return type:

ValueDefinition

get_raw_value(id_)[source]#

Get the raw value for an id.

This is a convenience method to not have to call value_set.get(id).value.

Parameters:

id – The id or definition for which to retrieve the raw value.
id_ (DefinitionId | str | ValueDefinition) –

Returns:

The raw value of the Value matching the passed id or definition.

Return type:

Any

has_value(id_)[source]#

Test if the set has a specific value.

Parameters:

id – The id or definition for which to lookup if a value is present
id_ (DefinitionId | str | ValueDefinition) –

Returns:

True if the value set contains a value for the provided id_. Otherwise, False.

Return type:

bool

Raises:

TypeError – If the id is neither a str, DefinitionId nor a ValueDefinition.

ids()[source]#

Get all ids of the set.

Returns:: An iterable of all definition ids from all values of the set.
Return type:: Iterable[DefinitionId]

items()[source]#

Get an items view of all values.

Return type:: ItemsView[DefinitionId, Value]

set(value, definition=None, overwrite=False)[source]#

Set a value in the value set.

Parameters:

value (Any) – The value to be set. If the value is not an instance of Value one needs to also provide a definition.
definition (ValueDefinition | None) – An optional definition of the passed value should the value not be an instance of Value.
overwrite (bool) – By default values in the ValueSet are not overwritten. If you want to update an already set value you will need to set overwrite = True.

Raises:

ValueError – If value is not a Value and no definition is passed.
ValueError – If value’s id is already present in the Value Set, and the overwrite argument is set to False.

set_values(values, definitions=None, overwrite=True)[source]#

Set multiple values in the value set.

Parameters:

values (List[Any]) – The values to be set. If the values are not an instance of Value the optional parameter definitions needs to be provided with a list of ValueDefinition describing each value in values.
definitions (List[ValueDefinition] | None) – An optional list of definitions for values passed via values. Both values and definitions need to be of equal length.
overwrite (bool) – The overwrite-behavior. See ValueSet.set() for details.

Raises:

ValueError – If values and definitions are not of equal length.

values()[source]#

Get all values of the set.

Returns:: An iterable of all values within the set.
Return type:: Iterable[Value]