Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[FIX] harmonize 'file name' into 'filename' #962

Merged
merged 1 commit into from
Dec 21, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions src/02-common-principles.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ misunderstanding we clarify them here.
the final `_`), right before the **File extension**, for example, it is `eeg` in
`sub-05_task-matchingpennies_eeg.vhdr`.

1. **File extension** - a portion of the file name after the left-most
1. **File extension** - a portion of the filename after the left-most
period (`.`) preceded by any other alphanumeric. For example, `.gitignore` does
not have a file extension, but the file extension of `test.nii.gz` is `.nii.gz`.
Note that the left-most period is included in the file extension.
Expand All @@ -133,10 +133,10 @@ misunderstanding we clarify them here.

The following standard describes a way of arranging data and writing down
metadata for a subset of neuroimaging experiments. Some aspects of the standard
are compulsory. For example a particular file name format is required when
are compulsory. For example a particular filename format is required when
storing structural scans. Some aspects are regulated but optional. For example a
T2 volume does not need to be included, but when it is available it should be
saved under a particular file name specified in the standard. This standard
saved under a particular filename specified in the standard. This standard
aspires to describe a majority of datasets, but acknowledges that there will be
cases that do not fit. In such cases one can include additional files and
subfolders to the existing folder structure following common sense. For example
Expand All @@ -149,13 +149,13 @@ specification.

## File name structure

A file name consists of a chain of *entities*, or key-value pairs, a *suffix* and an
A filename consists of a chain of *entities*, or key-value pairs, a *suffix* and an
*extension*.
Two prominent examples of entities are `subject` and `session`.

For a data file that was collected in a given `session` from a given
`subject`, the file name MUST begin with the string `sub-<label>_ses-<label>`.
If the `session` level is omitted in the folder structure, the file name MUST begin
`subject`, the filename MUST begin with the string `sub-<label>_ses-<label>`.
If the `session` level is omitted in the folder structure, the filename MUST begin
with the string `sub-<label>`, without `ses-<label>`.

Note that `sub-<label>` corresponds to the `subject` entity because it has
Expand All @@ -169,19 +169,19 @@ be added for all subjects if at least one subject in the dataset has more than
one session.
If a `/ses-<label>` subfolder is included as part of the directory hierarchy,
then the same [`ses-<label>`](./99-appendices/09-entities.md#ses)
key/value pair MUST also be included as part of the file names themselves.
key/value pair MUST also be included as part of the filenames themselves.
Acquisition time of session can
be defined in the [sessions file](03-modality-agnostic-files.md#sessions-file).

A chain of entities, followed by a suffix, connected by underscores (`_`)
produces a human readable file name, such as `sub-01_task-rest_eeg.edf`.
It is evident from the file name alone that the file contains resting state
produces a human readable filename, such as `sub-01_task-rest_eeg.edf`.
It is evident from the filename alone that the file contains resting state
data from subject `01`.
The suffix `eeg` and the extension `.edf` depend on the imaging modality and
the data format and indicate further details of the file's contents.

Entities within a file name MUST be unique.
For example, the following file name is not valid because it uses the `acq`
Entities within a filename MUST be unique.
For example, the following filename is not valid because it uses the `acq`
entity twice:
`sub-01_acq-laser_acq-uneven_electrodes.tsv`

Expand Down Expand Up @@ -658,7 +658,7 @@ of `<index>`es.
Please note that a given label or index is distinct from the "prefix"
it refers to. For example `sub-01` refers to the `sub` entity (a
subject) with the label `01`. The `sub-` prefix is not part of the subject
label, but must be included in file names (similarly to other key names).
label, but must be included in filenames (similarly to other key names).

## Uniform Resource Indicator

Expand Down Expand Up @@ -816,10 +816,10 @@ For example, an ASSET calibration scan might be named

Non-standard files and directories should be named with care.
Future BIDS efforts may standardize new entities and suffixes, changing the
meaning of file names and setting requirements on their contents or metadata.
meaning of filenames and setting requirements on their contents or metadata.
Validation and parsing tools MAY treat the presence of non-standard files and
directories as an error, so consult the details of these tools for mechanisms
to suppress warnings or provide interpretations of your file names.
to suppress warnings or provide interpretations of your filenames.

<!-- Link Definitions -->

Expand Down
2 changes: 1 addition & 1 deletion src/03-modality-agnostic-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -259,7 +259,7 @@ samples.json
```

The purpose of this file is to describe properties of samples, indicated by the `sample` entity.
This file is REQUIRED if `sample-<label>` is present in any file name within the dataset.
This file is REQUIRED if `sample-<label>` is present in any filename within the dataset.
Each sample MUST be described by one and only one row.

{{ MACROS___make_columns_table(
Expand Down
2 changes: 1 addition & 1 deletion src/04-modality-specific-files/05-task-events.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ sub-<label>/[ses-<label>]
<matches>_events.json
```

Where `<matches>` corresponds to task file name. For example:
Where `<matches>` corresponds to task filename. For example:
`sub-control01_task-nback`.

Each task events file REQUIRES a corresponding task data file.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ For the template directory name, `<datatype>` can correspond to any data
recording modality, for example `func`, `anat`, `dwi`, `meg`, `eeg`, `ieeg`,
or `beh`.

In the template file names, the `<matches>` part corresponds to task file name
In the template filenames, the `<matches>` part corresponds to task filename
before the suffix.
For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`,
`<matches>` would correspond to `sub-control01_task-nback_run-1`.
Expand Down
2 changes: 1 addition & 1 deletion src/05-derivatives/02-common-data-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ share the following (non-required) ones:
Preprocessed `bold` NIfTI file in the original coordinate space of the original run.
The location of the file in the original datasets is encoded in the `RawSources` metadata,
and [`_desc-<label>`](../99-appendices/09-entities.md#desc)
is used to prevent clashing with the original file name.
is used to prevent clashing with the original filename.

{{ MACROS___make_filetree_example(
{
Expand Down
2 changes: 1 addition & 1 deletion src/06-longitudinal-and-multi-site-studies.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Longitudinal and multi-site studies

Multiple sessions (visits) are encoded by adding an extra layer of directories
and [file names](02-common-principles.md#file-name-structure)
and [filenames](02-common-principles.md#file-name-structure)
in the form of a session (for example `ses-<label>`) and
with a [`*_sessions.tsv` file](03-modality-agnostic-files.md#sessions-file).

Expand Down
4 changes: 2 additions & 2 deletions src/99-appendices/03-hed.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ Example: An accompanying `*_events.json` sidecar describing the `mycodes` catego

Each column of `*_events.tsv` containing non-categorical values usually represents a
particular type of data, for example the `speed` of a stimulus object across the
screen or the file name of the stimulus image.
screen or the filename of the stimulus image.
These variables could be annotated in the HED column of `*_events.tsv`.
However, that approach requires repeating the values appearing in the individual
columns in the HED column.
Expand Down Expand Up @@ -155,7 +155,7 @@ Example: An accompanying `*_events.json` sidecar describing both categorical and
"HED": "Attribute/Response start delay/# ms, Action/Button press"
},
"stim_file": {
"LongName": "Stimulus file name",
"LongName": "Stimulus filename",
"Description": "Relative path of the stimulus image file",
"HED": "Attribute/File/#"
}
Expand Down
2 changes: 1 addition & 1 deletion src/99-appendices/04-entity-table.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Entity formats indicate whether the value is alphanumeric
(`<label>`) or numeric (`<index>`).

A general introduction to entities is given in the section on
[file name structure](../02-common-principles.md#file-name-structure),
[filename structure](../02-common-principles.md#file-name-structure),
while entity definitions are in [Appendix IX](09-entities.md).

<!--
Expand Down
2 changes: 1 addition & 1 deletion src/99-appendices/06-meg-file-formats.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,7 @@ Each of these files has an internal pointer to the next file.
This is important when renaming these split recordings to the BIDS convention.
Instead of a simple renaming, files should be read in and saved under their new
names with dedicated tools like [MNE](https://mne.tools), which will ensure
that not only the file names, but also the internal file pointers will be
that not only the filenames, but also the internal file pointers will be
updated.

It is RECOMMENDED that FIFF files with multiple parts use the `split-<index>`
Expand Down
2 changes: 1 addition & 1 deletion src/99-appendices/09-entities.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ This section compiles the entities (key-value pairs) described throughout this
specification, and describes each.

A general introduction to entities is given in the section on
[file name structure](../02-common-principles.md#file-name-structure).
[filename structure](../02-common-principles.md#file-name-structure).

The ordering of entities, and whether each is OPTIONAL, REQUIRED, or MUST NOT
be specified for a given file type, is specified in the [Entity Table](04-entity-table.md).
Expand Down
6 changes: 3 additions & 3 deletions src/CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@
- \[FIX] clarify that \<physio|stim>.json is REQUIRED [#542](https://github.com/bids-standard/bids-specification/pull/542) ([sappelhoff](https://github.com/sappelhoff))
- \[FIX] Replace all non-breaking spaces with vanilla spaces [#536](https://github.com/bids-standard/bids-specification/pull/536) ([nicholst](https://github.com/nicholst))
- \[FIX] Clarify indices are nonnegative integers. [#535](https://github.com/bids-standard/bids-specification/pull/535) ([nicholst](https://github.com/nicholst))
- \[FIX] Clarify use of session entity in file names [#532](https://github.com/bids-standard/bids-specification/pull/532) ([Moo-Marc](https://github.com/Moo-Marc))
- \[FIX] Clarify use of session entity in filenames [#532](https://github.com/bids-standard/bids-specification/pull/532) ([Moo-Marc](https://github.com/Moo-Marc))
- \[ENH] Add the ability of users to specify an explicit HED.xml schema for validation. [#527](https://github.com/bids-standard/bids-specification/pull/527) ([VisLab](https://github.com/VisLab))
- \[FIX] clarify that scans.json is allowed and recommended [#523](https://github.com/bids-standard/bids-specification/pull/523) ([sappelhoff](https://github.com/sappelhoff))
- \[INFRA] add copyright holder to license. [#521](https://github.com/bids-standard/bids-specification/pull/521) ([sappelhoff](https://github.com/sappelhoff))
Expand Down Expand Up @@ -342,7 +342,7 @@
- \[FIX] Clarify continuous recording metadata fields [#167](https://github.com/bids-standard/bids-specification/pull/167) ([effigies](https://github.com/effigies))
- \[FIX] changed reference of `dcm2nii` to `dcm2niix` [#166](https://github.com/bids-standard/bids-specification/pull/166) ([DimitriPapadopoulos](https://github.com/DimitriPapadopoulos))
- \[FIX] Removing a leftover file [#162](https://github.com/bids-standard/bids-specification/pull/162) ([chrisgorgo](https://github.com/chrisgorgo))
- \[FIX] Specify marker file names for KIT data (MEG) [#62](https://github.com/bids-standard/bids-specification/pull/62) ([monkeyman192](https://github.com/monkeyman192))
- \[FIX] Specify marker filenames for KIT data (MEG) [#62](https://github.com/bids-standard/bids-specification/pull/62) ([monkeyman192](https://github.com/monkeyman192))
- \[FIX] Remove father-level for meg filetypes other than BTi/4D data [#19](https://github.com/bids-standard/bids-specification/pull/19) ([teonbrooks](https://github.com/teonbrooks))

## [v1.2.0](https://github.com/bids-standard/bids-specification/tree/v1.2.0) (2019-03-04)
Expand Down Expand Up @@ -461,7 +461,7 @@
- Added `InversionTime` metadata key.
- Clarification on the source vs raw language.
- Added `trial_type` column to the event files.
- Added missing `sub-<participant_label>` in behavioral data file names.
- Added missing `sub-<participant_label>` in behavioral data filenames.
- Added ability to store stimuli files.
- Clarified the language describing allowed subject labels.
- Added quantitative proton density maps.
Expand Down
2 changes: 1 addition & 1 deletion src/pregh-changes.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@
- Added `InversionTime` metadata key.
- Clarification on the source vs raw language.
- Added `trial_type` column to the event files.
- Added missing `sub-<participant_label>` in behavioral data file names.
- Added missing `sub-<participant_label>` in behavioral data filenames.
- Added ability to store stimuli files.
- Clarified the language describing allowed subject labels.
- Added quantitative proton density maps.
Expand Down