|
1 | | -## The heuristic file |
2 | | - |
3 | | -The heuristic file controls how information about the dicoms is used to convert |
4 | | -to a file system layout (e.g., BIDS). This is a python file that must have the |
5 | | -function `infotodict`, which takes a single argument `seqinfo`. |
6 | | - |
7 | | -### `seqinfo` and the `s` variable |
8 | | - |
9 | | -`seqinfo` is a list of namedtuple objects, each containing the following fields: |
10 | | - |
11 | | -* total_files_till_now |
12 | | -* example_dcm_file |
13 | | -* series_id |
14 | | -* dcm_dir_name |
15 | | -* unspecified2 |
16 | | -* unspecified3 |
17 | | -* dim1 |
18 | | -* dim2 |
19 | | -* dim3 |
20 | | -* dim4 |
21 | | -* TR |
22 | | -* TE |
23 | | -* protocol_name |
24 | | -* is_motion_corrected |
25 | | -* is_derived |
26 | | -* patient_id |
27 | | -* study_description |
28 | | -* referring_physician_name |
29 | | -* series_description |
30 | | -* image_type |
31 | | - |
32 | | -``` |
33 | | -128 125000-1-1.dcm 1 - - |
34 | | -- 160 160 128 1 0.00315 1.37 AAHScout False |
35 | | -``` |
36 | | - |
37 | | -### The dictionary returned by `infotodict` |
38 | | - |
39 | | -This dictionary contains as keys a 3-tuple `(template, a tuple of output types, |
40 | | - annotation classes)`. |
41 | | - |
42 | | -template - how the file should be relative to the base directory |
43 | | -tuple of output types - what format of output should be created - nii.gz, dicom, |
44 | | - etc.,. |
45 | | -annotation classes - unused |
46 | | - |
47 | | -``` |
48 | | -Example: ('func/sub-{subject}_task-face_run-{item:02d}_acq-PA_bold', ('nii.gz', |
49 | | - 'dicom'), None) |
50 | | -``` |
51 | | - |
52 | | -A few fields are defined by default and can be used in the template: |
53 | | - |
54 | | -- item: index within category |
55 | | -- subject: participant id |
56 | | -- seqitem: run number during scanning |
57 | | -- subindex: sub index within group |
58 | | -- session: session info for multi-session studies and when session has been |
59 | | - defined as a parameter for heudiconv |
60 | | - |
61 | | -Additional variables may be added and can be returned in the value of the |
62 | | -dictionary returned from the function. |
63 | | - |
64 | | -`info[some_3-tuple] = [12, 14, 16]` would assign dicom sequence groups 12, 14 |
65 | | -and 16 to be converted using the template specified in `some_3-tuple`. |
66 | | - |
67 | | -if the template contained a non-sanctioned variable, it would have to be |
68 | | -provided in the values for that key. |
69 | | - |
70 | | -``` |
71 | | -some_3_tuple = ('func/sub-{subject}_task-face_run-{item:02d}_acq-{acq}_bold', ('nii.gz', |
72 | | - 'dicom'), None) |
73 | | -``` |
74 | | - |
75 | | -In the above example `{acq}` is not a standard variable. In this case, values |
76 | | -for this variable needs to be added. |
77 | | - |
78 | | -``` |
79 | | -info[some_3-tuple] = [{'item': 12, 'acq': 'AP'}, |
80 | | - {'item': 14, 'acq': 'AP'}, |
81 | | - {'item': 16, 'acq': 'PA'}] |
82 | | -``` |
| 1 | +========= |
| 2 | +Heuristic |
| 3 | +========= |
| 4 | + |
| 5 | +The heuristic file controls how information about the DICOMs is used to convert |
| 6 | +to a file system layout (e.g., BIDS). ``heudiconv`` includes some built-in |
| 7 | +heuristics, including `ReproIn <https://github.com/ReproNim/reproin/blob/master/README.md>`_ |
| 8 | +(which is great to adopt if you will be starting your data collection!). |
| 9 | + |
| 10 | +However, there is a large variety of data out there, and not all DICOMs will be |
| 11 | +covered by the existing heuristics. This section will outline what makes up a |
| 12 | +heuristic file, and some useful functions available when making one. |
| 13 | + |
| 14 | + |
| 15 | +Components |
| 16 | +========== |
| 17 | + |
| 18 | +--------------------- |
| 19 | +`infotodict(seqinfos)` |
| 20 | +--------------------- |
| 21 | + |
| 22 | +The only required function for a heuristic, `infotodict` is used to both define |
| 23 | +the conversion outputs and specify the criteria for scan to output association. |
| 24 | +Conversion outputs are defined as keys, a `tuple` consisting of a template path |
| 25 | +used for the basis of outputs, as well as a `tuple` of output types. Valid types |
| 26 | +include `nii`, `nii.gz`, and `dicom`. |
| 27 | + |
| 28 | +.. note:: |
| 29 | + |
| 30 | + An example conversion key: |
| 31 | + ('sub-{subject}/func/sub-{subject}_task-test_run-{item}_bold', ('nii.gz', 'dicom')) |
| 32 | + |
| 33 | + |
| 34 | +The `seqinfos` parameter is a list of namedtuples which serves as a grouped and |
| 35 | +stacked record of the DICOMs passed in. Each item in `seqinfo` contains DICOM |
| 36 | +metadata that can be used to isolate the series, and assign it to a conversion |
| 37 | +key. |
| 38 | + |
| 39 | +A dictionary of {conversion key: seqinfo} is returned. |
| 40 | + |
| 41 | +------------------------------- |
| 42 | +`create_key(template, outtype)` |
| 43 | +------------------------------- |
| 44 | + |
| 45 | +A common helper function used to create the conversion key in `infotodict`. |
| 46 | + |
| 47 | +------------------ |
| 48 | +`filter_files(fl)` |
| 49 | +------------------ |
| 50 | + |
| 51 | +A utility function used to filter any input files. |
| 52 | + |
| 53 | +If this function is included, every file found will go through this filter. Any |
| 54 | +files where this function returns `True` will be filtered out. |
| 55 | + |
| 56 | +------------------------ |
| 57 | +`filter_dicom(dcm_data)` |
| 58 | +------------------------ |
| 59 | + |
| 60 | +A utility function used to filter any DICOMs. |
| 61 | + |
| 62 | +If this function is included, every DICOM found will go through this filter. Any |
| 63 | +DICOMs where this function returns `True` will be filtered out. |
| 64 | + |
| 65 | +---------------------------- |
| 66 | +`infotoids(seqinfos, outdir)` |
| 67 | +---------------------------- |
| 68 | + |
| 69 | +Further processing on `seqinfos` to deduce/customize subject, session, and locator. |
| 70 | + |
| 71 | +A dictionary of {"locator": locator, "session": session, "subject": subject} is returned. |
0 commit comments