docs: improve docstring (#1748)

* docs: improve docstring

* docs: update specimen ID

* docs: clarify suffix

* docs: better writing

* update docs

* fix: bad merge

* update docs

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: dbirman

docs/source/acquisition.md

@@ -78,7 +78,7 @@ while the StimulusEpoch represents all stimuli being presented.
 | Field | Type | Title (Description) |
 |-------|------|-------------|
 | `subject_id` | `str` | Subject ID (Unique identifier for the subject) |
-| `specimen_id` | `str or List[str] or NoneType` | Specimen ID (Specimen ID(s) used in this acquisition. Required for in vitro imaging modalities.) |
+| `specimen_id` | `str or List[str] or NoneType` | Specimen ID (Required for in vitro modalities. Standard format is {subject_id} with a _### suffix, as needed) |
 | `acquisition_start_time` | `datetime (timezone-aware)` | Acquisition start time (During validation, timezone information will be moved into the acquisition_start_tz field.) |
 | `acquisition_start_tz` | `int or pydantic_extra_types.timezone_name.TimeZoneName or NoneType` | Acquisition start timezone (Automatically populated by a validator based on acquisition_start_time. Will be a TimeZoneName (IANA name) when the datetime uses a ZoneInfo timezone, or an integer UTC offset in hours for fixed-offset timezones. Use ZoneInfo (from the zoneinfo standard library) to preserve the named timezone.) |
 | `acquisition_end_time` | `datetime (timezone-aware)` | Acquisition end time  |

docs/source/aind_data_schema_models/harp_types.md

@@ -10,10 +10,12 @@ Harp device types
 |------|------|------|
 | `ANALOGINPUT` | `AnalogInput` | `1236` |
 | `ARCHIMEDES` | `Archimedes` | `1136` |
+| `AUDIOSWITCH` | `AudioSwitch` | `1248` |
 | `BEHAVIOR` | `Behavior` | `1216` |
 | `CAMERACONTROLLER` | `CameraController` | `1168` |
 | `CAMERACONTROLLERGEN2` | `CameraControllerGen2` | `1170` |
 | `CLOCKSYNCHRONIZER` | `ClockSynchronizer` | `1152` |
+| `CURRENTDRIVER` | `CurrentDriver` | `1282` |
 | `CUTTLEFISH` | `cuTTLefish` | `1403` |
 | `CUTTLEFISHFIP` | `cuTTLefishFip` | `1407` |
 | `DRIVER12VOLTS` | `Driver12Volts` | `1072` |
@@ -22,6 +24,7 @@ Harp device types
 | `HOBGOBLIN` | `Hobgoblin` | `123` |
 | `IBL_BEHAVIOR_CONTROL` | `Ibl_behavior_control` | `2080` |
 | `INPUTEXPANDER` | `InputExpander` | `1106` |
+| `LASERDRIVERCONTROLLER` | `LaserDriverController` | `1298` |
 | `LEDCONTROLLER` | `LedController` | `1088` |
 | `LICKETYSPLIT` | `LicketySplit` | `1400` |
 | `LOADCELLS` | `LoadCells` | `1232` |
@@ -33,7 +36,7 @@ Harp device types
 | `POKE` | `Poke` | `1024` |
 | `PYCONTROLADAPTER` | `PyControlAdapter` | `1184` |
 | `RFIDREADER` | `RfidReader` | `2094` |
-| `RGBARRAY` | `RgbArray` | `1248` |
+| `RGBARRAY` | `RgbArray` | `1264` |
 | `SIMPLEANALOGGENERATOR` | `SimpleAnalogGenerator` | `1121` |
 | `SNIFFDETECTOR` | `SniffDetector` | `1401` |
 | `SOUNDCARD` | `SoundCard` | `1280` |

docs/source/components/specimen_procedures.md

@@ -41,7 +41,7 @@ Description of a single planar section of brain tissue
 | `thickness` | `Optional[float]` | Slice thickness  |
 | `thickness_unit` | Optional[[SizeUnit](../aind_data_schema_models/units.md#sizeunit)] | Slice thickness unit  |
 | `partial_slice` | Optional[List[[AnatomicalRelative](../aind_data_schema_models/coordinates.md#anatomicalrelative)]] | Partial slice (If sectioning does not include the entire slice, indicate which part of the slice is retained.) |
-| `output_specimen_id` | `str` | Specimen ID  |
+| `output_specimen_id` | `str` | Specimen ID (Output IDs should generally follow the format {input_specimen_id}_###) |
 | `targeted_structure` | Optional[[BrainAtlas](../aind_data_schema_models/brain_atlas.md#ccfv3)] | Targeted structure  |
 | `includes_surrounding_tissue` | `Optional[bool]` | Includes surrounding tissue (Whether the section includes additional tissue surrounding the targeted structure.) |
 
@@ -63,7 +63,7 @@ Description of a single section of brain tissue. Slices should use PlanarSection
 
 | Field | Type | Title (Description) |
 |-------|------|-------------|
-| `output_specimen_id` | `str` | Specimen ID  |
+| `output_specimen_id` | `str` | Specimen ID (Output IDs should generally follow the format {input_specimen_id}_###) |
 | `targeted_structure` | Optional[[BrainAtlas](../aind_data_schema_models/brain_atlas.md#ccfv3)] | Targeted structure  |
 | `includes_surrounding_tissue` | `Optional[bool]` | Includes surrounding tissue (Whether the section includes additional tissue surrounding the targeted structure.) |
 | <del>`coordinate_system_name`</del> | `Optional[str]` | **[DEPRECATED]** Use PlanarSection instead. Coordinate system name  |

docs/source/components/surgery_procedures.md

@@ -147,7 +147,7 @@ Description of a perfusion procedure that creates a specimen
 | Field | Type | Title (Description) |
 |-------|------|-------------|
 | `protocol_id` | `Optional[str]` | Protocol ID (DOI for protocols.io) |
-| `output_specimen_ids` | `List[str]` | Specimen ID (IDs of specimens resulting from this procedure.) |
+| `output_specimen_ids` | `List[str]` | Specimen ID (IDs of specimens resulting from this procedure. Whole brains can use the {subject_id}, partial sections should always include a suffix {subject_id}_###) |
 
 
 ### ProbeImplant

examples/processing.py

@@ -1,4 +1,4 @@
-""" example processing """
+"""example processing"""
 
 import argparse
 from datetime import datetime, timezone

src/aind_data_schema/components/specimen_procedures.py

@@ -28,7 +28,9 @@ class SectionOrientation(str, Enum):
 class Section(DataModel):
     """Description of a single section of brain tissue. Slices should use PlanarSection."""
 
-    output_specimen_id: str = Field(..., title="Specimen ID")
+    output_specimen_id: str = Field(
+        ..., title="Specimen ID", description="Output IDs should generally follow the format {input_specimen_id}_###"
+    )
     targeted_structure: Optional[BrainStructureModel] = Field(default=None, title="Targeted structure")
     includes_surrounding_tissue: Optional[bool] = Field(
         default=None,

src/aind_data_schema/components/surgery_procedures.py

@@ -221,7 +221,10 @@ class Perfusion(DataModel):
     output_specimen_ids: List[str] = Field(
         ...,
         title="Specimen ID",
-        description="IDs of specimens resulting from this procedure.",
+        description=(
+            "IDs of specimens resulting from this procedure."
+            " Whole brains can use the {subject_id}, partial sections should always include a suffix {subject_id}_###"
+        ),
     )
 
     @field_validator("output_specimen_ids", mode="before")

src/aind_data_schema/core/acquisition.py

@@ -362,7 +362,7 @@ class Acquisition(DataCoreModel):
     specimen_id: Optional[Union[str, List[str]]] = Field(
         default=None,
         title="Specimen ID",
-        description="Specimen ID(s) used in this acquisition. Required for in vitro imaging modalities.",
+        description="Required for in vitro modalities. Standard format is {subject_id} with a _### suffix, as needed",
     )
 
     # Acquisition metadata