Catch22¶

class Catch22(features='all', catch24=False, outlier_norm=True, replace_nans=False, use_pycatch22=False, n_jobs=1, parallel_backend=None)[source]¶

Bases: BaseCollectionTransformer

Canonical Time-series Characteristics (Catch22).

Overview: Input n series with d dimensions of length m. Transforms series into the 22 Catch22 [1] features extracted from the hctsa [R0686c85ef67c-2] toolbox.

Parameters:

featuresint/str or List of int/str, default=”all”

The Catch22 features to extract by feature index, feature name as a str or as a list of names or indices for multiple features. If “all”, all features are extracted. Valid features are as follows:

[“DN_HistogramMode_5”, “DN_HistogramMode_10”, “CO_f1ecac”,”CO_FirstMin_ac”, “CO_HistogramAMI_even_2_5”, “CO_trev_1_num”, “MD_hrv_classic_pnn40”, “SB_BinaryStats_mean_longstretch1”, “SB_TransitionMatrix_3ac_sumdiagcov”, “PD_PeriodicityWang_th0_01”, “CO_Embed2_Dist_tau_d_expfit_meandiff”, “IN_AutoMutualInfoStats_40_gaussian_fmmi”, “FC_LocalSimple_mean1_tauresrat”, “DN_OutlierInclude_p_001_mdrmd”, “DN_OutlierInclude_n_001_mdrmd”, “SP_Summaries_welch_rect_area_5_1”, “SB_BinaryStats_diff_longstretch0”, “SB_MotifThree_quantile_hh”, “SC_FluctAnal_2_rsrangefit_50_1_logi_prop_r1”, “SC_FluctAnal_2_dfa_50_1_2_logi_prop_r1”, “SP_Summaries_welch_rect_centroid”, “FC_LocalSimple_mean3_stderr”]

Shortened:: [“mode_5”, “mode_10”, “acf_timescale”, “acf_first_min”, “ami2”, “trev”, “high_fluctuation”, “stretch_high”, “transition_matrix”, “periodicity”, “embedding_dist”, “ami_timescale”, “whiten_timescale”, “outlier_timing_pos”, “outlier_timing_neg”, “centroid_freq”, “stretch_decreasing”, “entropy_pairs”, “rs_range”, “dfa”, “low_freq_power”, “forecast_error”]

catch24bool, default=False

Extract the mean and standard deviation as well as the 22 Catch22 features if true. If a List of specific features to extract is provided, “Mean” and/or “StandardDeviation” must be added to the List to extract these features.

outlier_normbool, optional, default=False

If True, each time series is normalized during the computation of the two outlier Catch22 features, which can take a while to process for large values as it depends on the max value in the timseries. Note that this parameter did not exist in the original publication/implementation as they used time series that were already normalized.

replace_nansbool, default=False

Replace NaN or inf values from the Catch22 transform with 0.

use_pycatch22bool, optional, default=False

Wraps the C based pycatch22 implementation for aeon. (https://github.com/DynamicsAndNeuralSystems/pycatch22). This requires the pycatch22 package to be installed if True.

n_jobsint, default=1

The number of jobs to run in parallel for transform. Requires multiple input cases. -1 means using all processors.

parallel_backendstr, ParallelBackendBase instance or None, default=None

Specify the parallelisation backend implementation in joblib, if None a ‘prefer’ value of “threads” is used by default. Valid options are “loky”, “multiprocessing”, “threading” or a custom backend. See the joblib Parallel documentation for more details.

Attributes:

get_features_arguments: Return feature names for the estimators features argument.

See also

Catch22Classifier

Notes

Capabilities ¶
Missing Values	No
Multithreading	Yes
Inverse Transform	No
Univariate	Yes
Multivariate	Yes
Unequal Length	Yes

Original Catch22 package implementations: https://github.com/DynamicsAndNeuralSystems/Catch22

For the Java version, see https://github.com/uea-machine-learning/tsml/blob/master/src/main/java /tsml/transformers/Catch22.java

References

[1]

Lubba, C. H., Sethi, S. S., Knaute, P., Schultz, S. R., Fulcher, B. D., &

Jones, N. S. (2019). catch22: Canonical time-series characteristics. Data Mining and Knowledge Discovery, 33(6), 1821-1852. .. [R0686c85ef67c-2] Fulcher, B. D., Little, M. A., & Jones, N. S. (2013). Highly comparative time-series analysis: the empirical structure of time series and their methods. Journal of the Royal Society Interface, 10(83), 20130048.

Examples

>>> from aeon.transformations.collection.feature_based import Catch22
>>> from aeon.testing.data_generation import make_example_3d_numpy
>>> X = make_example_3d_numpy(n_cases=4, n_channels=1, n_timepoints=10,
...                           random_state=0, return_y=False)
>>> tnf = Catch22(replace_nans=True)
>>> tnf.fit(X)
Catch22(...)
>>> print(tnf.transform(X)[0])
[1.15639531e+00 1.31700577e+00 5.66227710e-01 2.00000000e+00
 3.89048349e-01 2.33853577e-01 1.00000000e+00 3.00000000e+00
 8.23045267e-03 0.00000000e+00 1.70859420e-01 2.00000000e+00
 1.00000000e+00 7.00000000e-01 2.00000000e-01 1.10933565e-32
 4.00000000e+00 2.04319187e+00 0.00000000e+00 0.00000000e+00
 1.96349541e+00 5.51667002e-01]

Methods

`clone`([random_state])	Obtain a clone of the object with the same hyperparameters.
`fit`(X[, y])	Fit transformer to X, optionally using y if supervised.
`fit_transform`(X[, y])	Fit to data, then transform it.
`get_class_tag`(tag_name[, raise_error, ...])	Get tag value from estimator class (only class tags).
`get_class_tags`()	Get class tags from estimator class and all its parent classes.
`get_fitted_params`([deep])	Get fitted parameters.
`get_params`([deep])	Get parameters for this estimator.
`get_tag`(tag_name[, raise_error, ...])	Get tag value from estimator class.
`get_tags`()	Get tags from estimator.
`reset`([keep])	Reset the object to a clean post-init state.
`set_params`(**params)	Set the parameters of this estimator.
`set_tags`(**tag_dict)	Set dynamic tags to given values.
`transform`(X[, y])	Transform X and return a transformed version.

clone(random_state=None)[source]¶

Obtain a clone of the object with the same hyperparameters.

A clone is a different object without shared references, in post-init state. This function is equivalent to returning sklearn.clone of self. Equal in value to type(self)(**self.get_params(deep=False)).

Parameters:

random_stateint, RandomState instance, or None, default=None: Sets the random state of the clone. If None, the random state is not set. If int, random_state is the seed used by the random number generator. If RandomState instance, random_state is the random number generator.

Returns:

estimatorobject: Instance of type(self), clone of self (see above)

fit(X, y=None)[source]¶

Fit transformer to X, optionally using y if supervised.

Writes to self: - is_fitted : flag is set to True. - model attributes (ending in “_”) : dependent on estimator

Parameters:

Xnp.ndarray or list

Data to fit transform to, of valid collection type. Input data, any number of channels, equal length series of shape ( n_cases, n_channels, n_timepoints) or list of numpy arrays (number of channels, series length) of shape [n_cases], 2D np.array (n_channels, n_timepoints_i), where n_timepoints_i is length of series i. Other types are allowed and converted into one of the above.

Different estimators have different capabilities to handle different types of input. If self.get_tag("capability:multivariate") is False, they cannot handle multivariate series. If self.get_tag( "capability:unequal_length") is False, they cannot handle unequal length input. In both situations, a ValueError is raised if X has a characteristic that the estimator does not have the capability to handle.

ynp.ndarray, default=None

1D np.array of float or str, of shape (n_cases) - class labels (ground truth) for fitting indices corresponding to instance indices in X. If None, no labels are used in fitting.

Returns:

selfa fitted instance of the estimator

fit_transform(X, y=None)[source]¶

Fit to data, then transform it.

Fits the transformer to X and y and returns a transformed version of X.

State change:: Changes state to “fitted”.

Writes to self: _is_fitted : flag is set to True. model attributes (ending in “_”) : dependent on estimator.

Parameters:

Xnp.ndarray or list

ynp.ndarray, default=None

1D np.array of float or str, of shape (n_cases) - class labels (ground truth) for fitting indices corresponding to instance indices in X. If None, no labels are used in fitting.

Returns:

transformed version of X

classmethod get_class_tag(tag_name, raise_error=True, tag_value_default=None)[source]¶

Get tag value from estimator class (only class tags).

Parameters:

tag_namestr: Name of tag value.
raise_errorbool, default=True: Whether a ValueError is raised when the tag is not found.
tag_value_defaultany type, default=None: Default/fallback value if tag is not found and error is not raised.

Returns:

tag_value: Value of the tag_name tag in cls. If not found, returns an error if raise_error is True, otherwise it returns tag_value_default.

Raises:

ValueError: if raise_error is True and tag_name is not in self.get_tags().keys()

Examples

>>> from aeon.classification import DummyClassifier
>>> DummyClassifier.get_class_tag("capability:multivariate")
True

classmethod get_class_tags()[source]¶

Get class tags from estimator class and all its parent classes.

Returns:

collected_tagsdict: Dictionary of tag name and tag value pairs. Collected from _tags class attribute via nested inheritance. These are not overridden by dynamic tags set by set_tags or class __init__ calls.

property get_features_arguments¶: Return feature names for the estimators features argument.

get_fitted_params(deep=True)[source]¶

Get fitted parameters.

State required:: Requires state to be “fitted”.

Parameters:

deepbool, default=True: If True, will return the fitted parameters for this estimator and contained subobjects that are estimators.

Returns:

fitted_paramsdict: Fitted parameter names mapped to their values.

get_params(deep=True)¶

Get parameters for this estimator.

Parameters:

deepbool, default=True: If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict: Parameter names mapped to their values.

get_tag(tag_name, raise_error=True, tag_value_default=None)[source]¶

Get tag value from estimator class.

Includes dynamic and overridden tags.

Parameters:

tag_namestr: Name of tag to be retrieved.
raise_errorbool, default=True: Whether a ValueError is raised when the tag is not found.
tag_value_defaultany type, default=None: Default/fallback value if tag is not found and error is not raised.

Returns:

tag_value: Value of the tag_name tag in self. If not found, returns an error if raise_error is True, otherwise it returns tag_value_default.

Raises:

ValueError: if raise_error is True and tag_name is not in self.get_tags().keys()

Examples

>>> from aeon.classification import DummyClassifier
>>> d = DummyClassifier()
>>> d.get_tag("capability:multivariate")
True

get_tags()[source]¶

Get tags from estimator.

Includes dynamic and overridden tags.

Returns:

collected_tagsdict: Dictionary of tag name and tag value pairs. Collected from _tags class attribute via nested inheritance and then any overridden and new tags from __init__ or set_tags.

reset(keep=None)[source]¶

Reset the object to a clean post-init state.

After a self.reset() call, self is equal or similar in value to type(self)(**self.get_params(deep=False)), assuming no other attributes were kept using keep.

Detailed behaviour:

removes any object attributes, except:: hyper-parameters (arguments of __init__) object attributes containing double-underscores, i.e., the string “__”

runs __init__ with current values of hyperparameters (result of get_params)

Not affected by the reset are:

object attributes containing double-underscores class and object methods, class attributes any attributes specified in the keep argument

Parameters:

keepNone, str, or list of str, default=None: If None, all attributes are removed except hyperparameters. If str, only the attribute with this name is kept. If list of str, only the attributes with these names are kept.

Returns:

selfobject: Reference to self.

Raises:

TypeError: If ‘keep’ is not a string or a list of strings.

set_params(**params)¶

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict: Estimator parameters.

Returns:

selfestimator instance: Estimator instance.

set_tags(**tag_dict)[source]¶

Set dynamic tags to given values.

Parameters:

**tag_dictdict: Dictionary of tag name and tag value pairs.

Returns:

selfobject: Reference to self.

transform(X, y=None)[source]¶

Transform X and return a transformed version.

State required:: Requires state to be “fitted”.

Accesses in self: _is_fitted : must be True fitted model attributes (ending in “_”) : must be set, accessed by _transform

Parameters:

Xnp.ndarray or list

ynp.ndarray, default=None

1D np.array of float or str, of shape (n_cases) - class labels (ground truth) for fitting indices corresponding to instance indices in X. If None, no labels are used in fitting.

Returns:

transformed version of X