From 61febee53799cfe9fe0d956f6f155bfc6e241d8b Mon Sep 17 00:00:00 2001
From: Marie-Helene Bourget <bourgetmarieh@gmail.com>
Date: Mon, 31 May 2021 17:14:19 -0400
Subject: [PATCH 1/7] Add sample entity to 02-common-principles.md and
 entities.yaml

---
 src/02-common-principles.md |  7 +++++++
 src/schema/entities.yaml    | 11 +++++++++++
 2 files changed, 18 insertions(+)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index f69e448bdc..d08c2608b6 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -32,6 +32,13 @@ misunderstanding we clarify them here.
     context, a session may also indicate a group of related scans,
     taken in one or more visits.
 
+1.  **Sample** - a sample pertaining to a subject such as tissue, primary cell
+    or cell-free sample.
+    The `sample-<label>` key/value pair is used to distinguish between different
+    samples from the same subject.
+    The label MUST be unique per subject and is RECOMMENDED to be unique
+    throughout the dataset.
+
 1.  **Data acquisition** - a continuous uninterrupted block of time during which
     a brain scanning instrument was acquiring data according to particular
     scanning sequence/protocol.
diff --git a/src/schema/entities.yaml b/src/schema/entities.yaml
index 6c7bab8e31..e0035dedd7 100644
--- a/src/schema/entities.yaml
+++ b/src/schema/entities.yaml
@@ -25,6 +25,17 @@ session:
     often in the case of some intervention between sessions
     (for example, training).
   format: label
+sample:
+  name: Sample
+  entity: sample
+  description: |
+    A sample pertaining to a subject such as tissue, primary cell
+    or cell-free sample.
+    The `sample-<label>` key/value pair is used to distinguish between different
+    samples from the same subject.
+    The label MUST be unique per subject and is RECOMMENDED to be unique
+    throughout the dataset.
+  format: label
 task:
   name: Task
   entity: task

From 2d4a92fb719a5a1c1a0ca6a275a0f30f0ca8c46f Mon Sep 17 00:00:00 2001
From: Marie-Helene Bourget <bourgetmarieh@gmail.com>
Date: Fri, 4 Jun 2021 10:13:30 -0400
Subject: [PATCH 2/7] Add samples.tsv file to 03-modality-agnostic-files.md

---
 src/03-modality-agnostic-files.md | 65 +++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/src/03-modality-agnostic-files.md b/src/03-modality-agnostic-files.md
index 2da10f03cd..98cf8c2222 100644
--- a/src/03-modality-agnostic-files.md
+++ b/src/03-modality-agnostic-files.md
@@ -251,6 +251,71 @@ to date of birth.
 }
 ```
 
+## Samples file
+
+Template:
+
+```Text
+samples.tsv
+samples.json
+```
+
+The purpose of this RECOMMENDED file is to describe properties of samples
+when the `sample-<label>` key/value pair is used in filenames.
+If this file exists, it MUST contain the three following columns:
+
+-   `sample_id`: MUST consist of `sample-<label>` values identifying one row
+    for each sample
+
+-   `participant_id`: MUST consist of `sub-<label>`
+
+-   `sample_type`: MUST consist of sample type values (for example: tissue,
+    primary cell or cell-free sample) from [ENCODE Biosample Type](https://www.encodeproject.org/profiles/biosample_type)
+
+Other optional columns MAY be used to describe the samples.
+Each sample MUST be described by one and only one row.
+
+Commonly used *optional* columns in `samples.tsv` files are `pathology` and
+`derived_from`. We RECOMMEND to make use of these columns, and in case that
+you do use them, we RECOMMEND to use the following values for them:
+
+-   `pathology`: string value describing the pathology of the sample or type of control.
+    When different from `healthy`, pathology SHOULD be specified in `samples.tsv`.
+    The pathology MAY instead be specified in [Sessions files](06-longitudinal-and-multi-site-studies.html#sessions-file)
+    in case it changes over time.
+
+-   `derived_from`: `sample-<label>` key/value pair from which a sample is derived from,
+    for example a slice of tissue (`sample-02`) derived from a block of tissue (`sample-01`),
+    as illustrated in the example below.
+
+`samples.tsv` example:
+
+```Text
+sample_id participant_id sample_type derived_from
+sample-01 sub-01 tissue n/a
+sample-02 sub-01 tissue sample-01
+sample-03 sub-01 tissue sample-01
+sample-04 sub-02 tissue n/a
+sample-05 sub-02 tissue n/a
+```
+
+It is RECOMMENDED to accompany each `samples.tsv` file with a sidecar
+`samples.json` file to describe the TSV column names and properties of their values
+(see also the [section on tabular files](02-common-principles.md#tabular-files)).
+
+`samples.json` example:
+
+```JSON
+{
+    "sample_type": {
+        "Description": "type of sample from ENCODE Biosample Type (https://www.encodeproject.org/profiles/biosample_type)",
+    },
+    "derived_from": {
+        "Description": "sample_id from which the sample is derived from",
+    }
+}
+```
+
 ## Phenotypic and assessment data
 
 Template:

From 57bf42f501b57e0b55863d3b926a0feddfeecc46 Mon Sep 17 00:00:00 2001
From: Marie-Helene Bourget <bourgetmarieh@gmail.com>
Date: Fri, 4 Jun 2021 11:58:53 -0400
Subject: [PATCH 3/7] Fix Sessions files link in 03-modality-agnostic-files.md

---
 src/03-modality-agnostic-files.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/03-modality-agnostic-files.md b/src/03-modality-agnostic-files.md
index 98cf8c2222..8e6c973fd5 100644
--- a/src/03-modality-agnostic-files.md
+++ b/src/03-modality-agnostic-files.md
@@ -281,7 +281,7 @@ you do use them, we RECOMMEND to use the following values for them:
 
 -   `pathology`: string value describing the pathology of the sample or type of control.
     When different from `healthy`, pathology SHOULD be specified in `samples.tsv`.
-    The pathology MAY instead be specified in [Sessions files](06-longitudinal-and-multi-site-studies.html#sessions-file)
+    The pathology MAY instead be specified in [Sessions files](06-longitudinal-and-multi-site-studies.md#sessions-file)
     in case it changes over time.
 
 -   `derived_from`: `sample-<label>` key/value pair from which a sample is derived from,

From 0554117ea5a25c8fe873a43e716b234a64dfb1c0 Mon Sep 17 00:00:00 2001
From: Marie-Helene Bourget <bourgetmarieh@gmail.com>
Date: Fri, 4 Jun 2021 12:01:47 -0400
Subject: [PATCH 4/7] Add samples to src/schema/top_level_files.yaml

---
 src/schema/top_level_files.yaml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/schema/top_level_files.yaml b/src/schema/top_level_files.yaml
index 42b402a763..98a74a12b6 100644
--- a/src/schema/top_level_files.yaml
+++ b/src/schema/top_level_files.yaml
@@ -24,3 +24,8 @@ participants:
   extensions:
     - .tsv
     - .json
+samples:
+  required: false
+  extensions:
+    - .tsv
+    - .json

From f331c9fe23dcde923ac817fd53ef285bab290452 Mon Sep 17 00:00:00 2001
From: mariehbourget <54086142+mariehbourget@users.noreply.github.com>
Date: Sun, 20 Jun 2021 19:08:11 -0400
Subject: [PATCH 5/7] Update src/03-modality-agnostic-files.md

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 src/03-modality-agnostic-files.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/03-modality-agnostic-files.md b/src/03-modality-agnostic-files.md
index 8e6c973fd5..b7ef6703de 100644
--- a/src/03-modality-agnostic-files.md
+++ b/src/03-modality-agnostic-files.md
@@ -311,7 +311,7 @@ It is RECOMMENDED to accompany each `samples.tsv` file with a sidecar
         "Description": "type of sample from ENCODE Biosample Type (https://www.encodeproject.org/profiles/biosample_type)",
     },
     "derived_from": {
-        "Description": "sample_id from which the sample is derived from",
+        "Description": "sample_id from which the sample is derived"
     }
 }
 ```

From dea1403634f2bd4526e4b167ed8d7dfcdd385a7a Mon Sep 17 00:00:00 2001
From: mariehbourget <54086142+mariehbourget@users.noreply.github.com>
Date: Wed, 14 Jul 2021 15:18:43 -0400
Subject: [PATCH 6/7] Update src/03-modality-agnostic-files.md

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 src/03-modality-agnostic-files.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/03-modality-agnostic-files.md b/src/03-modality-agnostic-files.md
index b7ef6703de..1a933c0d88 100644
--- a/src/03-modality-agnostic-files.md
+++ b/src/03-modality-agnostic-files.md
@@ -260,8 +260,8 @@ samples.tsv
 samples.json
 ```
 
-The purpose of this RECOMMENDED file is to describe properties of samples
-when the `sample-<label>` key/value pair is used in filenames.
+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.
 If this file exists, it MUST contain the three following columns:
 
 -   `sample_id`: MUST consist of `sample-<label>` values identifying one row

From 20d7081ef99b06eaa8ab93f7d5736e6ad658367b Mon Sep 17 00:00:00 2001
From: Marie-Helene Bourget <bourgetmarieh@gmail.com>
Date: Wed, 14 Jul 2021 16:25:37 -0400
Subject: [PATCH 7/7] Add accepted values to sample_type

---
 src/03-modality-agnostic-files.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/03-modality-agnostic-files.md b/src/03-modality-agnostic-files.md
index 1a933c0d88..1dd15af091 100644
--- a/src/03-modality-agnostic-files.md
+++ b/src/03-modality-agnostic-files.md
@@ -269,8 +269,9 @@ If this file exists, it MUST contain the three following columns:
 
 -   `participant_id`: MUST consist of `sub-<label>`
 
--   `sample_type`: MUST consist of sample type values (for example: tissue,
-    primary cell or cell-free sample) from [ENCODE Biosample Type](https://www.encodeproject.org/profiles/biosample_type)
+-   `sample_type`: MUST consist of sample type values, either `cell line`, `in vitro differentiated cells`,
+    `primary cell`, `cell-free sample`, `cloning host`, `tissue`, `whole organisms`, `organoid` or
+    `technical sample` from [ENCODE Biosample Type](https://www.encodeproject.org/profiles/biosample_type)
 
 Other optional columns MAY be used to describe the samples.
 Each sample MUST be described by one and only one row.