From 4d25a0a7f7e9626c07025c75533f1a18199a261c Mon Sep 17 00:00:00 2001
From: Ben Dichter <ben.dichter@gmail.com>
Date: Wed, 29 Jul 2026 12:11:13 -0400
Subject: [PATCH] enh: Require the sample entity for icephys and enforce
 samples.tsv

Introduce the sample-<label> entity in a dedicated section of the
microelectrode electrophysiology page rather than defining it in passing in
the Photos section, and record the requirement levels agreed by the working
group: REQUIRED for icephys, including the single-sample and in vivo cases,
and OPTIONAL for ecephys.

Split the microephys file rule so that icephys requires the entity while
ecephys keeps it optional.

Add a check requiring samples.tsv whenever the sample entity is present in a
filename. The specification already states this requirement in the
description of the samples file, but the only check enforcing it was keyed on
the micr modality, so it never fired for microephys data.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../microelectrode-electrophysiology.md       | 33 ++++++++++++++++++-
 src/schema/rules/checks/dataset.yaml          | 16 +++++++++
 src/schema/rules/files/raw/microephys.yaml    | 14 ++++++--
 3 files changed, 60 insertions(+), 3 deletions(-)

diff --git a/src/modality-specific-files/microelectrode-electrophysiology.md b/src/modality-specific-files/microelectrode-electrophysiology.md
index a057c69911..2c7599ee35 100644
--- a/src/modality-specific-files/microelectrode-electrophysiology.md
+++ b/src/modality-specific-files/microelectrode-electrophysiology.md
@@ -37,6 +37,37 @@ and analysis pipelines. The terms are established and used in [Neurodata Without
 Both datatypes share a unified BIDS structure (probes, electrodes, channels) with technique-specific optional metadata fields.
 Files are organized into `ecephys/` or `icephys/` subdirectories with corresponding file suffixes.
 
+## Samples and the `sample-<label>` Entity
+
+The [`sample-<label>`](../appendices/entities.md#sample) entity identifies the biological sample
+from which a recording was made, and 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.
+
+The entity is REQUIRED for `icephys` data and OPTIONAL for `ecephys` data.
+Intracellular recordings are always made from a discrete sample, so the entity is required even when a subject
+yields only a single sample, and even when the recording is made in vivo,
+because the patched cell is itself the sample.
+Requiring the entity in the single-sample case avoids having to rename files if a second sample is added later.
+Extracellular recordings are frequently made in vivo without an identifiable sample,
+so the entity is optional, but it SHOULD be used when the recording is made from a sample
+such as an acute slice or a cultured cell population.
+
+A sample corresponds to the finest granularity of biological material from which signals are measured.
+For patch clamp recordings this is the individual cell (for example, `sample-cell001`),
+and for in vitro extracellular recordings it is typically the slice or the cell population.
+
+Where several samples are obtained from a common source, for example several cells patched
+from one slice, the source MAY also be described as a sample in `samples.tsv` and linked
+to the samples derived from it using the `derived_from` column.
+Such a parent sample generally does not appear as a `sample-<label>` entity in recording filenames,
+since it is not itself what was measured.
+
+Whenever the `sample-<label>` entity is present in a filename, the dataset MUST include a
+[`samples.tsv` file](../modality-agnostic-files/data-summary-files.md#samples-file) describing each sample.
+This applies to both `icephys` and `ecephys` data.
+See the [Intracellular Electrophysiology example](#intracellular-electrophysiology-patch) below
+for a dataset organized this way.
+
 ## Primary Data File Formats
 
 Microelectrode electrophysiology data (of `icephys` or `ecephys` datatypes) MUST be stored in an [open file format](https://en.wikipedia.org/wiki/Open_format),
@@ -574,7 +605,7 @@ with:
 
 The [`ses-<label>`](../appendices/entities.md#ses) entity may be used to specify when the photo was taken.
 
-The [`sample-<label>`](../appendices/entities.md#sample) entity may be used to specify the tissue sample for histological photos.
+The [`sample-<label>`](#samples-and-the-sample-label-entity) entity may be used to specify the tissue sample for histological photos.
 
 The [`space-<label>`](../appendices/entities.md#space) entity may be used to specify the coordinate system for atlas overlay photos.
 
diff --git a/src/schema/rules/checks/dataset.yaml b/src/schema/rules/checks/dataset.yaml
index a1b3cd7387..d843b2bb1b 100644
--- a/src/schema/rules/checks/dataset.yaml
+++ b/src/schema/rules/checks/dataset.yaml
@@ -72,6 +72,22 @@ SamplesTSVMissing:
   checks:
     - exists('samples.tsv', 'dataset')
 
+# samples.tsv is required whenever the sample entity is used, not only for
+# microscopy. See the description of the samples file in objects/files.yaml.
+SamplesTSVMissingForSampleEntity:
+  issue:
+    code: SAMPLES_TSV_MISSING
+    message: |
+      The compulsory file '/samples.tsv' is missing.
+      This file is REQUIRED if the `sample-<label>` entity is present in any
+      filename within the dataset.
+      See 'Modality agnostic files' section of the BIDS specification.
+    level: error
+  selectors:
+    - '"sample" in entities'
+  checks:
+    - exists('samples.tsv', 'dataset')
+
 UnknownVersion:
   issue:
     code: UNKNOWN_BIDS_VERSION
diff --git a/src/schema/rules/files/raw/microephys.yaml b/src/schema/rules/files/raw/microephys.yaml
index 643bbc0a33..873d4f6ff7 100644
--- a/src/schema/rules/files/raw/microephys.yaml
+++ b/src/schema/rules/files/raw/microephys.yaml
@@ -2,7 +2,6 @@
 microephys:
   suffixes:
     - ecephys
-    - icephys
   extensions:
     - .nwb
     # possible future: serialization in .zarr format to accompany .ome.zarr
@@ -11,7 +10,6 @@ microephys:
     - .json
   datatypes:
     - ecephys
-    - icephys
   entities:
     subject: required
     session: optional
@@ -20,6 +18,18 @@ microephys:
     acquisition: optional
     run: optional
 
+# Intracellular recordings are always made from a discrete sample, typically a
+# single cell, so the sample entity is required, as it is for microscopy.
+microephys__icephys:
+  $ref: rules.files.raw.microephys.microephys
+  suffixes:
+    - icephys
+  datatypes:
+    - icephys
+  entities:
+    $ref: rules.files.raw.microephys.microephys.entities
+    sample: required
+
 probes:
   suffixes:
     - probes