Setup Subjects and ProjectManager
From Brain Mapping
SetupSubjects and ProjectManager are a set of utilities designed to simplify the creation of projects and subjects, conversion of dicom files, and analysis. It currently includes a single script "setup_subject.rb" which can be found in your default path.
Two more scripts are being worked on:
The manage_projects.rb script will be a menu driven program allowing the user to create, modify, delete, and tag for archiving projects and their subjects. The manage_subject.rb script will allow the same for an individual subject with the addition of applying design.fsf templates to the subject and running analysis based on those templates. Together they should vastly simplify the researchers work flow.
API for Scripters
All of the ProjectManager scripts are written in Ruby. Included is an API, or interface to projects and subjects. By including the necessary libraries and modules industrious types can create their own custom scripts that conform to the ProjectManager management scheme. The libraries create full object oriented representations of projects and their subjects and store their essential properties in yaml files located at the subject/project root directory called ProjectInfo and SubjectInfo respectively.
In each user's $HOME directory, a hidden file called .projectmanager is created that stores a list of all the user's managed projects.
It's important that these files be left alone for smooth operation of the ProjectManager framework.
The usage is displayed with the -h option like so:
$ setup_subject.rb -h Usage: ./script/setup_subject.rb --project <project> --subject <subject> --user <ssh_username>[options] Required: -p, --project PROJECT The project for subject. -s, --subject SUBJECT Subject code for scan -u, --user USER DNS0 username Additional: -h, --help Display this help/usage message -c, --[no-]cluster Cluster tasks. default: on
- This is the project name the subject will be a member of. A full or relative path is acceptable. If the project does not yet exist, the script will prompt you for creation and the necessary information to do so.
- This is the subject name. It should correspond to the subject name given at scan time. If the subject is not found, an error is given and the script exits. If the subject directory already exists, the script will load the information for that subject and allow the user to refetch dicoms or convert existing dicoms to nifti files.
- This is your user name on the dns0 (brainmapping) servers. You will prompted for this password twice. The first time is for the script to retrieve a list of possible scans under that subject name. If more then one scan for the subject exists, the user is prompted for which one is the correct scan. Only one scan can be assigned to a subject. The second prompt is only done if the user wishes to retrieve the dicom files for the subject.
- Display the usage message for setup_subject.rb
- This option disables submission of nifti conversion to the cluster. The default is cluster enabled. To disable clustering, use the --no-cluster switch.
ProjectManager Directory Organization
The idea behind ProjectManager and its scripts are to create a highly organized and consistent directory layout. Let's take an example project and walk through the intended purpose of each subdirectory.
- This file contains information about the project. It is primarily used by the ProjectManager scripts and libraries and should not be deleted
- This directory should contain any documentation on the project. Spreadsheets, white papers, references, procedural notation, tutorials, or experimental design documentation
- Any custom scripts written specific to this project are stored here
- Design templates to be applied to subjects are kept here (in the future, these templates can be assigned permanently to subjects via the manage_projects and manage_subject scripts)
- This file contains information about the subject. It is primarily used by the ProjectManager scripts and libraries and should not be deleted
- Analysis output is stored here. In feat, this would be your Output Directory
- Behavioral files for the subject are stored here
- Contains dicom files for the subject
- Subject specific notes such as comments on the scan, special conditions specific to the subject, etc. are kept here
- Contains converted nifti files. In FSL, this would be the path of your input files.
The user is free to add any other directories they wish, though these will not be tracked by ProjectManager. If you delete one or more of these directories, it could break the ProjectManager scripts until they are manually recreated. This, of course, is not recommended.
For the purpose of this walk through, we'll assume that this is a new project and needs to be created.
$ setup_subject.rb --project ./MyProj -s subj1 -u foo
The above command will create a project called MyProj in the current directory and setup a subject with the scan name of subj1. The user 'foo' is used for fetching files from the brainmapping servers.
This project does not yet exist. Would you like to create it now? [y,n]
To create the project, enter 'y'. To exit the script enter 'n'.
This project does not yet exist. Project name: MyProj3 Please enter project lab: mylab Please enter project owner (e.g. PI): Foo Please enter project location: /Volumes/Songbook2/data/mylab/foo/ Project Created. . .
- Project name
- Name of the project directory that will contain all subject directories
- Please enter project lab
- This is the lab name the brainmapping scans were done under. For example, if the scan was performed under 'mylab' setup_subject.rb will look for subject sans under the MYLABGROUP directory on the brainmapping servers
- Please enter project owner
- The owner of the project. If you are the owner, enter your name. If your assisting another researcher with their project, you should probably enter their name.
- Please enter project location
- The path to create the project files in. This can be an absolute or relative path. For out lab, this will normally be Songbook1 or Songbook2 data/lab/username directory.
Getting list of dicom directories for subject Password: Subject Initialized.
Enter your brainmapping server password. If only one possible scan for the subject is found, it is automatically set as the subjects scan. If multiples are found, you will be asked which is the proper scan for the subject.
Would you like to fetch dicom files? [y,n] y Fetching subject files. This could take a while, please be patient. . . Password:
If you wish to fetch dicom files at this time, enter 'y'. Otherwise enter 'n'. Dicom files are stored in the PROJECTNAME/SUBJECTNAME/dicom directory.
You can fetch dicoms at a later date by re-running the script at a later time. However, it is very important that you at least allow the script to set up the subject's scan name in the previous step. If you do not, it will corrupt subject creation. If this happens for any reason, simply delete the subject's directory and rerun the script.
Would you like to convert dicoms to Nifti? [y,n] y Your job 9548 ("conversion") has been submitted Your job 9549 ("conversion") has been submitted Your job 9550 ("conversion") has been submitted Your job 9551 ("conversion") has been submitted Your job 9552 ("conversion") has been submitted
If you wish to convert the dicom files to nifti files now, enter 'y'. Each conversion will be submitted to the cluster by default and stored in the PROJECTNAME/SUBJECTNAME/raw directory.