This is where the description of the app goes. Provide quick summaries of:
Check out the brainlife datatypes webpage for a cataloguing of relevant datatypes.
- Dan Bullock's work is supported by the following sources:
- The University of Minnesota’s Neuroimaging Postdoctoral Fellowship Program, College of Science and Engineering's, and the Medical School's NIH funded T32 Neuroimaging Training Grant. NOGA: 1T32EB031512-01
- Sarah Heilbronner's work is supported by the following sources:
- The University of Minnesota’s Neurosciences' and Medical School's NIMH grant for the investigation of "Neural Basis of Psychopathology, Addictions and Sleep Disorders Study Section[NPAS]". NOGA: 5P50MH119569-02-04
- The University of Minnesota’s Neurosciences' Translational Neurophysiology grant. NOGA: 5R01MH118257-04
- The University of Minnesota’s Neurosciences' Addiction Connectome grant. NOGA: 1P30DA048742-01A1
(Provide citations that are directly relevant to this code implementation here)
(Provide citations that are indirectly relevant to this code implementation here)
(Statement of copyright and license)
(Provide a description of how to use this code repository in different contexts)
(provide notes/descriptions/documentation of characteristics and info that is applicable irrespective of the particulars of the compute environment/use-case)
The config.json file is a standard component of application functionality on the brainlife.io platform. However, even outside of the brainlife.io context (running this code in your local python environment), the config.json file is a clean and effective way of managing file and parameter inputs for this code. Typically, the "main" python file/script (main.py, is the default case) reads the .json file (using the json module) into a config dictionary object thusly:
with open('config.json') as config_json:
config = json.load(config_json)
Variables and parameters can then be read in from the dictionary using the relevant keys. An example config.json setup might look something like this:
{
"inputFile_1": "local/path/to/inputFile_1",
"inputFile_2": "local/path/to/inputFile_2",
"inputFile_3": "local/path/to/inputFile_3",
"parameter_1": parameter_1_value,
"parameter_2": parameter_2_value,
"parameter_3": parameter_3_value
}
Consider reviewing the json standard overview for help formatting this object.
The config.json file can provide a standard interface for controlling execution of the code, whether using brainlife.io, docker/singularity, or a local python environment.
Using this app on Brainlife.io
(describe and link the input datatypes)
(parameter settings, including default/typical inputs/values, should be documented and provided on the brainlife App user interface page. However, use this section to also duplicate )
- parameter_1: parameter 1 description
- parameter_2: parameter 1 description
- parameter_3: parameter 1 description
(notes pertinent/specific to usage via the Execute interface)
(notes pertinent/specific to usage via the Pipeline/Rule interface)
LOCAL usage via docker/singularity
Although excution of python code/apps (under the current developmental framework) is typically controlled by the main.py file, for the purposes of portability and standardization, the execution of of this file is acheived via a bash script that sets up some environmental variables for local / HPC usage and then runs the python script in the relevant docker environment (using "singularity exec") in (roughly) the following fashion:
#!/bin/bash
#PBS -l nodes=1:ppn=16
#PBS -l walltime=02:00:00
# run the actual python code
singularity exec docker://organization/container:version python3 main.py
Local use of docker images/containers using singularity requires local installation of singularity (a non-trivial matter). The Sylabs Singularity documentation page provides an overview of installation processes, however, this may not cover all installation cases. For example a debian package has been provided by the neurodebian group. Additionally, Brainlife documention provides a guide to singularity installation/usage as well.
There are two major singularity properties to keep in mind when considering local Singularity configuration: the cache directory and the bind path
Docker images that are pulled from repositories like dockerhub are stored and "built" locally. Usage of a wide range of docker images can quite easily lead to a significant buildup of files in this directory, which can quickly occupy a great deal of harddrive. As such it is important to be mindful of where (e.g. which disk resource) this environmental variable points to.
The virtual environments instantiated when a docker image is run (via singularity) do not have full access to your local file system. Instead, only a narrow set of paths are made available by default. As such, any functions or files called by the code that ARE NOT on these paths will not be found, resulting in an error. There are two approaches to dealing with this:
-
- Ensure that all requisite files & functions are accessible on these paths. For requisite files (e.g. input data) in particular, this may mean storing these in a subdirectory of the directory from which the "main" bash script (e.g. where the singularity call is executed).
With the appropriate modules installed in your local python environment it is also possible to run this code. Ensure that the required modules (see below) are installed, that the config.json file is pointing to the correct files, and you should be ready to go.
(list the packages and modules required for the execution of this code)
(consider https://docs.python.org/3/library/modulefinder.html run on main) (non-exhaustive listing of directly called packages that the relevant docker image would need to have or the user would need to have in their local environment)
(consider describing and linking code and applications which could be used with the output of this code or application to produce a more comprehensive analysis or processing pipeline)
Work to better structure and document this code/application. Please feel free to create issues [using the "issues" tab above] to help foster clarity in documentation, or to suggest alterations to documentation/code more directly. Furthermore, it is acutely understood that many of the functionalities in this package may be redundant implementations of (likely more robust and reliable) functionalities from other packages. The identification of such instances (and their other-package correspondances) would be greatly appreciated. Feel free to create branches which implement these alternatives. Be sure to update the documentation as well to describe your changes and to ensure that your contributions are appropriately credited.