dispel.providers.ads.tasks.grip module#

Grip Force test related functionality.

This module contains functionality to extract measures for the Grip Force test (GRIP).

class dispel.providers.ads.tasks.grip.CategoryToDiff#

Bases: tuple

Tuple-like object with the two pressure categories used to compute mean applied force difference.

static __new__(_cls, category_1, category_2)#: Create new instance of CategoryToDiff(category_1, category_2)

category_1#: Alias for field number 0

category_2#: Alias for field number 1

class dispel.providers.ads.tasks.grip.ExtractAppliedForceStats[source]#

Bases: ExtractMultipleStep

An extraction processing step for applied force measures.

Parameters:

hand – The hand used to perform the test.
category – The pressure category indicating on which category the applied force stats are computed.
plateau – The plateau on which the extraction is to be performed.
percentile – Compute the q-th percentile of the applied forces in the aggregation methods.

__init__(hand, category=None, plateau=None, percentile=90)[source]#

Parameters:

hand (HandModality) –
category (TargetPressureModality | None) –
plateau (PlateauModality | None) –
percentile (int) –

class dispel.providers.ads.tasks.grip.ExtractMeanAppliedForceDiff[source]#

Bases: ExtractMultipleStep

An extraction processing step for mean applied force difference (MAF).

Parameters:

hand – The hand used to perform the test.
categories_to_diff – The NamedTuple CategoryToDiff containing the two pressure categories on which the MAF difference is compute.
plateau – The plateau on which the extraction is to be performed.

__init__(hand, categories_to_diff, plateau=None)[source]#

Parameters:

hand (HandModality) –
categories_to_diff (CategoryToDiff) –
plateau (PlateauModality | None) –

class dispel.providers.ads.tasks.grip.ExtractOvershootStats[source]#

Bases: AggregateRawDataSetColumn

An extraction processing step for overshoot measures.

Parameters:: hand – The hand on which the overshoot measures are to be computed.

__init__(hand)[source]#

Parameters:: hand (HandModality) –

class dispel.providers.ads.tasks.grip.ExtractRMSPressure[source]#

Bases: ExtractStep

An extraction processing step for pressure accuracy measures.

Parameters:

hand – The hand used to perform the test
category – The pressure category indicating on which category the RMSE is computed.
plateau – The plateau on which the extraction is to be performed

__init__(hand, category=None, plateau=None)[source]#

Parameters:

hand (HandModality) –
category (TargetPressureModality | None) –
plateau (PlateauModality | None) –

class dispel.providers.ads.tasks.grip.ExtractReactionTimeStats[source]#

Bases: AggregateRawDataSetColumn

An extraction processing step for Reaction Time measures.

Parameters:: hand – The hand used to perform the test

__init__(hand)[source]#

Parameters:: hand (HandModality) –

class dispel.providers.ads.tasks.grip.ExtractThumbPositionVariation[source]#

Bases: ExtractMultipleStep

An extraction processing step for thumb position on screen.

Parameters:: hand – The hand used to perform the test

__init__(hand)[source]#

Parameters:: hand (HandModality) –

class dispel.providers.ads.tasks.grip.ExtractTransitionTime[source]#

Bases: ExtractStep

An extraction processing step for Transition Time measures.

Parameters:

hand – The hand used to perform the test
transition – A tuple indicating the two plateaus defining a transition. e.g.: {‘low’,’high’} indicates a transition from the 'low' plateau to the 'high' plateau.

__init__(hand, transition)[source]#

Parameters:

hand (HandModality) –
transition (Tuple[TargetPressureModality, TargetPressureModality]) –

class dispel.providers.ads.tasks.grip.FilterIncompleteSequences[source]#

Bases: LevelFilter

A filter to skip levels that do not contain eight sequences.

Notes

The filter expects concatenated levels from ConcatenateLevels and should contain the target pressure values in the context (i.e. targetPressure_{index}.)

filter(levels)[source]#

Check if there is contextual info for the eight sequences.

Parameters:: levels (Iterable[Level]) –
Return type:: Set[Level]

repr()[source]#

Get representation of the filter.

Return type:: str

class dispel.providers.ads.tasks.grip.FilterTransition[source]#

Bases: FilterIncompleteSequences

Filter incomplete sequences or level without the selected transition.

__init__(from_pressure, to_pressure)[source]#

Parameters:

from_pressure (TargetPressureModality) –
to_pressure (TargetPressureModality) –

filter(levels)[source]#

Filter for transitions.

Parameters:: levels (Iterable[Level]) –
Return type:: Set[Level]

repr()[source]#

Get representation of the filter.

Return type:: str

class dispel.providers.ads.tasks.grip.GripTremorMeasures[source]#

Bases: ProcessingStepGroup

A group of grip processing steps for tremor measures.

Parameters:

hand – The hand on which the tremor measures are to be computed.
sensor – The sensor on which the tremor measures are to be computed.

__init__(hand, sensor)[source]#

Parameters:

hand (HandModality) –
sensor (SensorModality) –

class dispel.providers.ads.tasks.grip.PlateauModality[source]#

Bases: AVEnum

Enumerated constant representing the plateau modality.

This modality defines the subpart of the plateau that is kept for measure computation.

LAST_FIVE = 3#

MIDDLE_FOUR = 1#

MIDDLE_TWO = 2#

class dispel.providers.ads.tasks.grip.PositionModality[source]#

Bases: AVEnum

Screen thumb position for grip force task.

X = 1#

Y = 2#

property column: str#: Create a camel case string of position modalities.

class dispel.providers.ads.tasks.grip.TargetPressureModality[source]#

Bases: AVEnum

Enumerated constant representing the pressure modalities.

HIGH = 3#

LOW = 1#

MEDIUM = 2#

VERY_HIGH = 4#

class dispel.providers.ads.tasks.grip.TransformOvershoot[source]#

Bases: TransformStep

An extraction step to measure the overshoot/undershoot.

Parameters:: hand – The hand on which the overshoot is to be computed.

__init__(hand)[source]#

Parameters:: hand (HandModality) –

class dispel.providers.ads.tasks.grip.TransformPlateau[source]#

Bases: TransformStep

An transform processing step for plateau detection.

__init__(level_id)[source]#

class dispel.providers.ads.tasks.grip.TransformPressureError[source]#

Bases: TransformStep

A TransformStep for pressure error related measures.

__init__(level_id, plateau=None)[source]#

Parameters:: plateau (PlateauModality | None) –

class dispel.providers.ads.tasks.grip.TransformRefinedTargetCategory[source]#

Bases: TransformStep

A TransformStep for to identify pressure categories.

__init__(level_id, plateau=None)[source]#

Parameters:: plateau (PlateauModality | None) –

class dispel.providers.ads.tasks.grip.TransformTimeDefinedPlateau[source]#

Bases: TransformStep

An transform processing step for time-defined plateau.

__init__(level_id, plateau)[source]#

Parameters:: plateau (PlateauModality) –

class dispel.providers.ads.tasks.grip.TransformTimeRelatedInfo[source]#

Bases: TransformStep

An extraction processing step for Time related measures.

__init__(level_id)[source]#

Parameters:: level_id (str) –

dispel.providers.ads.tasks.grip.applied_force(detected_plateau, category, cat_str=None)[source]#

Select the applied force or partial ‘detected-plateau’ column.

Parameters:

detected_plateau (DataFrame) – A dataframe with column ‘detected-plateau’ typically obtained after applying the TransformStep : TransformPlateau.
category (DataFrame) – A dataframe with column 'pressure-category' typically obtained after applying the TransformStep : :class: TransformRefinedTargetCategory.
cat_str (TargetPressureModality | None) – The pressure category indicating on which category the applied force is selected.

Returns:

The applied force or the ‘detected-plateau’ column on the defined pressure category cat_str.

Return type:

pandas.Series

dispel.providers.ads.tasks.grip.avg_diff_discrete_pdf(data, context)[source]#

Compute the average of the differentiated discrete PDF.

This corresponds to the average of the second discrete derivative of the pressure signal. In the process of computing the metric, we add several columns, namely ‘discrete-pdf’, ‘diff-discrete-pdf’ and level-sequence where we set the contextual level information under a series format with integers going from 0 to 7 indicating which level we are in.

Parameters:

data (DataFrame) – The two columns ‘discrete-pdf’ and ‘pressure’ of the data frame obtained by concatenating the levels.
context (Context) – The merged context obtained from the concatenation of the levels.

Returns:

A new data frame with discrete-pdf, diff-discrete-pdf, avg-diff-discrete-pdf and level-sequence columns

Return type:

pandas.DataFrame

dispel.providers.ads.tasks.grip.compute_overshoot(pressure, _plateau, time_info, level)[source]#

Compute pressure overshoot when changing pressure level.

Parameters:

pressure (DataFrame) –
_plateau (DataFrame) –
time_info (DataFrame) –
level (Level) –

Return type:

DataFrame

dispel.providers.ads.tasks.grip.compute_plateau(data, level)[source]#

Compute the plateau.

To compute the plateau we follow several steps: The first step is to compute the first and second discrete derivative of the resampled and interpolated pressure signal. (see avg_diff_discrete_pdf()).

Then we initialize our plateau detection algorithm by finding the spikes in the second discrete derivative of the signal (see compute_second_derivative_spikes()).

A third step consists in filling all small gaps in the detected plateau. (see fill_plateau()).

Once plateau are filled we filter the result by removing the very short detected plateau (see remove_short_plateau()).

The next step consists in extending the plateau filling large gap under certain conditions. (see extend_and_convert_plateau()).

Finally we create a target pressure signal based on the identified plateau. The idea is that a plateau often goes beyond the level border and hence should not be compared to the target pressure of the next level but on the main one on which the plateau resides. (see refined_target()).

Parameters:

data (DataFrame) – The data on which the plateau computation is to be performed.
level (Level) – The level corresponding to the given data.

Returns:

The pandas data frame containing the different plateaus.

Return type:

pandas.DataFrame

dispel.providers.ads.tasks.grip.compute_second_derivative_spikes(data)[source]#

Find spikes in diff discrete pdf.

The method is simple, we compare the moving average of the second derivative of the pressure signal (diff discrete pdf) to the average of the latter on the entire level-sequence. A spike or a plateau is detected if the moving average is higher than the level mean.

Parameters:: data (DataFrame) – A data frame with the two columns ‘diff-discrete-pdf’ and ‘avg-diff-discrete-pdf’ (e.g.: obtained with avg_diff_discrete_pdf).
Returns:: A series with values in {0, 1} indicating if a plateau has been detected.
Return type:: pandas.Series
Raises:: ValueError – A value error is raised if the length of the data is too short.

dispel.providers.ads.tasks.grip.compute_transition(data, transition)[source]#

Find all the transitions time of the selected transition.

Parameters:

data (DataFrame) –
transition (Tuple[TargetPressureModality, TargetPressureModality]) –

Return type:

float

dispel.providers.ads.tasks.grip.extend_and_convert_plateau(pressure, detected_plateau)[source]#

Extend the plateau under certain conditions.

The main idea is to fill large gaps between a current index and a lookahead index where a plateau is detected. Gaps are filled whenever the lookahead mean (defined as the mean between the current index and the lookahead) does not differ too much (0.5 pressure unit) from a lookbehind mean (defined as the mean from a lookbehind index until the current index ).

Parameters:

pressure (Series) – A Series of ‘pressure’
detected_plateau (Series) – A series of detected plateau

Returns:

The updated series ‘detected-plateau’ where large gaps have been filled and then where ‘1’ have been replaced with values from the ‘pressure’ column.

Return type:

pandas.Series

Raises:

ValueError – A value error is raised if the length of the data is too short.

dispel.providers.ads.tasks.grip.fill_plateau(data)[source]#

Fill small gaps in the plateau.

Parameters:: data (Series) – A series of values in {0, 1} typically the one obtained after applying the compute_second_derivative_spikes function.
Returns:: A modified version of the series where small gaps in the plateau have been filled.
Return type:: pandas.Series
Raises:: ValueError – A value error is raised if the length of the data is too short.

dispel.providers.ads.tasks.grip.filter_category(data, category, cat_str=None)[source]#

Filter data based on category.

The data frame data is filtered to only keep values for which the ‘pressure-category’ is equal to the cat_str. The exception is when cat_str == ‘all’ where data is returned without filtering.

Parameters:

data (DataFrame) – A dataframe typically obtained after applying the TransformStep : TransformPlateau.
category (DataFrame) – A dataframe with column 'pressure-category' typically obtained after applying the TransformStep : :class: TransformRefinedTargetCategory.
cat_str (TargetPressureModality | None) – The pressure category indicating on which category the applied force is selected.

Returns:

The filtered version of the data frame data.

Return type:

pandas.DataFrame

dispel.providers.ads.tasks.grip.get_target_pressure(context, seq)[source]#

Get target pressure from context and level sequence.

Parameters:

context (Context) – The merged context obtained from the concatenation of the levels.
seq (int) – The sequence of interest: e.g. a value in {0,1,..,7}

Returns:

Target pressure corresponding to the sequence seq.

Return type:

float

dispel.providers.ads.tasks.grip.reaction_time_between_level(plateau, level)[source]#

Compute the reaction time between the 8 different levels.

Parameters:

plateau (DataFrame) –
level (Level) –

Return type:

DataFrame

dispel.providers.ads.tasks.grip.refined_target(data, contexts)[source]#

Refine the target pressure for the detected plateau.

The method is simple, on each detected plateau, we take the maximum occurring target sequence as the label and add the refined target as the value of the target pressure for this label (or level sequence).

Parameters:

data (DataFrame) – A dataframe with the columns {‘detected-plateau’, ‘level-sequence’}
contexts (Context) – The merged context obtained from the concatenation of the levels.

Returns:

The series ‘refined-target’ corresponding to the target pressure extended to the size of the ‘detected-plateau’.

Return type:

pandas.Series

dispel.providers.ads.tasks.grip.remove_short_plateau(data, plateau_size=30)[source]#

Remove plateau shorter than plateau_size.

Parameters:

data (Series) – A series of values in {0, 1}, typically the one obtained after applying the fill_plateau function.
plateau_size (int) – The minimum size of a plateau, by default 30

Returns:

A modified version of the series where plateau shorter than the threshold plateau_size have been removed.

Return type:

pandas.Series

dispel.providers.ads.tasks.grip.rms_pressure_error(pressure_error, category, only_category=None)[source]#

Compute the Root Mean Square of ‘pressure-error’ column.

Parameters:

pressure_error (DataFrame) – A dataframe with column ‘pressure-error’ typically obtained after applying the TransformStep : TransformPressureError.
category (DataFrame) – A dataframe with column ‘pressure-category’ typically obtained after applying the TransformStep : TransformRefinedTargetCategory.
only_category (TargetPressureModality | None) – The pressure category indicating on which category the RMSE is computed.

Returns:

The Root Mean Square of the ‘pressure-error’ column on the defined pressure category cat str

Return type:

float

dispel.providers.ads.tasks.grip.smooth_discrete_pdf(data)[source]#

Compute the discrete probability density function (PDF).

Then smooth the values by filtering out small spikes.

Parameters:: data (Series) – A series of a signal. e.g. ‘pressure’
Returns:: A series of the discrete derivative of the signal where small spikes have been smoothed.
Return type:: pandas.Series
Raises:: ValueError – Raises a value error if the pandas.Series is too short.

dispel.providers.ads.tasks.grip.target_pressure_to_category(contexts)[source]#

Create a mapping between target pressure and their level.

Parameters:: contexts (Context) – The merged context obtained from the concatenation of the levels.
Returns:: The first element is a dictionary with as keys, the values of the four different target pressure and as values, the pressure category i.e values are in {‘low’, ‘medium’, ‘high’, ‘very_high’}. The Second element is the sequence of pressure category e.g.: [‘low’, ‘high’, ‘very_high’, ‘medium’, ‘high’, ‘medium’, ‘very_high’,’low’].
Return type:: Tuple[Dict[Any, str], List]

dispel.providers.ads.tasks.grip.time_defined_plateau(data, level, plateau)[source]#

Extract time-defined plateau.

This function extracts the plateaus as defined in the plateau modality. More formally, given a level that is defined by the following time windows: [start: end]. The plateau offset refines this time windows only keeping the section [start + plateau.start_offset: end - plateau.end_offset].

Parameters:

data (DataFrame) – A data frame such as the one obtained after resampling screen. e.g.: screen_ts_resampled
level (Level) – Any Level
plateau (PlateauModality) – A plateau modality defining the time windows on which measures will be computed.

Returns:

A data frame with three columns: detected-plateau is equals to the pressure on the plateau zero otherwise. level-sequence are integers indicating the level. refined-target is the target value.

Return type:

pandas.DataFrame