dispel.providers.generic.activity.turning module

A module to detect and process turns during tests.

class dispel.providers.generic.activity.turning.AggregateAbsTurnSpeed

Bases: TurnModalityMixIn, AggregateRawDataSetColumn

Aggregate absolute turn speed based on modality.

aggregations: AggregationsDefinitionType = [('mean', 'mean'), ('std', 'standard deviation'), ('median', 'median'), ('min', 'minimum'), ('max', 'maximum')]

definition: ValueDefinition | ValueDefinitionPrototype | None = <dispel.data.measures.MeasureValueDefinitionPrototype object>

The specification of the measure definition

class dispel.providers.generic.activity.turning.AggregateTurnDuration

Bases: TurnModalityMixIn, AggregateRawDataSetColumn

Aggregate turn duration based on modality.

aggregations: AggregationsDefinitionType = [('mean', 'mean'), ('std', 'standard deviation'), ('median', 'median'), ('min', 'minimum'), ('max', 'maximum')]

definition: ValueDefinition | ValueDefinitionPrototype | None = <dispel.data.measures.MeasureValueDefinitionPrototype object>

The specification of the measure definition

class dispel.providers.generic.activity.turning.AggregateTurnSpeedProperties

Bases: TurnModalityMixIn, AggregateRawDataSetColumn

Aggregate properties based on modality.

__init__(turn_modality, data_set_id, column_id)

class dispel.providers.generic.activity.turning.ElGoharyTurnDetection

Bases: TransformStep

El Gohary et al. turn detection processing step.

This processing step is to apply the el_gohary_detect_turns() to an angular velocity time series that has undergone the described filtering.

Parameters:

component – The column name of the series contained in raw data set.

__init__(component, *args, **kwargs)

Parameters:

component (str) –

definitions: List[RawDataValueDefinition] = [<RawDataValueDefinition: start (The start of the turn)>, <RawDataValueDefinition: end (The end of the turn)>, <RawDataValueDefinition: duration (The duration of the turn, s)>, <RawDataValueDefinition: angle (The angle of the turn, rad)>, <RawDataValueDefinition: turn_cls (The Turn class)>]

get_new_data_set_id()

Get the id of the new data set to be created.

Return type:

str

class dispel.providers.generic.activity.turning.ExtractNumberOfTurns

Bases: TurnModalityMixIn, ExtractStep

Extract the number of turns during the utt test.

definition: ValueDefinition | ValueDefinitionPrototype | None = <dispel.data.measures.MeasureValueDefinitionPrototype object>

The specification of the measure definition

transform_function()

Return the number of items in a container.

class dispel.providers.generic.activity.turning.ExtractTurnMeasures

Bases: ProcessingStepGroup

Extract Turn Measures based on Turn Selection Modality.

__init__(turns_data_set_id, turn_modality, **kwargs)

class dispel.providers.generic.activity.turning.RefineTurns

Bases: TransformStep

El Gohary et al. turn detection processing step.

This processing step is to apply the el_gohary_detect_turns() to a angular velocity time series that has undergone the described filtering.

Parameters:

component – The column name of the series contained in raw data set.

__init__(component, *args, **kwargs)

Parameters:

component (str) –

definitions: List[RawDataValueDefinition] = [<RawDataValueDefinition: start (The start of the turn)>, <RawDataValueDefinition: end (The end of the turn)>, <RawDataValueDefinition: duration (The duration of the turn, s)>, <RawDataValueDefinition: angle (The angle of the turn, rad)>, <RawDataValueDefinition: turn_cls (The Turn class)>]

get_new_data_set_id()

Get new data set id.

Return type:

str

th_time = Timedelta('0 days 00:00:00.300000')

class dispel.providers.generic.activity.turning.RefineUTurns

Bases: TransformStep

Refine Turns based on assumption of 180 degrees.

This processing step is to consecutive turns occuring soon after another and merge them if they are smaller than a threshold.

Parameters:

component – The column name of the series contained in raw data set.

__init__(component, *args, **kwargs)

Parameters:

component (str) –

definitions: List[RawDataValueDefinition] = [<RawDataValueDefinition: start (The start of the turn)>, <RawDataValueDefinition: end (The end of the turn)>, <RawDataValueDefinition: duration (The duration of the turn, s)>, <RawDataValueDefinition: angle (The angle of the turn, rad)>, <RawDataValueDefinition: turn_cls (The Turn class)>]

get_new_data_set_id()

Get new data set id.

Return type:

str

th_curr = 2.9670597283903604

th_last = 2.9670597283903604

th_min = 1.5707963267948966

th_sum = 4.71238898038469

th_time = Timedelta('0 days 00:00:03')

class dispel.providers.generic.activity.turning.TransformAbsTurnSpeed

Bases: TransformStep

Get absolute turns speed.

definitions: List[RawDataValueDefinition] = [<RawDataValueDefinition: abs_turn_speed (The absolute value of the average turn speed)>]

new_data_set_id: str = 'abs_turn_speed'

class dispel.providers.generic.activity.turning.Turn

Bases: object

Class to encapsulate turns and turn related gyroscope data.

Parameters:

• start – The start date time of the turn.

• end – The end date time of the turn.

• data – The angular velocity time series of the turn. The data set should ensure to be at least of the duration of time provided with start and end. It should be in rad/s and sampling has to be at a constant frequency.

start

The start date time of the turn.

end

The end date time of the turn.

__init__(start, end, data)

Parameters:

• start (datetime) –

• end (datetime) –

• data (Series) –

property angle: float

Get the angle of the turn.

Returns:

The angle of the turn in rad/s.

Return type:

float

property data: Series

Get the angular velocity data associated with the turn.

Returns:

Angular velocity series between start and end of the turn.

Return type:

pandas.Series

property direction: int

Get the direction of the turn.

Returns:

The direction of the turn. If the turning direction is positive 1 is returned. Otherwise -1.

Return type:

int

property duration: float

Get the duration of the turn.

Returns:

The duration of the turn in seconds.

Return type:

float

expand(threshold)

Expand the start and end of the turn to the given threshold.

This expands the turn until start and end are below the provided threshold of turn speed. The expansion relies on the data provided during the construction of the turn and should not be confused with what is available via data, which is always limited to the boundaries specified with start and end.

Parameters:

threshold (float) – The threshold until which to expand the turn.

Returns:

A new turn with expanded start and end time stamps based on associated data.

Return type:

Turn

merge(other)

Merge this turn with another one.

Parameters:

other – The other turn to merge this one with.

Returns:

The new merged turn. The new turn uses the earlier start and later end of both, respectively. The data will be based on this turn.

Return type:

Turn

class dispel.providers.generic.activity.turning.TurnModality

Bases: AVEnum

An enumeration for turn modalities.

ALL = 1

FIRST_FIVE = 2

FIRST_FOUR = 3

TWO_THREE_FOUR = 4

class dispel.providers.generic.activity.turning.TurnModalityMixIn

Bases: MeasureDefinitionMixin, DataSetProcessingStepMixin

A modality to filter on subsets of turns.

Parameters:

turn_modality – A TurnModality object denoting the turns to be used.

__init__(turn_modality, *args, **kwargs)

Parameters:

turn_modality (TurnModality) –

get_data_frames(level)

Get data frames.

Parameters:

level (Level) –

Return type:

List[DataFrame]

get_definition(**kwargs)

Get definition.

class dispel.providers.generic.activity.turning.WithinTurnSpeed

Bases: TransformStep

Compute within-turn properties of the turn speed.

This processing step is to compute sensor-derived aggregated properties of the angular velocity signal within each turn.

Parameters:

component – The column name of the series contained in raw data set.

__init__(component, *args, **kwargs)

Parameters:

component (str) –

definitions: List[RawDataValueDefinition] = [<RawDataValueDefinition: mean (mean of turn speed across a turn, rad/s)>, <RawDataValueDefinition: q95 (95th centile of turn speed across a turn, rad/s)>]

get_new_data_set_id()

Get new data set id.

Return type:

str

dispel.providers.generic.activity.turning.el_gohary_detect_turns(data)

Detect turns based on the El Gohary et al. algorithm [1] .

This method performs the detection after aligning and filtering the gyroscope time series (see El Gohary et al. algorithm 1, row 4).

Parameters:

data (Series) – A pandas series of angular velocity used to search for turns.

Returns:

A list of detected turns.

Return type:

List[Turn]

References

[1]

El-Gohary, Mahmoud, et al. “Continuous monitoring of turning in patients with movement disability.” Sensors 14.1 (2014): 356-369. https://doi.org/10.3390/s140100356

dispel.providers.generic.activity.turning.merge_turns(turns, th_time=Timedelta('0 days 00:00:00'), th_curr=inf, th_last=inf, th_sum=inf)

Merge turns that add up to approximately u-turns.

This function takes a list of turns and merges each of them with its preceding turn if that ended less than a time threshold ago and the consecutive turns are below a set of thresholds in size.

Parameters:

• turns (List[Turn]) – A list of Turn objects to be potentially merged.

• th_time (Timedelta) – A pandas.Timedelta containing the maximum time distance between turns that should be used for merging.

• th_curr (float) – A float indicating the maximum value of the current turn to be considered for merging

• th_last (float) – A float indicating the maximum value of the last turn to be considered for merging

• th_sum (float) – A float indicating the maximum value of the sum of current and previous turn to be considered for merging

Returns:

A list of merged turns.

Return type:

List[Turn]

dispel.providers.generic.activity.turning.refine_turns(data, turns_df, th_time=Timedelta('0 days 00:00:00'), th_curr=inf, th_last=inf, th_sum=inf, th_min=0.0)

Refine turns from El-Gohary output.

This function refines turns by merging consecutive turns with time distance (defined as the period between the end of a turn and the start of the next) less than a specified threshold as well as a set of thresholds constraining the size of refined merged angles.

Parameters:

• data (Series) – A pandas series of angular velocity used to search for turns.

• turns_df (DataFrame) – A pd.DataFrame containing the turns to be refined.

• th_time (Timedelta) – A pandas.Timedelta containing the maximum time distance between turns that should be used for merging.

• th_curr (float) – A float indicating the maximum value of the current turn to be considered for merging (in radians)

• th_last (float) – A float indicating the maximum value of the last turn to be considered for merging (in radians)

• th_sum (float) – A float indicating the maximum value of the sum of current and previous turn to be considered for merging (in radians)

• th_min (float) – A float indicating the minimum value of the angles to be kept in the data (in radians)

Returns:

A list of refined turns.

Return type:

List[Turn]

dispel.providers.generic.activity.turning.remove_turns_below_thres(turns, th_min=0.0)

Remove turns that are below a given threshold.

This function receives a list of turns and removes the ones that are lower than a given threshold.

Parameters:

• turns (List[Turn]) – A list of Turn objects to be potentially merged.

• th_min (float) – Minimum angle in radians

Returns:

A list of merged turns.

Return type:

List[Turn]