dispel.data.measures module#

A module containing models for measures.

class dispel.data.measures.MeasureId[source]#

Bases: DefinitionId

The definition of a measure id for a task.

Parameters:

  • task_name – The name and abbreviation of the task. Note that if no abbreviation is provided the name is used directly in the id.

  • measure_name – The name of the measure and its abbreviation.

  • modalities – The modalities and their abbreviations under which the measure is constituted.

  • aggregation – A method that was used to aggregate a sequence of the underlying measure, e.g., for the measure mean response time it would be mean.

Notes

The abbreviations of values are passed using AbbreviatedValue. To generate the actual id the .abbr accessor is used. If one passes only strings, the class actually wraps those into AbbreviatedValue instances.

Examples

>>> from dispel.data.values import AbbreviatedValue as AV
>>> from dispel.data.measures import MeasureId
>>> MeasureId(
...     task_name=AV('Cognitive Processing Speed', 'CPS'),
...     measure_name=AV('reaction time', 'rt'),
...     modalities=[AV('digit-to-digit', 'dtd')],
...     aggregation='mean'
... )
cps-dtd-rt-mean
__init__(task_name, measure_name, modalities=None, aggregation=None)[source]#
Parameters:
classmethod from_str(value)[source]#

See dispel.data.values.DefinitionId.from_str().

Parameters:

value (str) – The string from which the definition id is to be constructed.

Raises:

NotImplementedError – Always raised. This method is not implemented since there is no unambiguous parsing of task ids.

Return type:

DefinitionId

class dispel.data.measures.MeasureSet[source]#

Bases: ValueSet

A collection of measures.

VALUE_CLS#

alias of MeasureValue

classmethod from_data_frame(data)[source]#

Create a MeasureSet from a data frame.

Parameters:

data (DataFrame) – A data frame containing information about measures

Returns:

A measure set derived from the provided data frame.

Return type:

MeasureSet

to_list(stringify=False)[source]#

Convert measure set to a list of measure dictionaries.

Parameters:

stringify (bool) – True if all dictionary values are converted to strings. False otherwise.

Returns:

A dictionary summarizing measure value information.

Return type:

List[Dict[str, Optional[Any]]]

class dispel.data.measures.MeasureValue[source]#

Bases: FlagMixIn, Value

A measure value.

to_dict(stringify=False)[source]#

Get a dictionary representation of measure information.

Parameters:

stringify (bool) – True if all dictionary values are converted to strings. False otherwise.

Returns:

A dictionary summarizing measure value information.

Return type:

Dict[str, Optional[Any]]

class dispel.data.measures.MeasureValueDefinition[source]#

Bases: ValueDefinition

The definition of measures from tasks.

Parameters:

  • task_name – The full name of the task and its abbreviation, e.g., Cognitive Processing Speed test and CPS passed using AbbreviatedValue.

  • measure_name – The name of the measure, e.g. reaction time and its abbreviation passed using AbbreviatedValue. Note that aggregation methods are specified in aggregation and should not be direclty part of the measure name.

  • unit – See ValueDefinition.

  • description – See ValueDefinition.

  • data_type – See ValueDefinition.

  • validator – See ValueDefinition.

  • modalities – The modalities of the tasks, i.e. if there is more than one variant of the task. An example would be the digit-to-digit and symbol-to-digit or predefined key 1, predefined key 2 and random key variants of the CPS test. Abbreviations of the modalities can be passed using AbbreviatedValue.

  • aggregation – If the measure is the result of an aggregation, the method that was used to aggregate. E.g. for mean response time it would be mean. Abbreviations are passed using AbbreviatedValue.

  • precision – See ValueDefinition.

Examples

>>> from dispel.data.values import AbbreviatedValue as AV
>>> from dispel.data.measures import MeasureValueDefinition
>>> from dispel.data.validators import RangeValidator
>>> MeasureValueDefinition(
...     task_name = AV('Cognitive Processing Speed test', 'CPS'),
...     measure_name = AV('response time', 'rt'),
...     unit = 's',
...     description = 'The mean time to respond to a presented stimulus',
...     data_type = 'float64',
...     validator = RangeValidator(lower_bound=0),
...     modalities = [
...         AV('digit-to-digit', 'dtd'),
...         AV('predefined key 1', 'key1')
...     ],
...     aggregation = 'mean'
... )
<MeasureValueDefinition: cps-dtd_key1-rt-mean (CPS digit-to-digit ...>
__init__(task_name, measure_name, unit=None, description=None, data_type=None, validator=None, modalities=None, aggregation=None, precision=None)[source]#
Parameters:
class dispel.data.measures.MeasureValueDefinitionPrototype[source]#

Bases: ValueDefinitionPrototype

A task measure value definition prototype.

This is a convenience method that populates the cls argument with the MeasureValueDefinition class.

__init__(**kwargs)[source]#
Parameters:

kwargs (Any) –

dispel.data.measures.row_to_definition(row)[source]#

Convert a pandas series to a value definition.

Parameters:

row (Series) – A pandas series containing definition information.

Returns:

The corresponding value definition.

Return type:

ValueDefinition

Raises:

MissingColumnError – If required fields are missing from the pandas’ series.

dispel.data.measures.row_to_value(row)[source]#

Convert a pandas series to a measure value.

Parameters:

row (Series) – A pandas series containing definition information.

Returns:

The corresponding measure value.

Return type:

MeasureValue

Raises:

MissingColumnError – If measure_value field is missing from the pandas’ series.