picachooser 1.1.4

Usage

usage: PICAchooser runmode [options]

A program to review (and alter) melodic component selections.

positional arguments:

runmode. Valid choices are “melodic”, “groupmelodic”, “aroma”, and “fix”.

In melodic mode, the default output file is named “badcomponents.txt”; components flagged for removal will be written to MELODICDIR as comma separated integers. Component numbers start at 1 (for compatibility with fsl_regfilt).

In groupmelodic mode, the default output file is named “goodcomponents.txt”; components which are worth keeping will be written to MELODICDIR as integers, one per line. Component numbers start at 0 (for compatibility with standard NIFTI array indexing).

In aroma mode, the file “classified_motion_ICs.txt” must exist in the parent of MELODICDIR; by default the output will be written to “classified_motion_ICs_revised.txt” in the same directory. Component numbers start at 1 (for compatibility with AROMA numbering convention).

In fix mode, the default output file is named “hand_labels_noise.txt” and will be written to MELODICDIR as comma separated integers with square brackets surrounding the line. Component numbers start at 1 (for compatibility with FIX numbering convention).

optional arguments: -h, –help show this help message and exit

Standard input file location specification:

–featdir FEATDIR The FEAT directory associated with this MELODIC run.

–melodicdir MELODICDIR The .ica directory for this MELODIC run.

Nonstandard input file location specification: –backgroundfile BGFILE The anatomic file on which to display the ICs (usually found in FEATDIR/reg/example_func.nii.gz), –funcfile FUNCFILE The functional file to be filtered (usually found in FEATDIR/filtered_func_data.nii.gz), –motionfile MOTIONFILE The anatomic file on which to display the ICs (usually found in FEATDIR/mc/prefiltered_func_data_mcf.par). If the file has a .tsv extension, assume it is an fmriprep confounds file. –ICfile ICFILE The independent component file produced by MELODIC (usually found in MELODICDIR/melodic_IC.nii.gz). –ICmask ICMASK The independent component mask file produced by MELODIC (usually found in MELODICDIR/mask.nii.gz). –timecoursefile MIXFILE The timecourses of the independant components (usually found in MELODICDIR/melodic_mix),

Other arguments: –initfile INITFILE The name of an initial bad component file (in aroma mode, this overrides the default input file for AROMA). –outputfile OUTPUTFILE Where to write the bad component file (this overrides the default output file name). –filteredfile FILTEREDFILE The name of the filtered NIFTI file. If this is set, then when the bad component file is written, the command to generate the filtered file will be printed to the terminal window. –displaythresh DISPLAYTHRESH z threshold for the displayed ICA components. Default is 2.3.

Configuration arguments: –keepcolor KEEPCOLOR Set the color of timecourses to be kept (default is “g”). –discardcolor DISCARDCOLOR Set the color of timecourses to discard (default is “r”). –transmotlimits LOWERLIM UPPERLIM Override the “normal” limits of translational motion from the values in the configuration file to LOWERLIM-UPPERLIM mm. –rotmotlimits LOWERLIM UPPERLIM Override the “normal” limits of rotations motion from the values in the configuration file to LOWERLIM-UPPERLIM radians. –scalemotiontodata Scale motion plots to the motion timecourse values rather than to the limit lines. –componentlinewidth LINEWIDTH Override the component line width (in pixels) in the configuration file with LINEWIDTH. –motionlinewidth LINEWIDTH Override the motion timecourse line widths (in pixels) in the configuration file with LINEWIDTH. –motionlimitlinewidth LINEWIDTH Override the line widths of the motion limit lines (in pixels) in the configuration file with LINEWIDTH. ```

You’ll then get a window that looks like this:


Input file specification

For most datasets, you only need to specify the FEAT directory where the preprocessing was done, and the MELODIC directory where the ICA analysis was performed, and PICAchooser can find all the files it needs to let you do component selection. In some cases, however (looking at you, fmriprep), the files you need to find can be scattered all over the place, with different names (and even different formats). In those cases, you can specify the name and location of every one of the files separately (anything you set with these options will override the default locations calculated from the FEATDIR and MELODICDIR).

Other command line options

–initfile lets you read in a bad component file from anywhere to use as a starting point in your classification. It’s the normal behavior in aroma mode (reading from MELODICDIR/../classified_motion_ICs.txt), but you can do it in any mode with this flag, and it will override the aroma classifications.

–outputfile lets you write the bad component file anywhere you want, rather than just the default location.

–filteredfile specifies where the filtered file would go. If this is set, PICAchooser prints the fsl_regfilt command to filter the data using the currently tagged bad components whenever the file is saved (when the escape key is pressed, or when you quit).

–displaythresh sets the z-threshold for the component maps.

–spatialroi XMIN XMAX YMIN YMAX ZMIN ZMAX lets you zoom in on a cubic ROI within the NIFTI dataset. Useful if you did a constrained ICA on a particular brain region. Set the MAX value to -1 to go to the maximum value for a given dimension. These are voxel indices, with 0 being the first element of each dimension.

* Configuration changes

You can use –keepcolor, –discardcolor, –transmotlimits and –rotmotlimits to alter display behavior for the current run (useful if you’re using the docker container). To change things semi-permanently, edit the file ${HOME}/.picachooser.json. This file is created with default values if it is not present. You can use any valid python color specification string for color values, e.g. “r”, “ff0000”, or “FF0000” could all be used for red.

–componentlinewidth, –motionlinewidth, and –motionlimitlinewidth can all be used to specify various linewidths (in pixels) for the various plots. Useful if you want to make a screenshot pretty for a figure.

–scalemotiontodata autoscales the motion plots to the motion timecourse values rather than to fixed limits.

The motion plots have two dotted lines to indicate “normal” motion limits (by default +/-2.5 mm for translation and +/-0.04 radians for rotation). The locations of these lines are set by “transmotlimits” and “rotmotlimits” in the configuration file. Setting “motionplotstyle” to 0 will remove the lines, and fix the y range of the plots to the limit values. Set the limit line color using “motionlimitcolor”.

pyqtgraph:

1. Luke Campagnola. [PyQtGraph: Scientific Graphics and GUI Library for Python](http://www.pyqtgraph.org)

nibabel:

1. [Nibabel: Python package to access a cacophony of neuro-imaging file formats](https://github.com/nipy/nibabel) | <https://10.5281/zenodo.591597>

numpy:

1. Stéfan van der Walt, S. Chris Colbert and Gaël Varoquaux. The NumPy Array: A Structure for Efficient Numerical Computation, Computing in Science & Engineering, 13, 22-30 (2011) | <https:10.1109/MCSE.2011.37>

scipy:

1. Pauli Virtanen, Ralf Gommers, Travis E. Oliphant, Matt Haberland, Tyler Reddy, David Cournapeau, Evgeni Burovski, Pearu Peterson, Warren Weckesser, Jonathan Bright, Stéfan J. van der Walt, Matthew Brett, Joshua Wilson, K. Jarrod Millman, Nikolay Mayorov, Andrew R. J. Nelson, Eric Jones, Robert Kern, Eric Larson, CJ Carey, İlhan Polat, Yu Feng, Eric W. Moore, Jake VanderPlas, Denis Laxalde, Josef Perktold, Robert Cimrman, Ian Henriksen, E.A. Quintero, Charles R Harris, Anne M. Archibald, Antônio H. Ribeiro, Fabian Pedregosa, Paul van Mulbregt, and SciPy 1.0 Contributors. (2020) SciPy 1.0: Fundamental Algorithms for Scientific Computing in Python. Nature Methods, 17, 261–272 (2020) | <https://doi.org/10.1038/s41592-019-0686-2>

pandas:

1. McKinney, W., pandas: a foundational Python library for data analysis and statistics. Python for High Performance and Scientific Computing, 2011. 14.