osl_ephys.source_recon.sign_flipping

Functions for fixing the dipole sign ambiguity of beamformed data.

Functions

_get_parc_chans(raw)	Get parcel channels names in an mne.Raw or mne.Epochs object.
find_flips(cov, template_cov, n_embeddings, n_init, ...)	Find channels to flip.
load_covariances(parc_files[, n_embeddings, ...])	Loads data and returns its covariance matrix.
find_template_subject(covs[, diag_offset])	Find a good template subject to use to align dipoles.
covariance_matrix_correlation(M1, M2[, diag_offset, mode])	Calculates the Pearson correlation between covariance matrices.
randomly_flip(flips, max_flips)	Randomly flips some channels.
apply_flips_to_covariance(cov, flips[, n_embeddings])	Applies flips to a covariance matrix.
apply_flips(outdir, subject, flips[, epoched, ...])	Saves the sign flipped data.
time_embed(x, n_embeddings)	Performs time-delay embedding.
std_data(x)	Standardize (z-transform) the data.

Module Contents

osl_ephys.source_recon.sign_flipping._get_parc_chans(raw)

Get parcel channels names in an mne.Raw or mne.Epochs object.

Parameters:

raw (mne.Raw or mne.Epochs) – Raw or Epochs object.

Returns:

parc_chans – Parcel channel names. If no channels called ‘parcel_X’ are found in the raw object then we return ‘misc’.

Return type:

list of str or str

osl_ephys.source_recon.sign_flipping.find_flips(cov, template_cov, n_embeddings, n_init, n_iter, max_flips, use_tqdm=True)

Find channels to flip.

We search for the channels to flip by randomly flipping them and saving the flips that maximise the correlation of the covariance matrices between subjects.

Parameters:

• cov (numpy.ndarray) – Covariance matrix we would like to sign flip.

• template_cov (numpy.ndarray) – Template covariance matrix.

• n_embeddings (int) – Number of time-delay embeddings.

• n_init (int) – Number of initializations.

• n_iter (int) – Number of sign flipping iterations per subject to perform.

• max_flips (int) – Maximum number of channels to flip in an iteration.

• use_tqdm (bool) – Should we display a tqdm progress bar?

Returns:

• best_flips (numpy.ndarray) – A (n_channels,) array of 1s and -1s indicating whether or not to flip a channels.

• metrics (numpy.ndarray) – Evaluation metric (correlation between covariance matrices) as a function of iterations. Shape is (n_iter + 1,).

osl_ephys.source_recon.sign_flipping.load_covariances(parc_files, n_embeddings=1, standardize=True, loader=None, use_tqdm=True)

Loads data and returns its covariance matrix.

Parameters:

• parc_files (list of str) – List of paths to parcellated data files to load.

• n_embeddings (int) – Number of time-delay embeddings to perform.

• standardize (bool) – Should we standardize the data?

• loader (function) – Custom function to load parcellated data files.

• use_tqdm (bool) – Should we display a tqdm progress bar?

Returns:

covs – Covariance matrices.

Return type:

numpy.ndarray

osl_ephys.source_recon.sign_flipping.find_template_subject(covs, diag_offset=0)

Find a good template subject to use to align dipoles.

We select the median subject after calculating the similarity between the covariances of each subject.

Parameters:

• covs (numpy.ndarray) – Covariance of each subject. Shape much be (n_subjects, n_channels, n_channels).

• diag_offset (int) – Offset to apply when getting the upper triangle of the covariance matrix before calculating the correlation between covariances.

Returns:

index – Index for the template subject.

Return type:

int

osl_ephys.source_recon.sign_flipping.covariance_matrix_correlation(M1, M2, diag_offset=0, mode=None)

Calculates the Pearson correlation between covariance matrices.

Parameters:

• M1 (numpy.ndarray) – First covariance matrix.

• M2 (numpy.ndarray) – Second covariance matrix.

• diag_offset (int) – To calculate the distance we take the upper triangle. This argument allows us to specify an offet from the diagonal so we can choose not to take elements near the diagonal.

• mode (str) – Either ‘abs’, ‘sign’ or None.

osl_ephys.source_recon.sign_flipping.randomly_flip(flips, max_flips)

Randomly flips some channels.

Parameters:

• flips (numpy.ndarray) – Vector of 1s and -1s indicating which channels to flip.

• max_flips (int) – Maximum number of channels to change in this function.

Returns:

new_flips – Vector of 1s and -1s indicating which channels to flip.

Return type:

numpy.ndarray

osl_ephys.source_recon.sign_flipping.apply_flips_to_covariance(cov, flips, n_embeddings=1)

Applies flips to a covariance matrix.

Parameters:

• cov (numpy.ndarray) – Covariance matrix to apply flips to. Shape must be (n_channels*n_embeddings, n_channels*n_embeddings).

• flips (numpy.ndarray) – Vector of 1s and -1s indicating whether or not to flip a channels. Shape must be (n_channels,).

• n_embeddings (int) – Number of embeddings used when calculating the covariance.

Returns:

cov – Flipped covariance matrix.

Return type:

numpy.ndarray

osl_ephys.source_recon.sign_flipping.apply_flips(outdir, subject, flips, epoched=False, source_method='lcmv')

Saves the sign flipped data.

Parameters:

• outdir (str) – Path to source reconstruction directory.

• subject (str) – Subject name/id.

• flips (numpy.ndarray) – Flips to apply.

• epoched (bool) – Are we performing sign flipping on parc-raw.fif (epoched=False) or parc-epo.fif files (epoched=True)?

• source_method (str, optional) – Which parcellation file should we apply flips to.

osl_ephys.source_recon.sign_flipping.time_embed(x, n_embeddings)

Performs time-delay embedding.

Parameters:

• x (numpy.ndarray) – Time series data. Shape must be (n_samples, n_channels).

• n_embeddings (int) – Number of samples in which to shift the data. Must be an odd number.

Returns:

Time embedded data. Shape is (n_samples, n_channels * n_embeddings).

Return type:

sliding_window_view

osl_ephys.source_recon.sign_flipping.std_data(x)

Standardize (z-transform) the data.

Parameters:

x (numpy.ndarray) – Data. Shape must be (n_samples, n_channels).

Returns:

std_x – Standardized time series.

Return type:

numpy.ndarray