Skip to content

Commit 33791e0

Browse files
jdkentjdkent
committed
first commit
0 parents  commit 33791e0

File tree

4 files changed

+279
-0
lines changed

4 files changed

+279
-0
lines changed

‎README.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# xcpEngine on Argon
2+
3+
This guide is based off of [xcpEngine's own tutorial](https://xcpengine.readthedocs.io/config/tutorial.html)
4+
5+
This a guide for running [xcpEngine](https://xcpengine.readthedocs.io/index.html) on [Argon](https://wiki.uiowa.edu/display/hpcdocs/Argon+Cluster).
6+
xcpEngine is a tool that takes the output from [fmriprep](https://fmriprep.readthedocs.io/en/stable/)
7+
and completes a variety of analytical outputs (e.g. reho, alff, etc) as both niftis and tabular data (i.e. CSVs).
8+
The CSV data is data from a per-region/parcel basis from an atlas.
9+
xcpEngine supports several atlases, so you can get output from several atlas in one run.
10+
11+
The first step will be to log into argon (through a terminal)
12+
```
13+
# example ssh [email protected]
14+
ssh <hawkid>@argon.hpc.uiowa.edu
15+
```
16+
and if you're off campus, you can use port 40
17+
```
18+
ssh <hawkid>@argon.hpc.uiowa.edu -p 40
19+
```
20+
21+
While logged into Argon, we will be using the [singularity](https://www.sylabs.io/guides/2.6/user-guide/)
22+
image of xcpEngine so we can run it on Argon without having to worry about installing all the necessary software.
23+
Even though xcpEngine does not have an image on [singularityhub](https://singularity-hub.org/),
24+
we can build a singularity image from xcpEngine's docker image on [dockerhub](https://hub.docker.com/r/pennbbl/xcpengine).
25+
26+
It's better to build from a tagged version of an image (e.g. `1.0`) instead of `lastest` because `latest` represents
27+
the most current version of the image and everytime they change the image, the `latest` tag will now point to a different image.
28+
If we want to be reproducible (it's all the rage these days), using the tag `1.0` should always point to the same
29+
image across eternity and should always give us the same result.
30+
31+
```
32+
# make a place to keep our singularity images
33+
mkdir -p ${HOME}/simgs
34+
# make our singularity image
35+
singularity build ~/simgs/xcpEngine_v1.0.simg docker://pennbbl/xcpengine:1.0
36+
```
37+
38+
To run xcpEngine, we need data, specifically data that has been processed by fmriprep.
39+
Thankfully, the developers of xcpEngine have provided an example dataset.
40+
```
41+
# url of the data
42+
curl -o fmriprep.tar.gz -SL https://ndownloader.figshare.com/files/13598186
43+
# untar (extract) the data
44+
tar xvf fmriprep.tar.gz
45+
```
46+
47+
Next, we need two files: 1) a design file that defines what steps we want to run on our data
48+
and 2) a cohort file that specifies which participants to run.
49+
50+
```
51+
# download the design file (if necessary)
52+
curl -O https://raw.githubusercontent.com/PennBBL/xcpEngine/master/designs/fc-36p.dsn
53+
```
54+
55+
Here are the internals of the cohort file:
56+
```
57+
id0,img
58+
sub-1,fmriprep/sub-1/func/sub-1_task-rest_space-T1w_desc-preproc_bold.nii.gz
59+
```
60+
61+
All we need now is a directory to place the outputs, then we can run xcpEngine.
62+
```
63+
mkdir -p ./xcp_output
64+
```
65+
66+
Now we are ready to run xcpEngine!
67+
I made a little script to help make a "job" file we can submit to the cluster.
68+
It requires our email address as input:
69+
```
70+
./create_job.sh [email protected]
71+
```
72+
73+
`create_job.sh` should create a "job" file named `sample_xcpengine.job` that looks like this:
74+
```
75+
#!/bin/bash
76+
77+
#$ -pe smp 6
78+
#$ -q UI
79+
#$ -m bea
80+
#$ -M [email protected]
81+
#$ -e /Users/jdkent/xcpEngine/fc.err
82+
#$ -o /Users/jdkent/xcpEngine/fc.out
83+
84+
singularity run -H /Users/jdkent/singularity_home \
85+
/Users/jdkent/simgs/xcpEngine_v1.0.simg \
86+
-d /Users/jdkent/xcpEngine/fc-36p.dsn \
87+
-c /Users/jdkent/xcpEngine/func_cohort.csv \
88+
-o /Users/jdkent/xcpEngine/xcp_output \
89+
-t 1 -r /Users/jdkent/xcpEngine
90+
```
91+
92+
and we can submit `sample_xcpengine.job` to the cluster using:
93+
```
94+
qsub sample_xcpengine.job
95+
```
96+
97+
We will get an email when the job starts and finishes.
98+
99+
And you're done running it!
100+
101+
TODO: analyze the outputs
102+

‎create_job.sh‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
#!/bin/bash
2+
3+
email=$1
4+
5+
echo "\
6+
#!/bin/bash
7+
8+
#$ -pe smp 6
9+
#$ -q UI
10+
#$ -m bea
11+
#$ -M ${email}
12+
#$ -e ${PWD}/fc.err
13+
#$ -o ${PWD}/fc.out
14+
15+
singularity run -H ${HOME}/singularity_home \
16+
${HOME}/simgs/xcpEngine_v1.0.simg \
17+
-d ${PWD}/fc-36p.dsn \
18+
-c ${PWD}/func_cohort.csv \
19+
-o ${PWD}/xcp_output \
20+
-t 1 -r ${PWD}
21+
" > sample_xcpengine.job

‎fc-36p.dsn‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
#!/usr/bin/env bash
2+
3+
###################################################################
4+
# ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ ⊗ #
5+
###################################################################
6+
7+
8+
###################################################################
9+
# This design file stores the values of all variables required to
10+
# execute a complete neuroimage processing pipeline. You may
11+
# execute the analysis specified in this design file by calling
12+
# (in any v4 or higher bash terminal):
13+
#
14+
# xcpEngine -d <design> -c <cohort> -o <output> <options>
15+
#
16+
# Variables fall into five general categories:
17+
# * ANALYSIS VARIABLES are used at all stages of this analysis.
18+
# * PIPELINE specifies the modules that comprise the analysis.
19+
# * MODULE VARIABLES are used during one stage of the analysis.
20+
# These are typically array variables with array
21+
# indices equal to the index of the module that
22+
# calls them.
23+
# * OUTPUT VARIABLES may be used at all stages of the analysis.
24+
# These are typically array variables with array
25+
# indices equal to the value of the primary
26+
# subject identifier. They will appear only in
27+
# localised design files.
28+
###################################################################
29+
30+
31+
###################################################################
32+
# ANALYSIS VARIABLES
33+
###################################################################
34+
35+
analysis=fc_$(whoami)
36+
design=/Users/jdkent/xcpEngine/fc-36p.dsn
37+
sequence=anatomical
38+
standard=MNI%2x2x2
39+
40+
###################################################################
41+
# PIPELINE
42+
###################################################################
43+
44+
pipeline=prestats,confound2,regress,fcon,reho,alff,roiquant,norm,qcfc
45+
46+
###################################################################
47+
# 1 PRESTATS
48+
###################################################################
49+
50+
prestats_rerun[1]=1
51+
prestats_cleanup[1]=1
52+
prestats_process[1]=FMP
53+
54+
55+
###################################################################
56+
# 2 CONFOUND2
57+
###################################################################
58+
59+
confound2_rps[2]=1
60+
confound2_rms[2]=0
61+
confound2_wm[2]=1
62+
confound2_csf[2]=1
63+
confound2_gsr[2]=1
64+
confound2_acompcor[2]=0
65+
confound2_tcompcor[2]=0
66+
confound2_aroma[2]=0
67+
confound2_past[2]=0
68+
confound2_dx[2]=1
69+
confound2_sq[2]=2
70+
confound2_custom[2]=
71+
confound2_censor[2]=0
72+
confound2_censor_contig[2]=0
73+
confound2_framewise[2]=rmss:0.083,fds:0.167,dv:2
74+
confound2_rerun[2]=0
75+
confound2_cleanup[2]=1
76+
77+
###################################################################
78+
# 3 REGRESS
79+
###################################################################
80+
81+
regress_tmpf[3]=butterworth
82+
regress_hipass[3]=0.01
83+
regress_lopass[3]=0.08
84+
regress_tmpf_order[3]=1
85+
regress_tmpf_pass[3]=2
86+
regress_tmpf_ripple[3]=0.5
87+
regress_tmpf_ripple2[3]=20
88+
regress_dmdt[3]=2
89+
regress_1ddt[3]=1
90+
regress_smo[3]=6
91+
regress_sptf[3]=susan
92+
regress_usan[3]=default
93+
regress_usan_space[3]=
94+
regress_rerun[3]=0
95+
regress_cleanup[3]=1
96+
regress_process[3]=DMT-TMP-REG
97+
98+
###################################################################
99+
# 4 FCON
100+
###################################################################
101+
102+
fcon_atlas[4]=all
103+
fcon_metric[4]=corrcoef
104+
fcon_thr[4]=N
105+
fcon_pad[4]=FALSE
106+
fcon_rerun[4]=0
107+
fcon_cleanup[4]=1
108+
109+
###################################################################
110+
# 5 REHO
111+
###################################################################
112+
113+
reho_nhood[5]=vertices
114+
reho_roikw[5]=0 # does nothing at the moment
115+
reho_sptf[5]=susan
116+
reho_smo[5]=6
117+
reho_rerun[5]=0
118+
reho_cleanup[5]=1
119+
120+
###################################################################
121+
# 6 ALFF
122+
###################################################################
123+
124+
alff_hipass[6]=0.01
125+
alff_lopass[6]=0.08
126+
alff_sptf[6]=susan
127+
alff_smo[6]=6
128+
alff_rerun[6]=0
129+
alff_cleanup[6]=1
130+
131+
###################################################################
132+
# 7 ROIQUANT
133+
###################################################################
134+
135+
roiquant_atlas[7]=all
136+
roiquant_globals[7]=1
137+
roiquant_vol[7]=0
138+
roiquant_rerun[7]=0
139+
roiquant_cleanup[7]=1
140+
141+
###################################################################
142+
# 8 NORM
143+
###################################################################
144+
norm_primary[8]=1
145+
norm_rerun[8]=0
146+
norm_cleanup[8]=1
147+
148+
##################################################################
149+
# 9 QCFC
150+
###################################################################
151+
qcfc_atlas[9]=power264
152+
qcfc_sig[9]=fdr
153+
qcfc_rerun[9]=0
154+
qcfc_cleanup[9]=1

‎func_cohort.csv‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
id0,img
2+
sub-1,fmriprep/sub-1/func/sub-1_task-rest_space-T1w_desc-preproc_bold.nii.gz

0 commit comments

Comments
 (0)