Package: crtoolbox
The Confidence Regions ToolboxTable of ContentsBackgroundInstallUsageFile HandlingRegressionGenerating CRsWorking with BoundariesDisplaying VolumesData Simulation2D Data Simulation3D Data SimulationLicenseBackgroundThe crtoolbox is a Python-based software package designed to provide Confidence Regions (CRs) for excursion sets derived from neuroimaging data. At present, the methods provided are those proposed inSommerfeld, et al. 2017,Bowring, et al. 2021andMaullin-Sapey, et al. 2022. These methods provide CRs for 2D and 3D regression coefficient images, Cohen's d effect size images, and conjunction or disjunction images. For each approach, estimated inner and outer sets are constructed for an excursion set of interest. These estimated sets, together known as Confidence Regions, are designed to bound the true excursion set with a user-specified level of confidence.Further detail on CRs, alongside an extensive demonstration of thecrtoolbox, can be found in thecrtoolbox_demorepository, which originally formed part of theBeyond Blobologycourse at the Organization for Human Brain Mapping conference 2023.Please Note:The function calls described in this practical have only been tested with thecrtoolbox==0.1.6version. Later versions may not be compatible.InstallTo install thecrtoolboxplease use pip:pip install crtoolboxUsageAt present thecrtoolboxconsists of several standalone functions, which may be used together to generate CRs. The most relevant of these are detailed below. Full docstrings for each function can be found in the files linked.File HandlingThe following functions can be used for file manipulation and handling:read_image: This function may be used to read 2D or 3D images. Supported formats include; RGB images supported by theImagepackage,numpydata files and and NIfTI images.addBlockToNifti: This function adds a block of voxels to a pre-existing NIFTI or creates a new NIFTI of specified dimensions if the file does not already exist.remove_files: This function removes lists of files.These functions may be found incrtoolbox.lib.fileio.Effect Size imagesThe following functions can be used for regression and effect size estimation for either 2d or 3d images.regression: This function can be used to perform a standard mass-univariate linear regression and obtain beta coefficient estimates ("raw" effect sizes). Please note that for large analyses, other packages may be more suitable (for instance...).cohens: This function can be used to generate cohen's D images.Please note that the residuals and standard deviation images output byregressionandcohensare not the same;regressionoutputs regression residuals and the MLE for the standard deviation, whilstcohensoutputs transformed residuals (generated according to method 2 ofBowring, et al. 2021) alongside their standard deviation.These functions may be found incrtoolbox.lib.regressionandcrtoolbox.lib.cohens, respectively.Generating CRsThe following function is used to generate confidence regions. It supports both 2d and 3d images.generate_CRs: This function uses the outputs ofregression, orcohens, to generate CRs for raw or standardized effect sizes, respectively.This function may be found incrtoolbox.generate.Coverage AssessmentThe below function may be used to check whether the CRs correctly bound the underlying true excursion set (note this is only useful for simulation settings). It uses both a binary inclusion check and the interpolation methods outlines inBowring, et al. 2019.check_violations: Given a pair of CRs and a "true" excursion set, this function assesses whether the CRs correctly enclose the excursion set.This function may be found incrtoolbox.coverage.Working with BoundariesThe below function may be useful for developing the tool.get_bdry_map_combined: This function produces an image of the boundary of an excursion set. Both 2D and 3D images are supported.This function may be found incrtoolbox.lib.boundary.Displaying VolumesThe below functions can be used to display various images in an interactive format.display_volume, display_crsdisplay_volume: This function can be used to dispay individual 2D or 3D volumes. Masking is supported.display_crs: This function can be used to dispay 2D or 3D CRs. Masking is supported.These functions may be found incrtoolbox.lib.display.Data SimulationThecrtoolboxcurrently contains custom code for generating simulated data which may be useful for testing and demonstration. The below sections provide detail on the available 2D and 3D simulated datasets respectively.2D Data SimulationThe below classes can be used to generate 2D signals:CircleSignal: This will create a circular signal with user specified radius, center, smoothness and peak magnitude.SquareSignal: This will create a square signal with user specified radius, center, smoothness and peak magnitude.RampSignal: This will create a linear ramp signal with user specified slope and value range.The above classes will create objects representing each of the signal types. An image of the signal can be viewed using theplotmethod. Noise can also be generated using theNoiseclass.Noise: This will create noise with user specified magnitude, smoothness and heterogeniety settings.To use the above classes to generate data thegenerate_data_2Dfunction can be used:generate_data_2D: This will take in a signal object and a noise object and return the user's specified number of data instances.The classes for signal generation and noise generation, as well as thegenerate_data_2Dfunction, may be found incrtoolbox.tests.generate_2d_data.3D Data SimulationThe below function can be used to generate 3D simulated data resembling real-world fMRI images.generate_data: This will generate simualted 3D fMRI images according to a mass-univariate linear regression model, with fixed masking.For further detail on the pipeline used to generate these images, seeMaullin-Sapey & Nichols. 2022. Thegenerate_datafunction may be found incrtoolbox.tests.generate_ni_data.LicenseMIT