utils¶

class DataFrameFeature(*args, **kwargs)¶

Bases: Protocol

A dataframe feature is a function that takes a Trajectory or an InstanceCollection as input and returns a DataFrame.

Parameters:

trajectory (Trajectory | InstanceCollection) – The trajectory or collection to compute the feature for. Parameter can also be called collection.
*args – Additional positional arguments.
**kwargs – Additional keyword arguments.

Returns:

The computed feature.

Return type:

DataFrame

class Feature(*args, **kwargs)¶

Bases: Protocol

A feature is a function that takes a Trajectory or an InstanceCollection as input and returns a ndarray.

Parameters:

trajectory (Trajectory | InstanceCollection) – The trajectory or collection to compute the feature for. Parameter can also be called collection.
*args – Additional positional arguments.
**kwargs – Additional keyword arguments.

Returns:

The computed feature.

Return type:

ndarray

feature_names(func, relational, dyadic=False, suffixes=None, **kwargs)¶

Generate full feature names for a given function.

Parameters:

func (Feature) – The function to generate feature names for.
relational (bool) – Whether the function is relational.
dyadic (bool, default: False) – Whether the function is dyadic.
suffixes (Iterable[str] | None, default: None) – Optional suffixes to append to the feature names.
kwargs (Any)

Return type:

list[str]

Returns:

The full feature names.

get_feature_names(func, **kwargs)¶

Entrypoint for feature name generation.

Parameters:

func (Feature) – The feature function to generate names for.
**kwargs – Additional keyword arguments to pass to the feature function.

Return type:

list[str]

Returns:

A list of feature names corresponding to the function.

See also

feature_names() to generate feature names, using:
names() to generate feature names, or,
relational_names() to generate feature names for relational features

names(func_name, keypoints=None, keypoint_pairs=None)¶

Return the formatted feature names of a feature function, and a combination of keypoints and keypoint pairs.

Parameters:

func_name (str) – The name of the feature function.
keypoints (Iterable[int] | None, default: None) – The keypoint indices.
keypoint_pairs (Iterable[tuple[int, int]] | None, default: None) – The keypoint index pairs.

Return type:

list[str]

Returns:

The formatted feature names.

pair(keypoint_pair)¶

Return the formatted name of a keypoint pair.

Parameters:: keypoint_pair (tuple[int, int]) – The keypoint pair to get the name of.
Return type:: str
Returns:: The name of the keypoint pair.

prune_feature_names(names, *, keep=None, discard=None)¶

Discard (or keep) feature names based on a list of names to keep or discard.

Return type:

list[str]

Parameters:

names (Iterable[str])
keep (Iterable[str] | str | None)
discard (Iterable[str] | str | None)

Parameters: names: The feature names to prune. keep: A list of feature name patterns to keep, irregardless of the match discard. discard: A list of feature name patterns to discard.
Returns: A list of feature names after pruning.

recursive_name(func)¶

Return the name of a feature function.

If the function is a partial() (i.e., decorated), the name of the original function is returned.

Parameters:: func (Feature | DataFrameFeature | partial) – The feature function to get the name of.
Return type:: str
Returns:: The name of the feature function.

relational_names(func_name, *, keypoints_1=None, keypoints_2=None, keypoint_pairs_1=None, keypoint_pairs_2=None, element_wise=False)¶

Return the formatted feature names of a relational feature function, and a combination of keypoints and keypoint pairs.

Parameters:

func_name (str) – The name of the feature function.
keypoints_1 (Iterable[int] | None, default: None) – The first set of keypoints indices.
keypoints_2 (Iterable[int] | None, default: None) – The second set of keypoints indices.
keypoint_pairs_1 (Iterable[tuple[int, int]] | None, default: None) – The first set of keypoint index pairs.
keypoint_pairs_2 (Iterable[tuple[int, int]] | None, default: None) – The second set of keypoint index pairs.
element_wise (bool | None, default: False) – Whether to return the names of the feature function for each element-wise combination of keypoints and keypoint pairs.

Return type:

list[str]

Returns:

The formatted feature names.