From 21b772582fe412ff3676dd3f32c1b64b9c6a1846 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Tue, 21 Dec 2021 02:04:43 -0800
Subject: [PATCH] [DATALAD RUNCMD] RF: harmonize 'file name' into 'filename'
 (#962)

Text is using both 'file name' and 'filename' pretty much to the equal amount
ATM (see git grep outputs below).  Code uses 'filename', and wikipedia has
https://en.wikipedia.org/wiki/Filename and prefers to use 'filename' in it. So
I decided to harmonize  into  'filename'.

	$> git grep  'file name' | grep '\.md' | grep -v MACRO | nl
		 1	src/02-common-principles.md:1.  **File extension** - a portion of the file name after the left-most
		 2	src/02-common-principles.md:are compulsory. For example a particular file name format is required when
		 3	src/02-common-principles.md:saved under a particular file name specified in the standard. This standard
		 4	src/02-common-principles.md:A file name consists of a chain of *entities*, or key-value pairs, a *suffix* and an
		 5	src/02-common-principles.md:`subject`, the file name MUST begin with the string `sub-<label>_ses-<label>`.
		 6	src/02-common-principles.md:If the `session` level is omitted in the folder structure, the file name MUST begin
		 7	src/02-common-principles.md:key/value pair MUST also be included as part of the file names themselves.
		 8	src/02-common-principles.md:produces a human readable file name, such as `sub-01_task-rest_eeg.edf`.
		 9	src/02-common-principles.md:It is evident from the file name alone that the file contains resting state
		10	src/02-common-principles.md:Entities within a file name MUST be unique.
		11	src/02-common-principles.md:For example, the following file name is not valid because it uses the `acq`
		12	src/02-common-principles.md:label, but must be included in file names (similarly to other key names).
		13	src/02-common-principles.md:meaning of file names and setting requirements on their contents or metadata.
		14	src/02-common-principles.md:to suppress warnings or provide interpretations of your file names.
		15	src/03-modality-agnostic-files.md:This file is REQUIRED if `sample-<label>` is present in any file name within the dataset.
		16	src/04-modality-specific-files/05-task-events.md:Where `<matches>` corresponds to task file name. For example:
		17	src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md:In the template file names, the `<matches>` part corresponds to task file name
		18	src/05-derivatives/02-common-data-types.md:is used to prevent clashing with the original file name.
		19	src/06-longitudinal-and-multi-site-studies.md:and [file names](02-common-principles.md#file-name-structure)
		20	src/99-appendices/03-hed.md:screen or the file name of the stimulus image.
		21	src/99-appendices/03-hed.md:       "LongName": "Stimulus file name",
		22	src/99-appendices/04-entity-table.md:[file name structure](../02-common-principles.md#file-name-structure),
		23	src/99-appendices/06-meg-file-formats.md:that not only the file names, but also the internal file pointers will be
		24	src/99-appendices/09-entities.md:[file name structure](../02-common-principles.md#file-name-structure).
		25	src/CHANGES.md:-   \[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))
		26	src/CHANGES.md:-   \[FIX] Specify marker file names for KIT data (MEG) [#62](https://github.com/bids-standard/bids-specification/pull/62) ([monkeyman192](https://github.com/monkeyman192))
		27	src/CHANGES.md:-   Added missing `sub-<participant_label>` in behavioral data file names.
		28	src/pregh-changes.md:-   Added missing `sub-<participant_label>` in behavioral data file names.

	$> git grep 'filename' | grep '\.md' | grep -v MACRO | nl
		 1	CONTRIBUTING.md:Make sure that all filename format templates, entity tables, and entity definitions are correct
		 2	src/02-common-principles.md:(with the same filename as the `.nii[.gz]` file, but with a `.json` extension).
		 3	src/03-modality-agnostic-files.md:      "filename": ("REQUIRED", "There MUST be exactly one row for each file."),
		 4	src/03-modality-agnostic-files.md:filename	acq_time
		 5	src/04-modality-specific-files/02-magnetoencephalography.md:which saves the MEG sensor coil positions in a separate file with two possible filename extensions  (`.sqd`, `.mrk`).
		 6	src/05-derivatives/01-introduction.md:    status. Any modification of raw files must use a modified filename that does
		 7	src/05-derivatives/01-introduction.md:    not conflict with the raw filename. Further, any files created as part of a
		 8	src/05-derivatives/01-introduction.md:    derivative dataset must not match a permissible filename of a valid raw
		 9	src/05-derivatives/01-introduction.md:    dataset. Stated equivalently, if any filename in a derivative dataset has a
		10	src/05-derivatives/01-introduction.md:-   Each Derivatives filename MUST be of the form:
		11	src/05-derivatives/01-introduction.md:    `source_entities` MUST be the entire source filename, with the omission of
		12	src/05-derivatives/01-introduction.md:    the source suffix and extension. One exception to this rule is filename
		13	src/05-derivatives/01-introduction.md:-   There is no prohibition against identical filenames in different derived
		14	src/05-derivatives/03-imaging.md:filename.
		15	src/99-appendices/04-entity-table.md:specification, and establishes a common order within a filename.
		16	src/99-appendices/08-coordinate-systems.md:The `scanner` coordinate system is implicit and assumed by default if the derivative filename does not define **any** `space-<label>`.
		17	src/99-appendices/11-qmri.md:filenames will remain the same; however, the optional metadata (third column) may
		18	src/CHANGES.md:-   \[SCHEMA] Use macro for filename templates in file collections appendix [#787](https://github.com/bids-standard/bids-specification/pull/787) ([tsalo](https://github.com/tsalo))
		19	src/CHANGES.md:-   \[FIX] Accidentally swapped Neuromag/Elekta/MEGIN cross-talk & fine-calibration filename extensions [#621](https://github.com/bids-standard/bids-specification/pull/621) ([hoechenberger](https://github.com/hoechenberger))
		20	src/CHANGES.md:-   \[INFRA] SCHEMA: Declare entities by concept names, add entity field for filename components [#616](https://github.com/bids-standard/bids-specification/pull/616) ([effigies](https://github.com/effigies))
		21	src/CHANGES.md:-   \[FIX] Common principles: Fix filename in inheritance principle [#261](https://github.com/bids-standard/bids-specification/pull/261) ([Lestropie](https://github.com/Lestropie))
		22	src/CHANGES.md:-   \[FIX] Example for IntendedFor was missing session indicator in the filename [#129](https://github.com/bids-standard/bids-specification/pull/129) ([yarikoptic](https://github.com/yarikoptic))
		23	src/schema/README.md:the entity tables, entity definitions, filename templates, and metadata tables.
		24	src/schema/README.md:-   `entities.yaml`: Entities (key/value pairs in folder and filenames).
		25	src/schema/README.md:This file contains a dictionary in which each entity (key/value pair in filenames) is defined.
		26	src/schema/README.md:they appear in filenames _and_ their full names.
		27	src/schema/README.md:For example, the key for the "Contrast Enhancing Agent" entity, which appears in filenames as `ce-<label>`,
		28	src/schema/README.md:since many entities (such as `ce`) have very short filename elements.
		29	src/schema/README.md:The `entity` field is the entity as it appears in filenames. For example, the `entity` for `ceagent` is `ce`.
		30	src/schema/README.md:Given that all entities appear in filenames, they should all be strings and the `type` field should always be `string`.
		31	src/schema/README.md:For example, `run` should have an index, so a valid key-value pair in a filename would be `run-01`.
		32	src/schema/README.md:Keys are the filenames (without file extensions),
		33	src/schema/README.md:-   `datatypes/*.yaml`: Files in the `datatypes` folder contain information about valid filenames within a given datatype.
		34	src/schema/README.md:    Each dictionary contains a list of suffixes, entities, and file extensions which may constitute a valid BIDS filename.
		35	src/schema/README.md:-   `entities.yaml`: This file simply defines the order in which entities, when present, MUST appear in filenames.
		36	src/schema/README.md:Each dictionary corresponds to a group of suffixes that have the same rules regarding filenames.
		37	src/schema/README.md:**NOTE**: The order in which entities appear in these dictionaries does not reflect how they should appear in filenames.
		38	src/schema/README.md:This file contains a list of entities in the order in which they must appear in filenames.
=== Do not change lines below ===
{
 "chain": [],
 "cmd": "bash -c 'git grep -l '\"'\"'file name'\"'\"' | grep '\"'\"'\\.md'\"'\"' | grep -v MACRO | xargs sed -i -e '\"'\"'s,file name,filename,g'\"'\"''",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^
---
 src/02-common-principles.md                   | 28 +++++++++----------
 src/03-modality-agnostic-files.md             |  2 +-
 .../05-task-events.md                         |  2 +-
 ...logical-and-other-continuous-recordings.md |  2 +-
 src/05-derivatives/02-common-data-types.md    |  2 +-
 src/06-longitudinal-and-multi-site-studies.md |  2 +-
 src/99-appendices/03-hed.md                   |  4 +--
 src/99-appendices/04-entity-table.md          |  2 +-
 src/99-appendices/06-meg-file-formats.md      |  2 +-
 src/99-appendices/09-entities.md              |  2 +-
 src/CHANGES.md                                |  6 ++--
 src/pregh-changes.md                          |  2 +-
 12 files changed, 28 insertions(+), 28 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index e29d0b96ed..337705235c 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -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.
@@ -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
@@ -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
@@ -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`
 
@@ -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
 
@@ -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 -->
 
diff --git a/src/03-modality-agnostic-files.md b/src/03-modality-agnostic-files.md
index 1788f1911f..68bf8550cf 100644
--- a/src/03-modality-agnostic-files.md
+++ b/src/03-modality-agnostic-files.md
@@ -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(
diff --git a/src/04-modality-specific-files/05-task-events.md b/src/04-modality-specific-files/05-task-events.md
index 6fe334e0ff..5188a8c1ae 100644
--- a/src/04-modality-specific-files/05-task-events.md
+++ b/src/04-modality-specific-files/05-task-events.md
@@ -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.
diff --git a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
index ce443f1a07..3bf43c7532 100644
--- a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
+++ b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
@@ -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`.
diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index e03d88ca14..9dbe604706 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -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(
    {
diff --git a/src/06-longitudinal-and-multi-site-studies.md b/src/06-longitudinal-and-multi-site-studies.md
index c617812bc8..568c80c9c7 100644
--- a/src/06-longitudinal-and-multi-site-studies.md
+++ b/src/06-longitudinal-and-multi-site-studies.md
@@ -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).
 
diff --git a/src/99-appendices/03-hed.md b/src/99-appendices/03-hed.md
index 1526c1b036..0466cb7870 100644
--- a/src/99-appendices/03-hed.md
+++ b/src/99-appendices/03-hed.md
@@ -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.
@@ -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/#"
    }
diff --git a/src/99-appendices/04-entity-table.md b/src/99-appendices/04-entity-table.md
index 5dfd86d018..1afd0771a9 100644
--- a/src/99-appendices/04-entity-table.md
+++ b/src/99-appendices/04-entity-table.md
@@ -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).
 
 <!--
diff --git a/src/99-appendices/06-meg-file-formats.md b/src/99-appendices/06-meg-file-formats.md
index 1f5abc039f..7036eb32a0 100644
--- a/src/99-appendices/06-meg-file-formats.md
+++ b/src/99-appendices/06-meg-file-formats.md
@@ -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>`
diff --git a/src/99-appendices/09-entities.md b/src/99-appendices/09-entities.md
index b72e06e9a3..64d9700033 100644
--- a/src/99-appendices/09-entities.md
+++ b/src/99-appendices/09-entities.md
@@ -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).
diff --git a/src/CHANGES.md b/src/CHANGES.md
index 41ad4f92aa..9684d8a8ab 100644
--- a/src/CHANGES.md
+++ b/src/CHANGES.md
@@ -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))
@@ -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)
@@ -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.
diff --git a/src/pregh-changes.md b/src/pregh-changes.md
index 6351057aa6..da91e7f2e5 100644
--- a/src/pregh-changes.md
+++ b/src/pregh-changes.md
@@ -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.