files.yaml

---
# This file describes files which may appear at the top level of a dataset.
# This does not include information about whether these files are required or optional.
# For that information, see `rules/top_level_files.yaml`.
CHANGES:
  display_name: Changelog
  file_type: regular
  description: |
    Version history of the dataset (describing changes, updates and corrections) MAY be provided in
    the form of a `CHANGES` text file.
    This file MUST follow the
    [CPAN Changelog convention](https://metacpan.org/release/HAARG/CPAN-Changes-0.400002/view\
    /lib/CPAN/Changes/Spec.pod).
    The `CHANGES` file MUST be either in ASCII or UTF-8 encoding.
CITATION:
  display_name: CITATION.cff
  file_type: regular
  description: |
    A description of the citation information for the dataset, following the
    [Citation File Format](https://citation-file-format.github.io/) specification.
    This file permits more detailed and structured descriptions than
    [dataset_description.json](SPEC_ROOT/glossary.md#dataset_description-files).
LICENSE:
  display_name: License
  file_type: regular
  description: |
    A `LICENSE` file MAY be provided in addition to the short specification of the
    used license in the `dataset_description.json` `"License"` field.
    The `"License"` field and `LICENSE` file MUST correspond.
    The `LICENSE` file MUST be either in ASCII or UTF-8 encoding.
README:
  display_name: README
  file_type: regular
  description: |
    A REQUIRED text file, `README`, SHOULD describe the dataset in more detail.
    The `README` file MUST be either in ASCII or UTF-8 encoding and MAY have one of the extensions:
    `.md` ([Markdown](https://www.markdownguide.org/)),
    `.rst` ([reStructuredText](https://docutils.sourceforge.io/rst.html)),
    or `.txt`.
    A BIDS dataset MUST NOT contain more than one `README` file (with or without extension)
    at its root directory.
    BIDS does not make any recommendations with regards to the
    [Markdown flavor](https://www.markdownguide.org/extended-syntax/#lightweight-markup-languages)
    and does not validate the syntax of Markdown and reStructuredText.
    The `README` file SHOULD be structured such that its contents can be easily understood
    even if the used format is not rendered.
    A guideline for creating a good `README` file can be found in the
    [bids-starter-kit](https://github.com/bids-standard/bids-starter-kit/tree/main/templates/).
dataset_description:
  display_name: Dataset Description
  file_type: regular
  description: |
    The file `dataset_description.json` is a JSON file describing the dataset.
genetic_info:
  display_name: Genetic Information
  file_type: regular
  description: |
    The `genetic_info.json` file describes the genetic information available in the
    `participants.tsv` file and/or the genetic database described in
    `dataset_description.json`.

    Datasets containing the `Genetics` field in `dataset_description.json` or the
    `genetic_id` column in `participants.tsv` MUST include this file.
participants:
  display_name: Participant Information
  file_type: regular
  description: |
    The purpose of this RECOMMENDED file is to describe properties of participants
    such as age, sex, handedness, species and strain.
    If this file exists, it MUST contain the column `participant_id`,
    which MUST consist of `sub-<label>` values identifying one row for each participant,
    followed by a list of optional columns describing participants.
    Each participant MUST be described by one and only one row.

    Commonly used *optional* columns in `participants.tsv` files are `age`, `sex`,
    `handedness`, `strain`, and `strain_rrid`.

    The RECOMMENDED `species` column SHOULD be a binomial species name from the
    [NCBI Taxonomy](https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi)
    (for examples `homo sapiens`, `mus musculus`, `rattus norvegicus`).
    For backwards compatibility, if `species` is absent, the participant is assumed to be
    `homo sapiens`.
samples:
  display_name: Sample Information
  file_type: regular
  description: |
    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 filename within the dataset.
    Each sample MUST be described by one and only one row.
code:
  display_name: Code
  file_type: directory
  description: |
    A directory in which to store any code
    (for example the one used to generate the derivatives from the raw data).
    See the [Code section](SPEC_ROOT/modality-agnostic-files.md#code)
    for more information.
derivatives:
  display_name: Derivative data
  file_type: directory
  description: |
    Derivative data (for example preprocessed files).
    See the [relevant section](SPEC_ROOT/common-principles.md#source-vs-raw-vs-derived-data)
    for more information.
phenotype:
  display_name: Phenotype
  file_type: directory
  description: |
    A directory where to store participant level measurements (for
    example responses from multiple questionnaires) split into
    individual files separate from `participants.tsv`.
    See the [relevant section](SPEC_ROOT/modality-agnostic-files.md#phenotypic-and-assessment-data)
    for more information.
sourcedata:
  display_name: Source data
  file_type: directory
  description: |
    A directory where to store data before harmonization, reconstruction,
    and/or file format conversion (for example, E-Prime event logs or DICOM files).
    See the [relevant section](SPEC_ROOT/common-principles.md#source-vs-raw-vs-derived-data)
    for more information.
stimuli:
  display_name: Stimulus files
  file_type: directory
  description: |
    A directory to store any stimulus files used during an experiment.
    See the [relevant section](SPEC_ROOT/modality-specific-files/task-events.md#stimuli-directory)
    for more information.