Skip to content

Commit 38032b5

Browse files
yarikopticyarikoptic
committed
Add entities objects+rules from bids v1.6.0-480-ge47283a2
ATM we will need only these two files to establish consistent order of the entities in the filenames. Later we might want to carry a more complete copy of the schema, or may be eventually some proper bidsschema python package would appear to provide desired functionality anyways
1 parent d54a928 commit 38032b5

File tree

3 files changed

+389
-0
lines changed

3 files changed

+389
-0
lines changed

‎heudiconv/bids/data/schema/objects/entities.yaml

Lines changed: 356 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,356 @@
1+
---
2+
# This file describes entities present in BIDS filenames.
3+
# WARNING: The entities are presented here in alphabetical order!
4+
# The appropriate order of entities in filenames is defined in `rules/entities.yaml`,
5+
# rather than this file (`objects/entities.yaml`).
6+
acquisition:
7+
name: Acquisition
8+
entity: acq
9+
description: |
10+
The `acq-<label>` key/value pair corresponds to a custom label the
11+
user MAY use to distinguish a different set of parameters used for
12+
acquiring the same modality.
13+
For example this should be used when a study includes two T1w images - one
14+
full brain low resolution and one restricted field of view but high
15+
resolution.
16+
In such case two files could have the following names:
17+
`sub-01_acq-highres_T1w.nii.gz` and `sub-01_acq-lowres_T1w.nii.gz`, however
18+
the user is free to choose any other label than `highres` and `lowres` as long
19+
as they are consistent across subjects and sessions.
20+
In case different sequences are used to record the same modality
21+
(for example, `RARE` and `FLASH` for T1w)
22+
this field can also be used to make that distinction.
23+
At what level of detail to make the distinction (for example,
24+
just between `RARE` and `FLASH`, or between `RARE`, `FLASH`, and `FLASHsubsampled`)
25+
remains at the discretion of the researcher.
26+
type: string
27+
format: label
28+
ceagent:
29+
name: Contrast Enhancing Agent
30+
entity: ce
31+
description: |
32+
The `ce-<label>` key/value can be used to distinguish
33+
sequences using different contrast enhanced images.
34+
The label is the name of the contrast agent.
35+
The key `"ContrastBolusIngredient"` MAY also be added in the JSON file,
36+
with the same label.
37+
type: string
38+
format: label
39+
chunk:
40+
name: Chunk
41+
entity: chunk
42+
description: |
43+
The `chunk-<index>` key/value pair is used to distinguish between different
44+
regions, 2D images or 3D volumes files, of the same physical sample with
45+
different fields of view acquired in the same imaging experiment.
46+
type: string
47+
format: index
48+
density:
49+
name: Density
50+
entity: den
51+
description: |
52+
Density of non-parametric surfaces.
53+
MUST have a corresponding `Density` metadata field to provide
54+
interpretation.
55+
56+
This entity is only applicable to derivative data.
57+
type: string
58+
format: label
59+
description:
60+
name: Description
61+
entity: desc
62+
description: |
63+
When necessary to distinguish two files that do not otherwise have a
64+
distinguishing entity, the `_desc-<label>` keyword-value SHOULD be used.
65+
66+
This entity is only applicable to derivative data.
67+
type: string
68+
format: label
69+
direction:
70+
name: Phase-Encoding Direction
71+
entity: dir
72+
description: |
73+
The `dir-<label>` key/value can be set to an arbitrary alphanumeric label
74+
(for example, `dir-LR` or `dir-AP`) to distinguish different phase-encoding
75+
directions.
76+
type: string
77+
format: label
78+
echo:
79+
name: Echo
80+
entity: echo
81+
description: |
82+
If files belonging to an entity-linked file collection are acquired at different
83+
echo times, the `_echo-<index>` key/value pair MUST be used to distinguish
84+
individual files.
85+
This entity represents the `"EchoTime"` metadata field. Please note that the `<index>`
86+
denotes the number/index (in the form of a nonnegative integer), not the
87+
`"EchoTime"` value which needs to be stored in the field `"EchoTime"` of the separate
88+
JSON file.
89+
type: string
90+
format: index
91+
flip:
92+
name: Flip Angle
93+
entity: flip
94+
description: |
95+
If files belonging to an entity-linked file collection are acquired at different
96+
flip angles, the `_flip-<index>` key/value pair MUST be used to distinguish
97+
individual files.
98+
This entity represents the `"FlipAngle"` metadata field. Please note that the `<index>`
99+
denotes the number/index (in the form of a nonnegative integer), not the `"FlipAngle"`
100+
value which needs to be stored in the field `"FlipAngle"` of the separate JSON file.
101+
type: string
102+
format: index
103+
hemisphere:
104+
name: Hemisphere
105+
entity: hemi
106+
description: |
107+
The `hemi-<label>` entity indicates which hemibrain is described by the file.
108+
Allowed label values for this entity are `L` and `R`, for the left and right
109+
hemibrains, respectively.
110+
type: string
111+
format: label
112+
enum:
113+
- "L"
114+
- "R"
115+
inversion:
116+
name: Inversion Time
117+
entity: inv
118+
description: |
119+
If files belonging to an entity-linked file collection are acquired at different
120+
inversion times, the `_inv-<index>` key/value pair MUST be used to distinguish
121+
individual files.
122+
This entity represents the `"InversionTime` metadata field. Please note that the `<index>`
123+
denotes the number/index (in the form of a nonnegative integer), not the `"InversionTime"`
124+
value which needs to be stored in the field `"InversionTime"` of the separate JSON file.
125+
type: string
126+
format: index
127+
label:
128+
name: Label
129+
entity: label
130+
description: |
131+
Tissue-type label, following a prescribed vocabulary.
132+
Applies to binary masks and probabilistic/partial volume segmentations
133+
that describe a single tissue type.
134+
135+
This entity is only applicable to derivative data.
136+
type: string
137+
format: label
138+
modality:
139+
name: Corresponding Modality
140+
entity: mod
141+
description: |
142+
The `mod-<label>` key/value pair corresponds to modality label for defacing
143+
masks, for example, T1w, inplaneT1, referenced by a defacemask image.
144+
For example, `sub-01_mod-T1w_defacemask.nii.gz`.
145+
type: string
146+
format: label
147+
mtransfer:
148+
name: Magnetization Transfer
149+
entity: mt
150+
description: |
151+
If files belonging to an entity-linked file collection are acquired at different
152+
magnetization transfer (MT) states, the `_mt-<label>` key/value pair MUST be used to
153+
distinguish individual files.
154+
This entity represents the `"MTState"` metadata field. Allowed label values for this
155+
entity are `on` and `off`, for images acquired in presence and absence of an MT pulse,
156+
respectively.
157+
type: string
158+
enum:
159+
- "on"
160+
- "off"
161+
part:
162+
name: Part
163+
entity: part
164+
description: |
165+
This entity is used to indicate which component of the complex
166+
representation of the MRI signal is represented in voxel data.
167+
The `part-<label>` key/value pair is associated with the DICOM Tag
168+
`0008, 9208`.
169+
Allowed label values for this entity are `phase`, `mag`, `real` and `imag`,
170+
which are typically used in `part-mag`/`part-phase` or
171+
`part-real`/`part-imag` pairs of files.
172+
173+
Phase images MAY be in radians or in arbitrary units.
174+
The sidecar JSON file MUST include the units of the `phase` image.
175+
The possible options are `"rad"` or `"arbitrary"`.
176+
177+
When there is only a magnitude image of a given type, the `part` key MAY be
178+
omitted.
179+
type: string
180+
enum:
181+
- mag
182+
- phase
183+
- real
184+
- imag
185+
processing:
186+
name: Processed (on device)
187+
entity: proc
188+
description: |
189+
The proc label is analogous to rec for MR and denotes a variant of
190+
a file that was a result of particular processing performed on the device.
191+
192+
This is useful for files produced in particular by Elekta's MaxFilter
193+
(for example, `sss`, `tsss`, `trans`, `quat` or `mc`),
194+
which some installations impose to be run on raw data because of active
195+
shielding software corrections before the MEG data can actually be
196+
exploited.
197+
type: string
198+
format: label
199+
reconstruction:
200+
name: Reconstruction
201+
entity: rec
202+
description: |
203+
The `rec-<label>` key/value can be used to distinguish
204+
different reconstruction algorithms (for example `MoCo` for the ones using motion
205+
correction).
206+
type: string
207+
format: label
208+
recording:
209+
name: Recording
210+
entity: recording
211+
description: |
212+
More than one continuous recording file can be included (with different
213+
sampling frequencies).
214+
In such case use different labels.
215+
For example: `_recording-contrast`, `_recording-saturation`.
216+
type: string
217+
format: label
218+
resolution:
219+
name: Resolution
220+
entity: res
221+
description: |
222+
Resolution of regularly sampled N-dimensional data.
223+
MUST have a corresponding `"Resolution"` metadata field to provide
224+
interpretation.
225+
226+
This entity is only applicable to derivative data.
227+
type: string
228+
format: label
229+
run:
230+
name: Run
231+
entity: run
232+
description: |
233+
If several scans with the same acquisition parameters are acquired in the same session,
234+
they MUST be indexed with the [`run-<index>`](../99-appendices/09-entities.md#run) entity:
235+
`_run-1`, `_run-2`, `_run-3`, and so on (only nonnegative integers are allowed as
236+
run labels).
237+
238+
If different entities apply,
239+
such as a different session indicated by [`ses-<label>`](../99-appendices/09-entities.md#ses),
240+
or different acquisition parameters indicated by
241+
[`acq-<label>`](../99-appendices/09-entities.md#acq),
242+
then `run` is not needed to distinguish the scans and MAY be omitted.
243+
type: string
244+
format: index
245+
sample:
246+
name: Sample
247+
entity: sample
248+
description: |
249+
A sample pertaining to a subject such as tissue, primary cell
250+
or cell-free sample.
251+
The `sample-<label>` key/value pair is used to distinguish between different
252+
samples from the same subject.
253+
The label MUST be unique per subject and is RECOMMENDED to be unique
254+
throughout the dataset.
255+
type: string
256+
format: label
257+
session:
258+
name: Session
259+
entity: ses
260+
description: |
261+
A logical grouping of neuroimaging and behavioral data consistent across
262+
subjects.
263+
Session can (but doesn't have to) be synonymous to a visit in a
264+
longitudinal study.
265+
In general, subjects will stay in the scanner during one session.
266+
However, for example, if a subject has to leave the scanner room and then
267+
be re-positioned on the scanner bed, the set of MRI acquisitions will still
268+
be considered as a session and match sessions acquired in other subjects.
269+
Similarly, in situations where different data types are obtained over
270+
several visits (for example fMRI on one day followed by DWI the day after)
271+
those can be grouped in one session.
272+
Defining multiple sessions is appropriate when several identical or similar
273+
data acquisitions are planned and performed on all -or most- subjects,
274+
often in the case of some intervention between sessions
275+
(for example, training).
276+
type: string
277+
format: label
278+
space:
279+
name: Space
280+
entity: space
281+
description: |
282+
The space entity can be used to indicate
283+
the way in which electrode positions are interpreted
284+
(for EEG/MEG/iEEG data) or
285+
the spatial reference to which a file has been aligned (for MRI data).
286+
The space `<label>` MUST be taken from one of the modality specific lists in
287+
[Appendix VIII](../99-appendices/08-coordinate-systems.md).
288+
For example for iEEG data, the restricted keywords listed under
289+
[iEEG Specific Coordinate Systems](../99-appendices/08-coordinate-systems.md#ieeg-specific-coordinate-systems)
290+
are acceptable for `<label>`.
291+
292+
For EEG/MEG/iEEG data, this entity can be applied to raw data, but
293+
for other data types, it is restricted to derivative data.
294+
type: string
295+
format: label
296+
split:
297+
name: Split
298+
entity: split
299+
description: |
300+
In the case of long data recordings that exceed a file size of 2Gb, the
301+
.fif files are conventionally split into multiple parts.
302+
Each of these files has an internal pointer to the next file.
303+
This is important when renaming these split recordings to the BIDS
304+
convention.
305+
306+
Instead of a simple renaming, files should be read in and saved under their
307+
new names with dedicated tools like [MNE-Python](https://mne.tools/),
308+
which will ensure that not only the file names, but also the internal file
309+
pointers will be updated.
310+
It is RECOMMENDED that .fif files with multiple parts use the
311+
`split-<index>` entity to indicate each part.
312+
If there are multiple parts of a recording and the optional `scans.tsv` is provided,
313+
remember to list all files separately in `scans.tsv` and that the entries for the
314+
`acq_time` column in `scans.tsv` MUST all be identical, as described in
315+
[Scans file](../03-modality-agnostic-files.md#scans-file).
316+
type: string
317+
format: index
318+
stain:
319+
name: Stain
320+
entity: stain
321+
description: |
322+
The `stain-<label>` key/pair values can be used to distinguish image files
323+
from the same sample using different stains or antibodies for contrast enhancement.
324+
Stains SHOULD be indicated in the `"SampleStaining"` key in the sidecar JSON file,
325+
although the label may be different.
326+
Description of antibodies SHOULD also be indicated in `"SamplePrimaryAntibodies"`
327+
and/or `"SampleSecondaryAntobodies"` as appropriate.
328+
type: string
329+
format: label
330+
subject:
331+
name: Subject
332+
entity: sub
333+
description: |
334+
A person or animal participating in the study.
335+
type: string
336+
format: label
337+
task:
338+
name: Task
339+
entity: task
340+
description: |
341+
Each task has a unique label that MUST only consist of letters and/or
342+
numbers (other characters, including spaces and underscores, are not
343+
allowed).
344+
Those labels MUST be consistent across subjects and sessions.
345+
type: string
346+
format: label
347+
tracer:
348+
name: Tracer
349+
entity: trc
350+
description: |
351+
The `trc-<label>` key/value can be used to distinguish
352+
sequences using different tracers.
353+
The key `"TracerName"` MUST also be included in the associated JSON file,
354+
although the label may be different.
355+
type: string
356+
format: label

‎heudiconv/bids/data/schema/rules/entities.yaml

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
# This file simply defines the order in which entities should appear within filenames.
3+
# Entity definitions appear in the `objects/entities.yaml` file.
4+
- subject
5+
- session
6+
- sample
7+
- task
8+
- acquisition
9+
- ceagent
10+
- tracer
11+
- stain
12+
- reconstruction
13+
- direction
14+
- run
15+
- modality
16+
- echo
17+
- flip
18+
- inversion
19+
- mtransfer
20+
- part
21+
- processing
22+
- hemisphere
23+
- space
24+
- split
25+
- recording
26+
- chunk
27+
- resolution
28+
- density
29+
- label
30+
- description

‎setup.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,9 @@ def findsome(subdir, extensions):
5959
op.join('data', '*.dcm'),
6060
op.join('data', '*', '*.dcm')
6161
],
62+
'heudiconv.bids.data.schema': [
63+
'*/*.yaml'
64+
],
6265
}
6366
)
6467

0 commit comments

Comments
 (0)