nih2mne 0.6.2

Major Components

  calc_mnetrans.py - extract the transformation matrix (used under the hood in other processes)
  make_meg_bids.py - perform the whole bids conversion of the CTF folder
  make_bid_fs_swarm.sh - On biowulf create the swarm file for the freesurfer processing
  megcore_prep_mri_bids.py - perform all of the standard MRI processing for datasets
  eyetracking_preprocessing.py - identify eyetracking position from UADC channels
  print_bids_table.py - make a csv file that lists all the contents of your bids tree

Install:

Set up MNE environment (conda can be substituted for mamba below if it doesn't work):
mamba create --override-channels --channel=conda-forge --name=nihmeg mne
mamba activate nihmeg
Install nih_to_mne
pip install git+https://github.com/nih-megcore/nih_to_mne

PyQt6 is the default Qt binding used by the GUI applications. Managed environments that still provide PyQt5 5.15 can select the compatibility path before launching a GUI:

QT_API=pyqt5 bids_qa_gui.py

Developers can regenerate the checked-in Qt Designer forms with PyQt6 by running python tools/regenerate_qt_ui.py from the repository root.

MEG derivative path templates

nih2mne.bids_templates generates and inspects the expected MNE derivative paths for one MEG recording. It does not create directories, filter data, or write files. Filtering parameters become part of the proc- entity and are also exposed as expected JSON metadata:

from mne_bids import BIDSPath
from nih2mne.bids_templates import FilterSpec, MEGDerivativeTemplate

raw_path = BIDSPath(
    root="/data/my-bids",
    subject="01",
    session="1",
    task="rest",
    run="01",
    datatype="meg",
    suffix="meg",
    extension=".fif",
)
filter_spec = FilterSpec(
    l_freq=1,
    h_freq=40,
    notch_freqs=(60, 120),
    resample_sfreq=250,
    method="fir",
    phase="zero",
)
template = MEGDerivativeTemplate(
    raw_path,
    project="ENIGMA_MEG",
    filter_spec=filter_spec,
)
artifacts = template.evaluate()

# ..._task-rest_run-01_proc-filt1to40n60x120r250_epo.fif
print(artifacts["epochs"].path)
print(artifacts["epochs"].status)  # present, missing, or invalid
epochs = artifacts["epochs"].load_file()

# Metadata to place beside the filtered FIF file.
print(artifacts["filtered_raw_json"].expected_metadata)

An optional noise input may be another BIDSPath (including one from a different dataset) or an arbitrary path. Noise derivatives always adopt the primary recording's subject and session while retaining the noise task and run:

template = MEGDerivativeTemplate(
    raw_path,
    project="ENIGMA_MEG",
    filter_spec=filter_spec,
    noise="/data/empty-room/noise.fif",
    noise_entities={"task": "noise", "run": "01"},
)

Project-specific templates can append immutable ArtifactSpec entries in a subclass by extending MEGDerivativeTemplate.ARTIFACT_SPECS. Duplicate keys are rejected when the template is constructed.

Containers

Podman and Singularity/Apptainer images, including host Wayland/X11 and macOS XQuartz GUI support, can be built through the Makefile. See container/README.md for build and launch instructions.

GUI Components For Creating and QA-ing BIDS data

Overview Here: https://megcore.nih.gov/index.php/BIDS_GUIs Include: Trigger Parsing, BIDS creation, and BIDS QA

Adds calc_mnetrans.py, bstags.py, and make_meg_bids.py to the commandline

calc_mnetrans.py

usage: calc_mnetrans.py [-h] [-subjects_dir SUBJECTS_DIR] [-anat_json ANAT_JSON] [-tagfile TAGFILE]
                        [-elec_txt ELEC_TXT] -subject SUBJECT [-afni_mri AFNI_MRI]
                        [-trans_output TRANS_OUTPUT] -dsname DSNAME [-view_coreg]

optional arguments:
  -h, --help            show this help message and exit
  -subjects_dir SUBJECTS_DIR
                        Set SUBJECTS_DIR different from the environment variable. If not set this
                        defaults to os.environ['SUBJECTS_DIR]
  -anat_json ANAT_JSON  Full path to the BIDS anatomy json file with the NAS,RPA,LPA locations
  -tagfile TAGFILE      Tagfile generated by bstags.py
  -elec_txt ELEC_TXT    Electrode text file exported from brainsight
  -subject SUBJECT      The freesurfer subject id. This folder is expected to be in the freesurfer
                        SUBJECTS_DIR
  -afni_mri AFNI_MRI    Provide a BRIK or HEAD file as input. Data must have the tags assigned to
                        the header.
  -trans_output TRANS_OUTPUT
                        The output path for the mne trans.fif file
  -dsname DSNAME        CTF dataset to create the transform
  -view_coreg           Display the coregistration of MEG and head surface

bstags.py

usage: bstags.py file.txt
          Where file.txt is the saved electrode location output from Brainsight.

make_meg_bids.py

usage: 
        Convert MEG dataset to default Bids format using the MEG hash ID or 
        entered subject ID as the bids ID.        
        

WARNING: Must use the -anonymize flag to anonymize otherwise this does NOT anonymize the data!!!
        
       [-h] [-bids_dir BIDS_DIR] -meg_input_dir MEG_INPUT_DIR [-anonymize] [-mri_brik MRI_BRIK]
       [-mri_bsight MRI_BSIGHT] [-mri_bsight_elec MRI_BSIGHT_ELEC] [-bids_session BIDS_SESSION]
       [-subjid SUBJID] [-autocrop_zeros]

options:
  -h, --help            show this help message and exit
  -bids_dir BIDS_DIR    Output bids_dir path
  -meg_input_dir MEG_INPUT_DIR
                        Acquisition directory - typically designated by the acquisition date
  -anonymize            Strip out subject ID information from the MEG data. Currently this does not
                        anonymize the MRI. Requires the CTF tools.
  -bids_session BIDS_SESSION
                        Data acquisition session. This is set to 1 by default. If the same subject had
                        multiple sessions this must be set manually
  -subjid_input SUBJID_INPUT
                        The default subject ID is given by the MEG hash. If more than one subject is
                        present in a folder, this option can be set to select a single subjects
                        dataset.
  -bids_id BIDS_ID      The default subject ID is given by the MEG hash. To override the default
                        subject ID, use this flag. If -anonymize is used, you must set the subjid
  -autocrop_zeros       If files are terminated early, leaving zeros at the end of the file - this
                        will detect and remove the trailing zeros

Afni Coreg:
  -mri_brik MRI_BRIK    Afni coregistered MRI

Brainsight Coreg:
  -mri_bsight MRI_BSIGHT
                        Brainsight mri. This should be a .nii file. The exported electrodes text file
                        must be in the same folder and end in .txt. Otherwise, provide the
                        mri_sight_elec flag
  -mri_bsight_elec MRI_BSIGHT_ELEC
                        Exported electrodes file from brainsight. This has the locations of the
                        fiducials

Additional Options:
  -freesurfer           Perform recon-all pipeline on the T1w. This is required for the mri_prep
                        portions below
  -project PROJECT      Output project name for the mri processing from mri_prep

make_bid_fs_swarm.sh

From the bids folder - will create derivatives folder for freesurfer/subjects; write out the swarm file; and submit to swarm (with confirmation)

make_bids_fs_swarm.sh    #Must be in the bids folder

print_bids_table.py

Print out information on the created bids dataset, including the number of acq runs per subject with task column headers

usage: print_bids_table.py [-h] [-bids_dir BIDS_DIR] [-session SESSION]
                           [-output_fname OUTPUT_FNAME] [-print_task_counts]

options:
  -h, --help            show this help message and exit
  -bids_dir BIDS_DIR    Location of the bids directory
  -session SESSION      Session of data acq
  -output_fname OUTPUT_FNAME
                        If set the value counts of all the tasks will be written to a csv
                        table. This has more information than the print_task_counts
  -print_task_counts    Print out the number of task runs and number of subjects in the
                        bids dataset