timefeatures module¶

class timefeatures.TimeFeatures(data, labels, tmin, tmax, channel_names, label_names, srate, reaction_times=[], name=[])¶

Bases: object

Class for the extraction and visualization of features across time from the raw amplitude data. Visualize the evolution of different features over a time course [tmin, tmax], for multiples trials, for multiple conditions. The condition of each trial is defined by the labels vector. The original data is given by the 3D array data_ori (size: [n_features, n_pnts, n_trials]) which usually represents the amplitude of each channel. From these original data, other feature can be computed using the feature_extracter attribute, which will be stored in the data attribute.

Attributes:

data_ori : array (size: n_channels*n_pnts*n_trials) Original amplitude data. Other features will be computed from this. data : array (size: n_features*n_pnts*n_trials) Features data. Contain all the features concatenated. tmin : float Starting time (s) tmax : float Ending time (s) srate : float Sampling frequency (Hz) name : str A string identifying the time features times : array Time vector from tmin to tmax n_chan : int Number of channels n_pnts : int Number of time points n_trials : int Number of trials n_features : int Number of features n_labels : int Number of different conditions labels : array (size: n_trials) Condition of each trial represented by a number. Name of the associated condition can be accessed from the label_dict attribute channel_names : array (size: n_features) Name of each channel feature_names : array (size: n_features) Name of each feature feature_type : array (size: n_features) Type of each feature (e.g. : ‘amplitude’, ‘phase alpha’, …) feature_channame : array (size: n_features) Name of the channel associated with each feature label_dict : dict Dictionnary containing the condition name reaction_times : array (size: n_trials) Can be defined for some trials involving a timed response preprocessing_done : bool True if preprocessing has been done, False otherwise feature_extracter : featureextracter.FeatureExtracter instance Used to compute feature from the original data

Methods

add_feature(feat_mat, feat_name, feat_type, …)	Add the feature matrix feat_mat to the existing features in data attribute.
add_trials(trials_mat, label_id, label_name)	Add trials related to a new or already existing label
cluster_data(cluster_algo[, do_plot, ax, cb_ax])	Cluster the data selected by **kwargs - see timefeatures.get_data() - Return the cross-tabulation of the predicted versus true labels
compute_correlation_feature_target(**kwargs)	Compute and plot the correlation between the selected features for 2 specified conditions.
compute_correlation_hits_reaction_times([…])	Compute and plot the correlation (Pearson or Spearman) between selected features and reaction times (if defined).
compute_feature_importance(label_keys[, …])	Compute feature importance using forest of decitions trees.
extract_feature([feature_type])	Compute features from the original data data_ori and add them to the feature array data
feature_name2pos(feature_sel_names)	Return the feature names from the feature positions
feature_pos2name(feature_pos)	Return the feature position from the feature names
get_data(**kwargs)	Select the data corresponding to selected feature and/or labels and/or time points.
get_feature_pos([feature_pos, feature_type, …])	Get the feature position from feature type or/and feature channel name
get_label_key_from_value(dict_value)	Return the label key from the value of the dictionnary attribute label_dict
interactive_feature_rt_correlation([…])	Interactive plot of the correlation between feature and reaction times (for hits trials)
plot_feature_distribution([ax])	Plot the distribution of features at a certain time point for selected labels.
plot_feature_erp([plot_traces, ax])	Plot the feature evolution across time.
plot_feature_erpimage([ax, cax])	Plot the erp-image of the selected features
plot_feature_hits_reaction_time([scaling, …])	Plot the reaction time in function of the feature.
sample2time(sample)	Return the time in seconds from the sample index
save([dir_path, filename, filename_desc])	Save the time features instance to a pickle file using the pickle module.
sort_features([sorting_variable])	Sort the features according to sorting_variable
sort_trials([sorting_variable, direction])	Sort the data trial order given the sorting variable.
time2sample(t_sec)	Return the sample index from the time in seconds

add_feature(feat_mat, feat_name, feat_type, feat_channame)¶

Add the feature matrix feat_mat to the existing features in data attribute. Update feature_name, feature_channame and feature_type attributes.

Parameters:	feat_mat : array (size: n_new_features*n_pnts*n_trials) New feature array, to add to the existing features feat_name : array (size: n_new_features) Name of the new features feat_type : array (size: n_new_features) Type of the new features feat_channame : array (size: n_new_features) Channel’s name of the new features

add_trials(trials_mat, label_id, label_name, reaction_times=[])¶

Add trials related to a new or already existing label

Parameters:	trials_mat : array (size: n_features*n_pnts*n_new_trials) New trials array, to add to the existing trials label_id : int New trials label id label_name : str New trials label name reaction_times : array (size: n_new_trials) | None (default) If reaction times are associated with the new trials, supply it here

cluster_data(cluster_algo, do_plot=False, ax=[], cb_ax=[], **kwargs)¶

Cluster the data selected by **kwargs - see timefeatures.get_data() - Return the cross-tabulation of the predicted versus true labels

Parameters:

cluster_algo : str Clustering algorithm name. Possible values: [‘kmeans’, ‘affinitypropagation’, ‘spectralclustering’, ‘agglomerativeclustering’, ‘dbscan’] do_plot : bool If True, plot the clustering results ax : matplotlib axis | None Axis to plot on cb_ax : matplotlib axis | None Axis for the colorbar kwargs : Data selection parameters. Can be feature_pos, feature_type, feature_channame, label_keys, time_points. See get_data()

Returns:

ct : pandas DataFrame Output cross-tabulation DataFrame

compute_correlation_feature_target(**kwargs)¶

Compute and plot the correlation between the selected features for 2 specified conditions. These conditions must be specified by providing a label_keys parameter. Feature selections parameters can be used to select features - see get_data() -

Parameters:	kwargs : Optional (except for label_keys) Can be feature_pos, feature_type, feature_channame, label_keys, time_points. label_keys must be set. See get_data()

compute_correlation_hits_reaction_times(transform=[], method='pearson', scaling='', feature_range=(0, 1), ax_list=[], **kwargs)¶

Compute and plot the correlation (Pearson or Spearman) between selected features and reaction times (if defined).

Parameters:

transform : lambda Transform applied to the selected features. Use lambdas (e.g. : lambda x: np.exp(x)) method : str (default ‘pearson’) Correlation method to use. Can be 'pearson' or 'spearman' scaling : str | None (default: none) Scaling method. Can be : ‘standardization’ : compute the z-score ‘normalization’ : normalization betwenn 0 and 1 (default) or set by feature_range ‘robust’ : robust z-score feature_range : tuple | array (default: (0, 1)) Feature range when scaling is set to normalization ax_list : list | None (default: none) Axis list where to plot the results kwargs : Optional Feature selection parameters. Can be feature_pos, feature_type, feature_channame, label_keys, time_points. If label_keys is not specified, will be set to 1 (hits). See get_data().

Returns:

correlation : array Correlation array between the feature and the reaction times feature_pos : array Position of the selected features

compute_feature_importance(label_keys, n_decision_trees=250)¶

Compute feature importance using forest of decitions trees. See sklearn.ensemble.ExtraTreesClassifier()

Parameters:	label_keys : array Labels to use for the classification. Should contain at least 2 conditions. n_decision_trees : int (default: 250) Number of decision trees used in the classifier.

extract_feature(feature_type=[])¶

Compute features from the original data data_ori and add them to the feature array data

Parameters:	feature_type : str | array Feature type to compute. To choose in ['dwt', 'phase_hilbert', 'stft_pxx', 'cwt_coefs', 'cwt_phase']

feature_name2pos(feature_sel_names)¶

Return the feature names from the feature positions

Parameters:	feature_sel_names : str | array Feature names
Returns:	feature_pos : int | array Corresponding feature positions

feature_pos2name(feature_pos)¶

Return the feature position from the feature names

Parameters:	feature_pos : int | array Feature position
Returns:	feature_name : str | array Corresponding feature names

get_data(**kwargs)¶

Select the data corresponding to selected feature and/or labels and/or time points. The selection parameter can be the feature position, channel’s name, type and/or the condition (label_key) and/or the time points.

Parameters:	feature_pos : array, optional position of the features to select feature_type : array, optional type of the features to select feature_channame : array, optional Channel name of the feature to select label_keys : int | array, optional Label keys, if not specified, select all labels condition time_points : array, optional Time points to select
Returns:	data_feature : array (size n_features_sel, n_pnts_sel, n_trials_sel) Selected features array. The returned array is always 3D, even if the a single a feature or time point is selected. feature_names : array Names of the selected features label_vect : array Labels of the selected trials n_selected_trials : int Number of selected trials

get_feature_pos(feature_pos=[], feature_type=[], feature_channame=[], join=0)¶

Get the feature position from feature type or/and feature channel name

Parameters:	feature_pos : int | array | None (default: none) If provided, this method do nothing feature_type : int | array | None (default: none) Feature type selection feature_channame : int | array | None (default: none) Feature channel name selection join : bool (default: False) If True, selection the union [OR] between the 2 selection criteria (type and channame), otherwise select the intersection [AND]
Returns:	feature_pos : int | array Feature position

get_label_key_from_value(dict_value)¶

Return the label key from the value of the dictionnary attribute label_dict

Parameters:	dict_value : str Dictionnary value
Returns:	dict_key : int Corresponding dictionnary key

interactive_feature_rt_correlation(transform=[], method='pearson', scaling=[], feature_range=(0, 1), **kwargs)¶

Interactive plot of the correlation between feature and reaction times (for hits trials)

Parameters:

transform : lambda Transform applied to the selected features. Use lambdas (e.g. : lambda x: np.exp(x)) method : str Correlation method to use. Can be 'pearson' or 'spearman' scaling : str | None (default: none) Scaling method. Can be : ‘standardization’ : compute the z-score ‘normalization’ : normalization betwenn 0 and 1 (default) or set by feature_range ‘robust’ : robust z-score feature_range : tuple | array (default: (0, 1)) Feature range when scaling is set to normalization kwargs : Optional Feature selection parameters. Can be feature_pos, feature_type, feature_channame, label_keys, time_points. If label_keys is not specified, will be set to 1 (hits). See get_data().

plot_feature_distribution(ax=[], **kwargs)¶

Plot the distribution of features at a certain time point for selected labels. The time_points parameter should be specified.

Parameters:	kwargs : Optional Data selection parameters. Can be feature_pos, feature_type, feature_channame, label_keys, time_points. The time_points parameter must be specified. See get_data()

plot_feature_erp(plot_traces=0, ax=[], **kwargs)¶

Plot the feature evolution across time. Selection parameters can be passed.

Parameters:	plot_traces : Bool If True plot all the trials, otherwise plot the mean and tthe 95% CI kwargs : Optional Data selection parameters. Can be feature_pos, feature_type, feature_channame, label_keys, time_points. See get_data()

plot_feature_erpimage(ax=[], cax=[], **kwargs)¶

Plot the erp-image of the selected features

kwargs : Optional

Data selection parameters. Can be feature_pos, feature_type, feature_channame, label_keys, time_points. See get_data()

plot_feature_hits_reaction_time(scaling=[], feature_range=(0, 1), transform=[], ax_list=[], **kwargs)¶

Plot the reaction time in function of the feature. Used to visualize any correlation between the feature and the reaction time (if it is defined). The ‘time_points’ parameter must be set and contain only 1 value. Only one feature must be selected.

Parameters:

scaling : str | None (default: none) Scaling method. Can be : ‘standardization’ : compute the z-score ‘normalization’ : normalization betwenn 0 and 1 (default) or set by feature_range ‘robust’ : robust z-score feature_range : tuple | array (default: (0, 1)) Feature range when scaling is set to normalization transform : lambda | none (default: none) Function to transform the feature. Use lambdas, e.g. : lambda x: x**2. ax_list : list | None (default: none) List of axes to plot on kwargs : Optional (except time_points) Data selection parameters. Can be feature_pos, feature_type, feature_channame, label_keys, time_points. The time_points parameter must be specified and only 1 feature should be selected. The label_keys is automatically set to the ‘Hits’ key. See get_data()

sample2time(sample)¶

Return the time in seconds from the sample index

Parameters:	sample : int Sample index
Returns:	t_sec : float Corresponding time in seconds

save(dir_path='.', filename=[], filename_desc=[])¶

Save the time features instance to a pickle file using the pickle module.

Parameters:	dir_path : str Path of the directory where it will be saved filename : str Filename

sort_features(sorting_variable='feature_type')¶

Sort the features according to sorting_variable

Parameters:	sorting_variable : str Sorting variable. Can be ‘feature_type’ or ‘feature_channame’

sort_trials(sorting_variable='label', direction='ascend')¶

Sort the data trial order given the sorting variable. Sort data_ori and data given the new trial order

Parameters:	sorting_variable : str Sorting variable, can be either ‘label’ or ‘reaction times’ direction : str Possible values are ‘ascend’ or ‘descend’

time2sample(t_sec)¶

Return the sample index from the time in seconds

Parameters:	t_sec : float Time in seconds
Returns:	sample : int Correponding sample index

timefeatures.correlation_1d(vect_x, vect_y, method='pearson', transform_x=[], transform_y=[])¶

Correlation measure between 1D arrays

Parameters:	vect_x : array First array vect_y : array Second array method : str (default: ‘pearson’) Correlation methods - Can be 'pearson' or 'spearman' transform_x : lambda Transformation for first array. Use lambda, e.g. : lambda x: x**2 transform_y : lambda Transformation for second array. Use lambda, e.g. : lambda x: x**2
Returns:	corr_value : float Correlation value p_value : float Associated p-value

timefeatures.load_time_features(filepath)¶

Load a time feature instance previously saved using the pickle module

Parameters:	filepath : str Path of the pickle file
Returns:	time_features : TimeFeatures The TimeFeatures instance

timefeatures.scale_data(data, scaling, feature_range=(0, 1))¶

Scale the data using scikit-learn scalers

Parameters:	data : array data to scale scaling : str | None (default: none) Scaling method. Can be : ‘standardization’ : compute the z-score ‘normalization’ : normalization betwenn 0 and 1 (default) or set by feature_range ‘robust’ : robust z-score feature_range : tuple | array (default: (0, 1)) Feature range when scaling is set to normalization
Returns:	scaled_data : array Scaled data