osl_ephys.utils#

Submodules#

Attributes#

`osl_logger`
`fname`
`coreg_filenames`
`__doc__`

Classes#

`Study`	Class for simple file finding and looping.
`SPMMEEG`

Functions#

`process_file_inputs`(inputs)	Process inputs for several cases
`sanitise_filepath`(fname)	Remove leading/trailing whitespace, tab, newline and carriage return
`_load_unicode_inputs`(fname)
`find_run_id`(infile[, preload])
`validate_outdir`(outdir)	Checks if an output directory exists and if not creates it.
`get_rawdir`(files)	Gets the raw data directory from filename(s).
`add_subdir`(file, outdir[, run_id])	Add sub-directory.
`osl_print`(s[, logfile])
`dask_parallel_bag`(func, iter_args[, func_args, ...])	A maybe more consistent alternative to `dask_parallel`.
`simulate_data`(model[, num_samples, num_realisations, ...])	Simulate data from a linear model.
`simulate_raw_from_template`(sim_samples[, ...])	Simulate raw MEG data from a 306-channel MEGIN template.
`simulate_rest_mvar`(raw, sim_samples[, mvar_pca, ...])	Simulate resting state data from a raw object using a reduced MVAR model.
`convert_notts`(notts_opm_mat_file, smri_file, tsv_file, ...)	Convert Nottingham OPM data from matlab file to fif file.
`correct_mri`(smri_file, smri_fixed_file)	Correct the sform in the structural MRI file.
`soft_import`(package)	Try to import a package raising friendly error if not present.
`run_package_tests`()	Run OSL tests from within python
`check_version`(test_statement[, mode])	Check whether the version of a package meets a specified condition.

Package Contents#

class osl_ephys.utils.Study(studydir)[source]#

Class for simple file finding and looping.

Parameters:: studydir (str) – The study directory with wildcards.

studydir#

The study directory with wildcards.

Type:: str

fieldnames#

The wildcards in the study directory, i.e., the field names in between {braces}.

Type:: list

globdir#

The study directory with wildcards replaced with *.

Type:: str

match_files#

The files that match the globdir.

Type:: list

match_values#

The values of the field names (i.e., wildcards) for each file.

Type:: list

fields#

The field names and values for each file.

Type:: dict

Notes

This class is a simple wrapper around glob and parse. It works something like this:

>>> studydir = '/path/to/study/{subject}/{session}/{subject}_{task}.fif'
>>> study = Study(studydir)

Get all files in the study directory:

>>> study.get()

Get all files for a particular subject:

>>> study.get(subject='sub-01')

Get all files for a particular subject and session:

>>> study.get(subject='sub-01', session='ses-01')

The fieldnames that are not specified in get are replaced with wildcards (*).

studydir#

fieldnames#

globdir#

match_files#

match_values = []#

fields#

refresh()[source]#: Refresh the study directory.

get(check_exist=True, **kwargs)[source]#

Get files from the study directory that match the fieldnames.

Parameters:

check_exist (bool) – Whether to check if the files exist.
**kwargs (dict) – The field names and values to match.

Returns:

out – The files that match the field names and values.

Return type:

list

Notes

Example using Study and Study.get():

>>> studydir = '/path/to/study/{subject}/{session}/{subject}_{task}.fif'
>>> study = Study(studydir)

Get all files in the study directory:

>>> study.get()

Get all files for a particular subject:

>>> study.get(subject='sub-01')

Get all files for a particular subject and session:

>>> study.get(subject='sub-01', session='ses-01')

The fieldnames that are not specified in get are replaced with wildcards (*).

osl_ephys.utils.osl_logger = None[source]#

osl_ephys.utils.process_file_inputs(inputs)[source]#

Process inputs for several cases

The argument, inputs, can be… 1) string path to unicode file 2) string path to dir (e.g. if CTF .ds dir) 3) string path to file or regular-expression matching files 4) list of string paths to files 5) list of string paths to dirs (e.g. if CTF .ds dirs) 6) list of tuples with path to file and output name pairs 7) list of MNE objects

osl_ephys.utils.sanitise_filepath(fname)[source]#: Remove leading/trailing whitespace, tab, newline and carriage return characters.

osl_ephys.utils._load_unicode_inputs(fname)[source]#

osl_ephys.utils.find_run_id(infile, preload=True)[source]#

osl_ephys.utils.validate_outdir(outdir)[source]#: Checks if an output directory exists and if not creates it.

osl_ephys.utils.get_rawdir(files)[source]#: Gets the raw data directory from filename(s).

osl_ephys.utils.add_subdir(file, outdir, run_id=None)[source]#: Add sub-directory.

osl_ephys.utils.osl_print(s, logfile=None)[source]#

class osl_ephys.utils.SPMMEEG(filename)[source]#

filename#

_D#

type#

nsamples#

nchannels#

fsample#

time_onset#

channels#

data#

fname#

fullpath#

path#

sensors#

fiducials#

transform#

condlist#

history#

other#

ntrials#

montage#

current_montage#

time#

index#

good_index#

trial_definition = None#

get_data(montage=None)[source]#: Return memorymapped data and optionally apply a montage.

epoch_data(data)[source]#

define_trial(event_type, pre_stim, post_stim)[source]#

mark_artefacts_as_bad()[source]#

_channel_property(property_)[source]#

full_index(channel_type)[source]#

reindex_good_samples()[source]#

reindex_event_samples()[source]#

print_info()[source]#

_find_dat_file()[source]#

property size#

property chantype#

indchantype(channel_type)[source]#

indsample(t)[source]#

indtrial(cond)[source]#

property n_good_samples#

osl_ephys.utils.dask_parallel_bag(func, iter_args, func_args=None, func_kwargs=None)[source]#

A maybe more consistent alternative to dask_parallel.

Parameters:

func (function) – The function to run in parallel.
iter_args (list) – A list of iterables to pass to func.
func_args (list, optional) – A list of positional arguments to pass to func.
func_kwargs (dict, optional) – A dictionary of keyword arguments to pass to func.

Returns:

flags – A list of return values from func.

Return type:

list

References

https://docs.dask.org/en/stable/bag.html

osl_ephys.utils.simulate_data(model, num_samples=1000, num_realisations=1, use_cov=True, noise=None)[source]#

Simulate data from a linear model.

Parameters:

model (sails.AbstractLinearModel) – A linear model object.
num_samples (int) – The number of samples to simulate.
num_realisations (int) – The number of realisations to simulate.
use_cov (bool) – Whether to use the residual covariance matrix.

Returns:

Y – The simulated data.

Return type:

ndarray, shape (num_sources, num_samples, num_realisations)

osl_ephys.utils.simulate_raw_from_template(sim_samples, bad_segments=None, bad_channels=None, flat_channels=None, noise=None)[source]#

Simulate raw MEG data from a 306-channel MEGIN template.

Parameters:

sim_samples (int) – The number of samples to simulate.
bad_segments (list of tuples) – The bad segments to simulate.
bad_channels (list of ints) – The bad channels to simulate.
flat_channels (list of ints) – The flat channels to simulate.

Returns:

sim – The simulated data.

Return type:

mne.io.Raw

osl_ephys.utils.simulate_rest_mvar(raw, sim_samples, mvar_pca=32, mvar_order=12, picks=None, modalities=None, drop_dig=False)[source]#

Simulate resting state data from a raw object using a reduced MVAR model.

Parameters:

raw (mne.io.Raw) – The raw object to simulate from.
sim_samples (int) – The number of samples to simulate.
mvar_pca (int) – The number of PCA components to use.
mvar_order (int) – The MVAR model order.
picks (dict) – The picks to use. See mne.pick_types.
modalities (list of str) – The modalities to use. See mne.pick_types.
drop_dig (bool) – Whether to drop the digitisation points.

Returns:

sim – The simulated data.

Return type:

mne.io.Raw

Notes

Best used on low sample rate data <200Hz. fiff only for now.

osl_ephys.utils.fname = '/Users/andrew/Projects/ntad/raw_data/meeg_pilots/NTAD_Neo_Pilot2_RSO.fif'[source]#

osl_ephys.utils.convert_notts(notts_opm_mat_file, smri_file, tsv_file, fif_file, smri_fixed_file)[source]#

Convert Nottingham OPM data from matlab file to fif file.

Parameters:

notts_opm_mat_file (str) – The matlab file containing the OPM data.
smri_file (str) – The structural MRI file.
tsv_file (str) – The tsv file containing the sensor locations and orientations.
fif_file (str) – The output fif file.
smri_fixed_file (str) – The output structural MRI file with corrected sform.

Notes

The matlab file is assumed to contain a variable called ‘data’ which is a matrix of size nSamples x nChannels. The matlab file is assumed to contain a variable called ‘fs’ which is the sampling frequency. The tsv file is assumed to contain a header row, and the following columns: name, type, bad, x, y, z, qx, qy, qz The x,y,z columns are the sensor locations in metres. The qx,qy,qz columns are the sensor orientations in metres.

osl_ephys.utils.correct_mri(smri_file, smri_fixed_file)[source]#

Correct the sform in the structural MRI file.

Parameters:

smri_file (str) – The structural MRI file.
smri_fixed_file (str) – The output structural MRI file with corrected sform.

Returns:

sform_std – The new sform.

Return type:

ndarray

Notes

The sform is corrected so that it is in standard orientation.

osl_ephys.utils.coreg_filenames[source]#

osl_ephys.utils.soft_import(package)[source]#: Try to import a package raising friendly error if not present.

osl_ephys.utils.run_package_tests()[source]#

Run OSL tests from within python

https://docs.pytest.org/en/7.1.x/how-to/usage.html

Notes

Calling pytest.main() will result in importing your tests and any modules that they import. Due to the caching mechanism of python’s import system, making subsequent calls to pytest.main() from the same process will not reflect changes to those files between the calls. For this reason, making multiple calls to pytest.main() from the same process (in order to re-run tests, for example) is not recommended.

osl_ephys.utils.check_version(test_statement, mode='warn')[source]#

Check whether the version of a package meets a specified condition.

Parameters:

test_statement (str) – Package version comparison string in the standard format expected by python installs. eg ‘osl-ephys<1.0.0’ or ‘osl-ephys==0.6.dev0’
mode ({'warn', 'assert'}) – Flag indicating whether to warn the user or raise an error if the comparison fails

osl_ephys.utils.__doc__[source]#