bidsmreye package

Submodules

bidsmreye.bids_utils module

bidsmreye.bids_utils.check_layout(cfg: Config, layout: BIDSLayout, for_file: str = 'bold') → None

Check layout.

Parameters:

• cfg (Config) – Configuration object

• layout (BIDSLayout) – BIDSLayout of the dataset.

Raises:

• RuntimeError – _description_

• RuntimeError – _description_

bidsmreye.bids_utils.create_bidsname(layout: BIDSLayout, filename: dict[str, str] | str | Path, filetype: str, extra_entities: dict[str, str] | None = None) → Path

Return a BIDS valid filename for layout and a filename or a dict of BIDS entities.

Parameters:

• layout (BIDSLayout) – BIDSLayout of the dataset.

• filename (Union[dict, str, Path]) – Dictionary of BIDS entities or a Path to a file.

• filetype (str) – One of the file type available in the BIDS name config.

Raises:

TypeError –

Returns:

Return type:

Path

bidsmreye.bids_utils.create_sidecar(layout: BIDSLayout, filename: str, SamplingFrequency: float | None = None, source: str | None = None) → None

Create sidecar for the eye motion timeseries.

bidsmreye.bids_utils.get_dataset_layout(dataset_path: str | Path, config: str | list[str] | dict[str, str] | None = None, use_database: bool = False, reset_database: bool = False) → BIDSLayout

Return a BIDSLayout object for the dataset at the given path.

Parameters:

• dataset_path (Union[str, Path]) – Path to the dataset.

• config (Optional[dict], optional) – Pybids config to use. Defaults to None.

• use_database (bool, optional) – Defaults to False

Returns:

_description_

Return type:

BIDSLayout

bidsmreye.bids_utils.init_dataset(cfg: Config, qc_only: bool = False) → BIDSLayout

bidsmreye.bids_utils.init_derivatives_layout(cfg: Config) → BIDSLayout

Initialize a derivatives dataset and returns its layout.

Parameters:

output_dir (Path)

Returns:

Return type:

BIDSLayout

bidsmreye.bids_utils.list_subjects(cfg: Config, layout: BIDSLayout) → list[str]

List subject in a BIDS dataset for a given Config.

Parameters:

• cfg (Config) – Configuration object

• layout (BIDSLayout) – BIDSLayout of the dataset.

Raises:

RuntimeError – _description_

Returns:

_description_

Return type:

list

bidsmreye.bids_utils.return_desc_entity(model_filename: Path)

bidsmreye.bids_utils.sanitize_filename(filename: Path)

Turn filename stem into its alphanumeric CamelCase equivalent.

To use as a BIDS entity label.

bidsmreye.bids_utils.save_sampling_frequency_to_json(layout_out: BIDSLayout, img: BIDSFile, source: str) → None

bidsmreye.bids_utils.set_dataset_description(layout: BIDSLayout, is_derivative: bool = True) → BIDSLayout

Add dataset description to a layout.

Parameters:

• layout (BIDSLayout) – _description_

• is_derivative (bool, optional) – Defaults to True

Returns:

Updated BIDSLayout of the dataset

Return type:

BIDSLayout

bidsmreye.bids_utils.write_dataset_description(layout: BIDSLayout) → None

Add a dataset_description.json to a BIDS dataset.

Parameters:

layout (BIDSLayout) – BIDSLayout of the dataset to update.

bidsmreye.bidsmreye module

Main script.

bidsmreye.bidsmreye.bidsmreye(bids_dir: str, output_dir: str, analysis_level: str, action: str, participant_label: list[str] | None = None, space: list[str] | None = None, task: list[str] | None = None, run: list[str] | None = None, debug: bool | None = None, model_weights_file: str | None = None, reset_database: bool | None = None, bids_filter_file: str | None = None, linear_coreg: bool = False, log_level_name: str | None = None, force: bool = False) → None

bidsmreye.bidsmreye.dispatch(analysis_level: str, action: str, cfg: Config) → None

bidsmreye.configuration module

class bidsmreye.configuration.Config(input_dir=None, output_dir=None, *, subjects: Any | None = None, space: Any | None = None, task: Any | None = None, run: Any | None = None, model_weights_file: str | Path | None = None, bids_filter: Any = None, debug: str | bool | None = None, reset_database: bool = False, linear_coreg: bool = False, force: bool = False)

Bases: object

Set up config and check that all required fields are set.

Raises:

• ValueError – _description_

• RuntimeError – _description_

Returns:

_description_

Return type:

_type_

bids_filter: Any

check_argument(attribute: str, layout_in: BIDSLayout) → Config

Check an attribute value compared to the input dataset content.

Parameters:

• attribute (str)

• layout_in (BIDSLayout)

Raises:

RuntimeError –

Returns:

Return type:

Config

debug: str | bool | None

force: bool

has_GPU: bool = False

input_dir

linear_coreg: bool

listify(attribute: str) → Config

Convert attribute to list if not already.

model_weights_file: str | Path | None

output_dir: Path

reset_database: bool

run: Any | None

space: Any | None

subjects: Any | None

task: Any | None

bidsmreye.configuration.config_to_dict(cfg: Config) → dict[str, Any]

Convert a config to a dictionary.

Parameters:

cfg (_type_)

Returns:

Return type:

_type_

bidsmreye.configuration.get_bids_filter_config(config_file: Path | None = None) → dict[str, Any]

Load the bids filter file config.

Parameters:

config_file (Path, optional) – Config to load. Defaults to None.

Returns:

_description_

Return type:

dict

bidsmreye.configuration.get_bidsname_config(config_file: Path | None = None) → dict[str, str]

Load configuration for naming output BIDS files.

Parameters:

config_file (Path, optional) – Defaults to None

Returns:

Config as a dictionary.

Return type:

dict

See the Path construction demo in the pybids tutorial.

https://github.com/bids-standard/pybids/blob/master/examples/pybids_tutorial.ipynb

bidsmreye.configuration.get_config(config_file: Path | None = None, default: str = '') → dict[str, str]

Load a config stored in a JSON.

Parameters:

• config_file (Path, optional) – File to load. Defaults to None. Will look into the config directory if None.

• default (str, optional) – Default file to load. Defaults to “”

Raises:

FileNotFoundError – _description_

Returns:

Config as a dictionary.

Return type:

dict

bidsmreye.configuration.get_pybids_config(config_file: Path | None = None) → dict[str, str]

Load pybids configuration.

Parameters:

config_file (Path, optional) – Defaults to None

Returns:

_description_

Return type:

dict

Pybids configs are stored in the layout module.

https://github.com/bids-standard/pybids/tree/master/bids/layout/config

bidsmreye.defaults module

Store defaults.

bidsmreye.defaults.available_models() → list[str]

Return a list of available models.

bidsmreye.defaults.default_log_level() → str

Return default log level.

bidsmreye.defaults.default_model() → str

Return default model.

bidsmreye.defaults.log_levels() → list[str]

Return a list of log levels.

bidsmreye.download module

Download the models from OSF.

bidsmreye.download.download(model: str | Path | None = None, output_dir: Path | str | None = None) → Path | None

Download the models from OSF.

Parameters:

• model (str, optional) – Model to download. defaults to None

• output_dir (Path, optional) – Path where to save the model. Defaults to None.

Returns:

Path to the downloaded model.

Return type:

Path

bidsmreye.generalize module

Compute eyetracking movement from preprocessed extracted data.

bidsmreye.generalize.convert_confounds(layout_out: BIDSLayout, file: str | Path, extra_entities: dict[str, str] | None = None) → Path

Convert numpy output to TSV.

Parameters:

• layout_out (BIDSLayout) – pybids layout to of the dataset to act on.

• file (Union[str, Path]) – File to generate the confounds for.

Returns:

Name of the file generated.

Return type:

Path

This function should preferably work on a single file but should still be able to unpack the results from a numpy file with results from multiple files.

bidsmreye.generalize.create_and_save_figure(layout_out: BIDSLayout, file: str, evaluation: Any, scores: Any) → None

Generate a figure for the eye motion timeseries.

Unused but keeping to help with plotting of datasets with with training data

Parameters:

• layout_out (BIDSLayout) – Output dataset layout.

• file (str)

• evaluation (_type_) – see deepmreye.train.evaluate_model

• scores (_type_) – see deepmreye.train.evaluate_model

bidsmreye.generalize.create_confounds_tsv(layout_out: BIDSLayout, file: str, subject_label: str, extra_entities: dict[str, str] | None = None) → None

Generate a TSV file for the eye motion timeseries.

Parameters:

• layout_out (BIDSLayout)

• file (str)

• subject_label (str)

bidsmreye.generalize.generalize(cfg: Config) → None

Apply model weights to new data.

Parameters:

cfg (Config) – Configuration object

bidsmreye.generalize.process_subject(cfg: Config, layout_out: BIDSLayout, subject_label: str) → None

Run generalize for one subject.

Parameters:

• cfg (Config) – Configuration object

• layout_out (BIDSLayout)

• subject_label (str)

bidsmreye.logging module

bidsmreye.methods module

Write method section.

bidsmreye.methods.methods(output_dir: str | Path | None = None, model: str | None = None, qc_only: bool = False) → Path

Write method section.

Parameters:

• output_dir (Union[str, Path], optional) – Defaults to Path(“.”)

• model (str, optional) – Defaults to None.

Returns:

Output file name.

Return type:

Path

bidsmreye.prepare_data module

Run coregistration and extract data from eye masks in MNI space.

bidsmreye.prepare_data.combine_data_with_empty_labels(layout_out: BIDSLayout, img: Path, i: int = 1) → Path

Combine data with empty labels.

Parameters:

• layout_out (_type_) – _description_

• subject_label (_type_) – _description_

• img (_type_) – _description_

• i (int, optional) – _description_, defaults to 1

bidsmreye.prepare_data.coregister_and_extract_data(img: str, linear_coreg: bool = False) → None

Coregister image to eye template and extract data from eye mask for one image.

Parameters:

img (str) – Image to coregister and extract data from

bidsmreye.prepare_data.prepapre_image(cfg: Config, layout_in: BIDSLayout, layout_out: BIDSLayout, img: BIDSFile) → None

Preprocess a single functional image.

bidsmreye.prepare_data.prepare_data(cfg: Config) → None

Run coregistration and extract data for all subjects.

Parameters:

cfg (Config) – Configuration object

bidsmreye.prepare_data.process_subject(cfg: Config, layout_in: BIDSLayout, layout_out: BIDSLayout, subject_label: str) → None

Run coregistration and extract data for one subject.

Parameters:

• cfg (Config) – Configuration object.

• layout_in (BIDSLayout) – Layout input dataset.

• layout_out (BIDSLayout) – Layout output dataset.

• subject_label (str) – Can be a regular expression.

bidsmreye.quality_control module

Tools to compute and plot quality controls at the file or group level.

bidsmreye.quality_control.add_qc_to_sidecar(confounds: DataFrame, sidecar_name: Path) → None

Add quality control metrics to the sidecar json file.

Parameters:

• layout (BIDSLayout) – Layout of the BIDS dataset to which the confounds tsv file belongs to

• confounds_tsv (str | Path) – path the the confounds tsv file

Returns:

Path to the sidecar json file

Return type:

Path

bidsmreye.quality_control.compute_displacement(x: Series, y: Series) → Series

bidsmreye.quality_control.compute_displacement_and_outliers(confounds: DataFrame) → DataFrame

bidsmreye.quality_control.compute_robust_outliers(time_series: Series, outlier_type: str | None = None) → list[int] | type[NotImplementedError]

Compute robust ouliers of a time series using S-outliers or Carling’s k.

Parameters:

• series (pd.Series) – Series to compute the outliers on.

• outlier_type (str) – Default to ‘S-outliers’.

Returns:

Series of booleans indicating the outliers.

Return type:

pd.Series

Adapted from spmup by Cyril Pernet.

S-outliers is the default options, it is independent of a measure of centrality as this is based on the median of pair-wise distances. This is a very sensitive measures, i.e. it has a relatively high false positive rates. As such it is a great detection tools.

The adjusted Carling’s box-plot rule can also be used, and derived from the median of the data: outliers are outside the bound of median +/- k*IQR, with k = (17.63*n-23.64)/(7.74*n-3.71). This is a more specific measure, as such it is ‘better’ than S-outliers to regress-out, removing bad data points (assuming we don’t want to ‘remove’ too many).

References:

• Rousseeuw and Croux [1993]

• Carling [2000]

• Hoaglin et al. [1986]

bidsmreye.quality_control.get_sampling_frequency(layout: BIDSLayout, file: str | Path, extra_entities: dict[str, str] | None = None) → float | None

Get the sampling frequency from the sidecar JSON file.

bidsmreye.quality_control.perform_quality_control(cfg: Config, layout_in: BIDSLayout, confounds_tsv: str | Path, layout_out: BIDSLayout | None = None) → None

Perform quality control on the confounds.

Compute displacement and outlier for a given eyetrack.tsv file and create a visualization for it that is saved as an html file.

Parameters:

• layout (BIDSLayout) – pybids layout to of the dataset to act on.

• confounds_tsv (str | Path) – Path to the confounds TSV file.

bidsmreye.quality_control.qc_subject(cfg: Config, layout_in: BIDSLayout, subject_label: str, layout_out: BIDSLayout | None = None) → None

Run quality control for one subject.

bidsmreye.quality_control.quality_control_input(cfg: Config) → None

Run quality control on the input dataset.

bidsmreye.quality_control.quality_control_output(cfg: Config) → None

Run quality control on the output dataset.

bidsmreye.utils module

bidsmreye.utils.add_timestamps_to_dataframe(df: DataFrame, sampling_frequency: float)

bidsmreye.utils.check_if_file_found(bf: list[BIDSFile], this_filter: dict[str, Any], layout: BIDSLayout) → None

bidsmreye.utils.copy_license(output_dir: Path) → Path

Copy CCO license to output directory.

Parameters:

output_dir (Path)

bidsmreye.utils.create_dir_for_file(file: Path) → None

Create the path to a file if it does not exist.

Parameters:

file (Path)

bidsmreye.utils.create_dir_if_absent(output_path: str | Path) → None

Create a path if it does not exist.

Parameters:

output_path (Union[str, Path])

bidsmreye.utils.get_deepmreye_filename(layout: BIDSLayout, img: str, filetype: str | None = None) → Path

Get deepmreye filename.

Parameters:

• layout (BIDSLayout) – BIDSLayout of the dataset.

• img (str) – _description_

• filetype (str, optional) – Any of the following: None, “mask”, “report”D defaults to None

Raises:

ValueError – _description_

Returns:

_description_

Return type:

Path

bidsmreye.utils.move_file(input: Path, output: Path) → None

Move or rename a file and create target directory if it does not exist.

Should work even the source and target names are on different file systems.

:param input:File to move. :type input: Path

Parameters:

• output (Path)

• root (Path) – Optional. If specified, the printed path will be relative to this path.

bidsmreye.utils.progress_bar(text: str, color: str = 'green') → Progress

bidsmreye.utils.return_deepmreye_output_filename(filename: str, filetype: str | None = None) → str

Return deepmreye output filename.

Parameters:

• filename (str)

• filetype (str, optional) – Any of the following: None, “mask”, “report”. defaults to None

Returns:

_description_

Return type:

str

bidsmreye.utils.return_regex(value: str | list[str] | None) → str | None

Return the regular expression for a string or a list of strings.

Parameters:

value (Union[str, Optional[list]])

Returns:

Return type:

Optional[str]

bidsmreye.utils.set_this_filter(cfg: Config, subject_label: str | list[str], filter_type: str) → dict[str, Any]

bidsmreye.visualize module

bidsmreye.visualize.add_outliers_to_heatmap(fig: Any, X: Series, Y: Series, outliers: Series, outlier_color: str) → None

bidsmreye.visualize.collect_group_qc_data(cfg: Config) → DataFrame | None

Collect QC metrics data from all subjects json in a BIDS dataset.

Parameters:

input_dir (str | Path)

Returns:

Return type:

pd.DataFrame

bidsmreye.visualize.group_report(cfg: Config) → None

Create a group level report figure for eyetracking data.

Returns:

Figure object

Return type:

Any

bidsmreye.visualize.plot_group_boxplot(fig: Any, qc_data: DataFrame, row: int, col: int, column_names: list[str], trace_names: list[str], ticktext: list[str], yaxes_title: str) → None

bidsmreye.visualize.plot_heat_map(fig: Any, eye_gaze_data: DataFrame) → None

bidsmreye.visualize.plot_time_series(fig: Any, eye_gaze_data: DataFrame, title_text: str, row: int, col: int, plotting_range: list[float] | None = None, line_color: str = 'rgb(0, 150, 175)') → None

bidsmreye.visualize.time_range(time_stamps: Series) → list[float]

bidsmreye.visualize.value_range(X: Series) → list[float]

bidsmreye.visualize.visualize_eye_gaze_data(eye_gaze_data: DataFrame) → Any

Module contents

Bidsmreye package.