Brain States package¶
sekupy.analysis.states.base module¶
- class sekupy.analysis.states.base.Clustering(estimator=KMeans(), name='state', **kwargs)[source]¶
- fit(ds, prepro=<sekupy.analysis.states.subsamplers.VarianceSubsampler object>, **kwargs)[source]¶
This method fits the dataset using the clustering algorithm
- Parameters:
- scores¶
The results of the state identification ‘labels’: array
array with the assigned cluster for the subsampled set of samples
- ‘states’: array
the centroids of the clustered set using the subsampled dataset.
- ‘dynamics’: array
the predicted labels of the full dataset using the fitted algorithm
- ‘X’: array
the subsampled dataset
- ‘targets’: array
the targets of the dataset (if applicable)
- ‘state_similarity’: array
the similarity of the dataset with the most similar centroid
- Type:
- get_centroids(X, labels)[source]¶
Returns the centroid of a clustering experiment
- Parameters:
X (n_samples x n_features array) – The full dataset used for clustering
labels (n_samples array) – The clustering labels for each sample.
- Returns:
centroids – The centroids of the clusters.
- Return type:
n_cluster x n_features shaped array
- get_state_duration(dynamics=None)[source]¶
Extracts the average of state duration given the fitted timecourse for each subject. This is the output of fit_centroids function
- Parameters:
dynamics (n_timepoints array) – The state dynamics output from _predict function.
- Returns:
state_duration – The duration of each state for each subject/session. first element is the state number, second the duration in points
- Return type:
vector n_transition x 2 matrix,
- get_state_frequencies(dynamics=None, sfreq=128, method=<function psd_array_welch>, **kwargs)[source]¶
Returns the spectrum of the state occurence for each subject.
- Parameters:
state_dynamics (n_states x n_timepoints array) – The state dynamics output from fit_states function.
method (function from mne.time_frequency package)
X (n_timepoinst x n_features array) – This is the array on which we need to build the state_dynamics whether not provided nor calculated.
- Returns:
results – first element is the array of frequencies, second element is the array n_states x frequencies of the spectrum.
- Return type:
- get_transition_matrix(dynamics=None)[source]¶
Extracts the probability transition matrix given the fitted timecourse for each subject. This is the output of fit_centroids function
- Parameters:
group_fitted_timecourse (n_subjects x n_timepoints array) – The state dynamics output from fit_centroids function.
- Returns:
transition_p –
- The number of transition from x state to y state, stored
in matrix[x,y]. The syntax is matrix[starting_state, ending_state].
- Return type:
n_states x n_states matrix,
- save(path=None, **kwargs)[source]¶
Basic function for saving information about the analysis. Basically it should be overriden in subclasses.
This implementation creates the folder in which results are stored, following BIDS specification.
- Parameters:
- Returns:
path – The directory created or the path passed as parameter.
- Return type:
GSBS algorithm¶
- class sekupy.analysis.states.gsbs.GSBS(tr_tuning=1, blocksize=50, dmin=1, **kwargs)[source]¶
This class uses a greedy search algorithm to segment timeseries into neural state with stable activity patterns. The algorithm identifies the timepoint of state transition and the best number of states using t-statistics
You can find more information about the method here: Geerligs L., van Gerven M., Güçlü U (2020) Detecting neural state transitions underlying event segmentation biorXiv. https://doi.org/10.1101/2020.04.30.069989
- Parameters:
kmax (int) – Maximum number of neural states to be estimated. (a reasonable choice is t/2) (maybe should be included in fit)
tr_tuning (int, optional) – Number of timepoints to be included in the finetuning, it optimizes the transition time around a boundary. If = 0 no fine tuning is performed, if < 0 all timepoints are included, by default 1.
blocksize (int, optional) – Minimal number that constitues a block, this is used to speed up the computation when the number of tp is large, it finds local optimun within a block of blocksize, by default 50.
dmin (int, optional) – Number of timepoints around the diagonal that are not taken into account in the computation of the t-distance metric, by default 1.