Setup Subjects and ProjectManager

About

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.

Future Plans

Two more scripts are being worked on:

• manage_projects.rb
• manage_subject.rb

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.

setup_subject.rb

Usage

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

Required Options

--project

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.

--subject

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.

--user

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.

Additional Options

--help

Display the usage message for setup_subject.rb

--[no-]cluster

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.

• MyProject
  • ProjectInfo
  • doc
  • scripts
  • templates
  • Subject1
    • SubjectInfo
    • analysis
    • behav
    • dicom
    • notes
    • raw
  • Subject2
    • SubjectInfo
    • analysis
    • behav
    • dicom
    • notes
    • raw

Project Directories

ProjectInfo

This file contains information about the project. It is primarily used by the ProjectManager scripts and libraries and should not be deleted

doc

This directory should contain any documentation on the project. Spreadsheets, white papers, references, procedural notation, tutorials, or experimental design documentation

scripts

Any custom scripts written specific to this project are stored here

templates

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)

Subject Directories

SubjectInfo

This file contains information about the subject. It is primarily used by the ProjectManager scripts and libraries and should not be deleted

analysis

Analysis output is stored here. In feat, this would be your Output Directory

behav

Behavioral files for the subject are stored here

dicom

Contains dicom files for the subject

notes

Subject specific notes such as comments on the scan, special conditions specific to the subject, etc. are kept here

raw

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.

Walk Through

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.