|
1 | 1 | # xnat_downloader |
2 | 2 | [](https://circleci.com/gh/HBClab/xnat_downloader) |
3 | 3 |
|
4 | | -## Install (within the github directory) |
5 | | - |
6 | | -```python setup.py install``` |
7 | | - |
8 | | -## Run |
9 | | - |
10 | | -```xnat_downloader -i <input>.json``` |
11 | | - |
12 | | -## Formatting the json |
13 | | - |
14 | | -The json file specifies what you want to download from xnat as well as where you want to download it to. The keywords in the json file let you customize what values to pass into the xnat_downloader script which will determine what scans get downloaded. |
15 | | - |
16 | | -- destination: the base directory to create the BIDS structure |
17 | | - |
18 | | -- project: the project name as it appears on xnat |
19 | | - |
20 | | -- subjects: (optional) a list ([]) that specifies which subjects you want to download (e.g. [1, 4, 60]) |
21 | | - |
22 | | -- scans: (optional) The list of scan types you want to download (e.g. ["anat","func","fmap","dwi"] |
23 | | - |
24 | | -## The Reproin heuristic |
25 | | -Sequence names on the scanner must follow this specification to avoid manual conversion/handling: |
26 | | - |
27 | | -``` |
28 | | - [PREFIX:]<seqtype[-label]>[_ses-<SESID>][_task-<TASKID>][_acq-<ACQLABEL>][_run-<RUNID>][_dir-<DIR>][<more BIDS>][__<custom>] |
29 | | -
|
30 | | -where |
31 | | -
|
32 | | - [PREFIX:] - leading capital letters followed by : are stripped/ignored |
33 | | - <...> - value to be entered |
34 | | - [...] - optional -- might be nearly mandatory for some modalities (e.g., |
35 | | - run for functional) and very optional for others |
36 | | - *ID - alpha-numerical identifier (e.g. 01,02, pre, post, pre01) for a run, |
37 | | - task, session. Note that makes more sense to use numerical values for |
38 | | - RUNID (e.g., _run-01, _run-02) for obvious sorting and possibly |
39 | | - descriptive ones for e.g. SESID (_ses-movie, _ses-localizer) |
40 | | -<seqtype[-label]> |
41 | | - a known BIDS sequence type which is usually a name of the folder under |
42 | | - subject's directory. And (optional) label is specific per sequence type |
43 | | - (e.g. typical "bold" for func, or "T1w" for "anat"), which could often |
44 | | - (but not always) be deduced from DICOM. Known to BIDS modalities are: |
45 | | - anat - anatomical data. Might also be collected multiple times across |
46 | | - runs (e.g. if subject is taken out of magnet etc), so could |
47 | | - (optionally) have "_run" definition attached. For "standard anat" |
48 | | - labels, please consult to "8.3 Anatomy imaging data" but most |
49 | | - common are 'T1w', 'T2w', 'angio' |
50 | | - func - functional (AKA task, including resting state) data. |
51 | | - Typically contains multiple runs, and might have multiple different |
52 | | - tasks different per each run |
53 | | - (e.g. _task-memory_run-01, _task-oddball_run-02) |
54 | | - fmap - field maps |
55 | | - dwi - diffusion weighted imaging (also can as well have runs) |
56 | | -_ses-<SESID> (optional) |
57 | | - a session. Having a single sequence within a study would make that study |
58 | | - follow "multi-session" layout. A common practice to have a _ses specifier |
59 | | - within the scout sequence name. You can either specify explicit session |
60 | | - identifier (SESID) or just say to maintain, create (starts with 1). |
61 | | - You can also use _ses-{date} in case of scanning phantoms or non-human |
62 | | - subjects and wanting sessions to be coded by the acquisition date. |
63 | | -_task-<TASKID> (optional) |
64 | | - a short name for a task performed during that run. If not provided and it |
65 | | - is a func sequence, _task-UNKNOWN will be automatically added to comply with |
66 | | - BIDS. Consult http://www.cognitiveatlas.org/tasks on known tasks. |
67 | | -_acq-<ACQLABEL> (optional) |
68 | | - a short custom label to distinguish a different set of parameters used for |
69 | | - acquiring the same modality (e.g. _acq-highres, _acq-lowres etc) |
70 | | -_run-<RUNID> (optional) |
71 | | - a (typically functional) run. The same idea as with SESID. |
72 | | -_dir-[AP,PA,LR,RL,VD,DV] (optional) |
73 | | - to be used for fmap images, whenever a pair of the SE images is collected |
74 | | - to be used to estimate the fieldmap |
75 | | -<more BIDS> (optional) |
76 | | - any other fields (e.g. _acq-) from BIDS acquisition |
77 | | -__<custom> (optional) |
78 | | - after two underscores any arbitrary comment which will not matter to how |
79 | | - layout in BIDS. But that one theoretically should not be necessary, |
80 | | - and (ab)use of it would just signal lack of thought while preparing sequence |
81 | | - name to start with since everything could have been expressed in BIDS fields. |
82 | | -## Last moment checks/FAQ: |
83 | | -- Functional runs should have _task-<TASKID> field defined |
84 | | -- Do not use "+", "_" or "-" within SESID, TASKID, ACQLABEL, RUNID, so we |
85 | | - could detect "canceled" runs. |
86 | | -- If run was canceled -- just copy canceled run (with the same index) and re-run |
87 | | - it. Files with overlapping name will be considered duplicate/canceled session |
88 | | - and only the last one would remain. The others would acquire |
89 | | - __dup0<number> suffix. |
90 | | -Although we still support "-" and "+" used within SESID and TASKID, their use is |
91 | | -not recommended, thus not listed here |
92 | | -``` |
| 4 | +xnat_downloader downloads dicom data from an xnat server, converts the dicoms to niftis using [dcm2niix](https://github.com/rordenlab/dcm2niix), and saves the output in [BIDS](http://bids.neuroimaging.io/) format. See the [documentation](http://xnat-downloader.readthedocs.io/en/latest/) for details and usage |
0 commit comments