feature extractor

class BaseExtractor(*, features=None, dyadic_features=None, cache_mode=True, cache_directory=None, pipeline=None)

Bases: ABC, Generic

The base class for feature extractors.

Allows the following keyword arguments in feature functions:

  • as_absolute: Whether to return the absolute value of the feature.

  • as_sign_change_latency: Whether to return the latency of sign changes in the feature.

  • reversed_dyad: Whether to reverse the order of the dyad for feature computation.

Parameters:

  • features (list[tuple[Feature, Mapping[str, Any]]] | None, default: None) – The features to extract.

  • dyadic_features (list[tuple[Feature, Mapping[str, Any]]] | None, default: None) – The dyadic features to extract.

  • cache_mode (Literal['cached'] | bool, default: True) – Whether to use caching or to allow only precomputed features.

  • cache_directory (str | Path | None, default: None) – The directory to use for caching.

  • pipeline (Pipeline | None, default: None) – The pipeline to use for further feature transformation.

adjust_function(function, as_absolute=False, as_sign_change_latency=False, **kwargs)

Adjust a feature function to be either absolute or sign change latency.

Parameters:

  • function (Feature) – The feature function to adjust.

  • as_absolute (bool, default: False) – Whether to adjust the feature function to be absolute.

  • as_sign_change_latency (bool, default: False) – Whether to adjust the feature function to be sign change latency.

  • kwargs (Any)

Return type:

Feature

Returns:

The adjusted feature function.

Raises:

ValueError – If both as_absolute=True and as_sign_change_latency=True.

allowed_additional_kwargs: tuple[str, ...] = ('as_absolute', 'as_sign_change_latency', 'reversed_dyad')
abstract classmethod concatenate(*args, axis=1, **kwargs)
Return type:

TypeVar(F, bound= Shaped)

Parameters:

  • args (F)

  • axis (int)

  • kwargs (Any)

property config: dict[Literal['individual', 'dyadic'], tuple[tuple[str, dict[str, Hashable]], ...]]

The configuration of the extractor, returned as a dictionary.

abstract classmethod empty()

Returns an empty feature object, type depending on the implementation in the subclass.

Return type:

TypeVar(F, bound= Shaped)

extract(trajectory, trajectory_other=None, *, indices=None)

Extract features from a trajectory.

If the trajectory_other argument is None and dyadic features are specified, a warning is raised.

Parameters:

  • trajectory (Trajectory) – The trajectory to extract features from.

  • trajectory_other (Trajectory | None, default: None) – The other trajectory in a dyad when extracting dyadic features.

  • indices (ndarray | None)

Returns:

The computed features. The type depends on the subclass.

Return type:

Any

extract_features(trajectory, trajectory_other=None, *, category)

Extract features of one category ('individual' or 'dyadic') from a trajectory. If the category is 'dyadic', the trajectory_other argument must be provided.

Parameters:

  • trajectory (Trajectory) – The trajectory to extract features from.

  • trajectory_other (Trajectory | None, default: None) – A second trajectory, used for dyadic features.

  • category (Literal['individual', 'dyadic']) – The category of the features to extract.

Return type:

TypeVar(F, bound= Shaped)

Returns:

The extracted features.

property feature_names: list[str]

The names of all features (both individual and dyadic).

load(features_config)

Load the extractor configuration from a dictionary.

Parameters:

features_config (dict[Literal['individual', 'dyadic'], list[tuple[str, Mapping[str, Any]]]]) – The configuration to load.

Return type:

Self

Returns:

The feature extractor after loading the configuration.

read_yaml(features_config_file)

Load the extractor configuration from a yaml file.

Parameters:

features_config_file (str) – The path to the yaml file to load the configuration from.

Return type:

Self

save_yaml(features_config_file)

Save the extractor configuration to a yaml file.

Parameters:

features_config_file (str) – The path to the yaml file to save the configuration to.

Return type:

None

abstract select_indices(X, *, indices)
Return type:

TypeVar(F, bound= Shaped)

Parameters:
property sha1

The SHA1 hash (digest) of the extractor configuration.

class DataFrameFeatureExtractor(*, features=None, dyadic_features=None, cache_mode=True, cache_directory=None, pipeline=None)

Bases: BaseExtractor[DataFrame]

A subclass to extract features as pandas DataFrames (DataFrame).

Extends the additional keyword arguments that can be passed to the feature functions to ("as_absolute", "as_sign_change_latency", "keep", "discard").

Parameters:
adjust_function(function, as_absolute=False, as_sign_change_latency=False, keep=None, discard=None, **kwargs)

Adjust a feature function to be a dataframe feature.

Parameters:

  • function (Feature) – The feature function to adjust.

  • as_absolute (bool, default: False) – Whether to adjust the feature function to be absolute.

  • as_sign_change_latency (bool, default: False) – Whether to adjust the feature function to be sign change latency.

  • keep (list[str] | str | None, default: None) – Patterns in the feature names to keep. This can be used to keep features that would otherwise be discarded.

  • discard (list[str] | str | None, default: None) – Patterns in the feature names to discard.

  • kwargs (Any)

Return type:

DataFrameFeature

Returns:

The adjusted feature function.

allowed_additional_kwargs: tuple[str, ...] = ('as_absolute', 'as_sign_change_latency', 'reversed_dyad', 'keep', 'discard')
classmethod concatenate(*args, axis=1, **kwargs)

Concatenate the computed features as a pandas DataFrame.

Parameters:

  • *args (DataFrame) – The computed features.

  • axis (int, default: 1) – The axis to concatenate along.

  • kwargs (Any)

Return type:

DataFrame

Returns:

The concatenated features.

classmethod empty()

Returns an empty DataFrame.

Return type:

DataFrame

select_indices(X, *, indices)
Return type:

DataFrame

Parameters:
class FeatureExtractor(*, features=None, dyadic_features=None, cache_mode=True, cache_directory=None, pipeline=None)

Bases: BaseExtractor[ndarray]

A subclass to extract features as numpy arrays (ndarray).

Parameters:
classmethod concatenate(*args, axis=1, **kwargs)

Concatenate the computed features.

Parameters:

  • *args (ndarray) – The computed features.

  • axis (int, default: 1) – The axis to concatenate along.

  • kwargs (Any)

Return type:

ndarray

Returns:

The concatenated features.

classmethod empty()

Returns an empty ~numpy.ndarray.

Return type:

ndarray

select_indices(X, *, indices)
Return type:

ndarray

Parameters:
class Shaped(*args, **kwargs)

Bases: Protocol

The minimum requirement of extracted features. Both numpy arrays and pandas DataFrames are supported.

property shape: tuple[int, ...]
load_feature_func(func_name)

Helper function to get a feature function (from features) from its name.

Parameters:

func_name (str) – The name of the feature function.

Returns:

The feature function.

Return type:

utils.Feature

Raises:

ValueError – If the feature function is not implemented in the features module.