refactor!: CoordinateSystem.NotApplicable

docs/source/acquisition.md

@@ -87,7 +87,7 @@ while the StimulusEpoch represents all stimuli being presented.
 | `instrument_name` | `Optional[str]` | Instrument name (Should match the Instrument.instrument_name. Required when instrument metadata is available.) |
 | `acquisition_type` | `str` | Acquisition type (Descriptive string detailing the type of acquisition, should be consistent across similar acquisitions for the same experiment.) |
 | `notes` | `Optional[str]` | Notes  |
-| `global_coordinate_system` | Optional[[CoordinateSystem](components/coordinates.md#coordinatesystem)] | Global coordinate system (Origin and axis definitions for determining the configured position of devices during acquisition. Required when coordinates are provided within the Acquisition) |
+| `global_coordinate_system` | [CoordinateSystem](components/coordinates.md#coordinatesystem) or "Not applicable" or NoneType | Global coordinate system (Origin and axis definitions for determining the configured position of devices during acquisition. Required when coordinates are provided within the Acquisition. Use 'Not applicable' when no global coordinate system applies.) |
 | `calibrations` | List[[Calibration](components/measurements.md#calibration) or [VolumeCalibration](components/measurements.md#volumecalibration) or [PowerCalibration](components/measurements.md#powercalibration)] | Calibrations (List of calibration measurements taken prior to acquisition.) |
 | `maintenance` | List[[Maintenance](components/measurements.md#maintenance)] | Maintenance (List of maintenance on instrument prior to acquisition.) |
 | `data_streams` | List[[DataStream](acquisition.md#datastream) or [ExternalDataStream](acquisition.md#externaldatastream)] | Data streams (A data stream is a collection of devices that are acquiring data simultaneously. Each acquisition can include multiple streams. Streams should be split when configurations are changed. Use ExternalDataStream for acquisitions where instrument metadata is unavailable.) |

docs/source/components/specimen_procedures.md

@@ -52,7 +52,7 @@ Description of a sectioning procedure performed on the coronal, sagittal, or tra
 
 | Field | Type | Title (Description) |
 |-------|------|-------------|
-| `global_coordinate_system` | [CoordinateSystem](coordinates.md#coordinatesystem) or [Atlas](coordinates.md#atlas) or NoneType | Sectioning global coordinate system (Only required if different from the Procedures.global_coordinate_system) |
+| `global_coordinate_system` | [CoordinateSystem](coordinates.md#coordinatesystem) or "Not applicable" or [Atlas](coordinates.md#atlas) or NoneType | Sectioning global coordinate system (Only required if different from the Procedures.global_coordinate_system. Use 'Not applicable' to explicitly disable the inherited global frame.) |
 | `sections` | List[[Section](#section) or [PlanarSection](#planarsection)] | Planar sections (Use PlanarSection for new implementations) |
 | `section_orientation` | [SectionOrientation](#sectionorientation) | Sectioning orientation  |
 

docs/source/components/subject_procedures.md

@@ -61,7 +61,7 @@ Description of subject procedures performed at one time
 | `weight_unit` | [MassUnit](../biodata_models/units.md#massunit) | Weight unit  |
 | `anaesthesia` | Optional[[Anaesthetic](surgery_procedures.md#anaesthetic)] | Anaesthesia  |
 | `workstation_id` | `Optional[str]` | Workstation ID  |
-| `global_coordinate_system` | Optional[[CoordinateSystem](coordinates.md#coordinatesystem)] | Surgery global coordinate system (Only required when the Surgery.global_coordinate_system is different from the Procedures.global_coordinate_system) |
+| `global_coordinate_system` | [CoordinateSystem](coordinates.md#coordinatesystem) or "Not applicable" or NoneType | Surgery global coordinate system (Only required when the Surgery.global_coordinate_system is different from the Procedures.global_coordinate_system. Use 'Not applicable' to explicitly disable the inherited global frame.) |
 | `measured_coordinates` | Optional[Dict[[Origin](../biodata_models/coordinates.md#origin), [Translation](coordinates.md#translation)]] | Measured coordinates (Coordinates measured during the procedure, for example Bregma and Lambda) |
 | `procedures` | List[[CatheterImplant](surgery_procedures.md#catheterimplant) or [Craniotomy](surgery_procedures.md#craniotomy) or [DeviceImplant](surgery_procedures.md#deviceimplant) or [ProbeImplant](surgery_procedures.md#probeimplant) or [Headframe](surgery_procedures.md#headframe) or [BrainInjection](surgery_procedures.md#braininjection) or [Injection](injection_procedures.md#injection) or [MyomatrixInsertion](surgery_procedures.md#myomatrixinsertion) or [GenericSurgeryProcedure](surgery_procedures.md#genericsurgeryprocedure) or [Perfusion](surgery_procedures.md#perfusion) or [SampleCollection](surgery_procedures.md#samplecollection)] | Procedures  |
 | `notes` | `Optional[str]` | Notes  |

docs/source/coordinate_systems.md

@@ -26,6 +26,20 @@ CoordinateSystem(
 )
 ```
 
+### Not Applicable
+
+When no global coordinate system applies, set `global_coordinate_system=CoordinateSystem.NotApplicable`. Note that this is different from using `global_coordinate_system=None` which will inherit from any parent coordinate systems. `"Not applicable"` should be used in situations where no transforms are present in an object.
+
+```{code} python
+from biodata_schema.components.coordinates import CoordinateSystem
+from biodata_schema.core.procedures import Procedures
+
+procedures = Procedures(
+  subject_name="12345",
+  global_coordinate_system=CoordinateSystem.NotApplicable,
+)
+```
+
 ### Origin
 
 An [Origin](biodata_models/coordinates.md#origin) is a point in space, often relative to the mouse's anatomy but it can also be a point on a device. The Origin defines the (0, 0, 0) coordinate in a coordinate system. Standard anatomical references are positions like Bregma or Lambda

docs/source/instrument.md

@@ -60,7 +60,7 @@ Description of an instrument
 | `modification_date` | `datetime.date` | Date of modification (Date of the last change to the instrument, hardware addition/removal, calibration, etc.) |
 | `modalities` | List[[Modality](biodata_models/modalities.md#modality)] | Modalities (List of all possible modalities that the instrument is capable of acquiring) |
 | `calibrations` | Optional[List[[Calibration](components/measurements.md#calibration) or [VolumeCalibration](components/measurements.md#volumecalibration) or [PowerCalibration](components/measurements.md#powercalibration)]] | Calibrations (List of calibration measurements takend during instrument setup and maintenance) |
-| `global_coordinate_system` | [CoordinateSystem](components/coordinates.md#coordinatesystem) | Global coordinate system (Origin and axis definitions for determining the position of the instrument's components) |
+| `global_coordinate_system` | [CoordinateSystem](components/coordinates.md#coordinatesystem) or "Not applicable" | Global coordinate system (Origin and axis definitions for determining the position of the instrument's components. Use 'Not applicable' when no global coordinate system applies.) |
 | `temperature_control` | `Optional[bool]` | Temperature control (Does the instrument maintain a constant temperature?) |
 | `notes` | `Optional[str]` | Notes  |
 | `connections` | List[[Connection](components/connections.md#connection)] | Connections (List of all connections between devices in the instrument) |

docs/source/procedures.md

@@ -29,5 +29,5 @@ Description of all procedures performed on a subject, including surgeries, injec
 | `subject_name` | `str` | Subject name (Unique name for the subject of data acquisition) |
 | `subject_procedures` | List[[Surgery](components/subject_procedures.md#surgery) or [NonSurgicalInjection](components/subject_procedures.md#nonsurgicalinjection) or [TrainingProtocol](components/subject_procedures.md#trainingprotocol) or [WaterRestriction](components/subject_procedures.md#waterrestriction) or [GenericSubjectProcedure](components/subject_procedures.md#genericsubjectprocedure)] | Subject Procedures (Procedures performed on a live subject) |
 | `specimen_procedures` | List[[SpecimenProcedure](components/specimen_procedures.md#specimenprocedure)] | Specimen Procedures (Procedures performed on tissue extracted after perfusion) |
-| `global_coordinate_system` | Optional[[CoordinateSystem](components/coordinates.md#coordinatesystem)] | Global Coordinate System (Origin and axis definitions for determining the configured position of devices implanted during procedures. Required when coordinates are provided within the Procedures) |
+| `global_coordinate_system` | [CoordinateSystem](components/coordinates.md#coordinatesystem) or "Not applicable" or NoneType | Global Coordinate System (Origin and axis definitions for determining the configured position of devices implanted during procedures. Required when coordinates are provided within the Procedures. Use 'Not applicable' when no global coordinate system applies.) |
 | `notes` | `Optional[str]` | Notes  |

examples/aibs_smartspim_instrument.py

@@ -3,13 +3,11 @@
 import argparse
 import datetime
 
-from biodata_models.coordinates import AxisName, Direction, Origin
 from biodata_models.modalities import Modality
 from biodata_models.organizations import Organization
-from biodata_models.units import SizeUnit
 
 from biodata_schema.components.connections import Connection
-from biodata_schema.components.coordinates import Axis, CoordinateSystem
+from biodata_schema.components.coordinates import CoordinateSystem
 from biodata_schema.components.devices import (
     AdditionalImagingDevice,
     Detector,
@@ -23,17 +21,6 @@
 )
 from biodata_schema.core.instrument import Instrument
 
-SIPE_MONITOR_RTF = CoordinateSystem(
-    name="SIPE_MONITOR_RTF",
-    origin=Origin.FRONT_CENTER,
-    axis_unit=SizeUnit.MM,
-    axes=[
-        Axis(name=AxisName.X, direction=Direction.LR),
-        Axis(name=AxisName.Y, direction=Direction.DU),
-        Axis(name=AxisName.Z, direction=Direction.BF),
-    ],
-)
-
 objective = Objective(
     name="TLX Objective",
     numerical_aperture=0.2,
@@ -222,7 +209,7 @@
     location="440",
     instrument_name="SmartSPIM2",
     modification_date=datetime.date(2023, 10, 4),
-    global_coordinate_system=SIPE_MONITOR_RTF,
+    global_coordinate_system=CoordinateSystem.NotApplicable,
     modalities=[Modality.SPIM],
     temperature_control=False,
     components=[

examples/aibs_smartspim_procedures.py

@@ -3,26 +3,13 @@
 import argparse
 from datetime import date
 
-from biodata_models.coordinates import AxisName, Direction, Origin
 from biodata_models.organizations import Organization
-from biodata_models.units import SizeUnit
 
-from biodata_schema.components.coordinates import Axis, CoordinateSystem
+from biodata_schema.components.coordinates import CoordinateSystem
 from biodata_schema.components.reagent import Reagent
 from biodata_schema.components.subject_procedures import Perfusion
 from biodata_schema.core import procedures
 
-BREGMA_ARI = CoordinateSystem(
-    name="BREGMA_ARI",
-    origin=Origin.BREGMA,
-    axis_unit=SizeUnit.MM,
-    axes=[
-        Axis(name=AxisName.AP, direction=Direction.PA),
-        Axis(name=AxisName.ML, direction=Direction.LR),
-        Axis(name=AxisName.SI, direction=Direction.SI),
-    ],
-)
-
 experimenters = ["John Smith"]
 specimen_name = "651286"
 
@@ -43,7 +30,7 @@
     start_date=date(2022, 11, 17),
     experimenters=["LAS"],
     ethics_review_id="2234",
-    global_coordinate_system=BREGMA_ARI,
+    global_coordinate_system=CoordinateSystem.NotApplicable,
     procedures=[
         Perfusion(
             protocol_id="dx.doi.org/10.17504/protocols.io.8epv51bejl1b/v6",
@@ -95,6 +82,7 @@
 
 all_procedures = procedures.Procedures(
     subject_name=specimen_name,
+    global_coordinate_system=CoordinateSystem.NotApplicable,
     subject_procedures=[
         perfusion,
     ],

examples/aind_smartspim_instrument.py

@@ -3,13 +3,11 @@
 import argparse
 from datetime import date
 
-from biodata_models.coordinates import AxisName, Direction, Origin
 from biodata_models.modalities import Modality
 from biodata_models.organizations import Organization
-from biodata_models.units import SizeUnit
 
 from biodata_schema.components.connections import Connection
-from biodata_schema.components.coordinates import Axis, CoordinateSystem
+from biodata_schema.components.coordinates import CoordinateSystem
 from biodata_schema.components.devices import (
     Device,
     Filter,
@@ -24,17 +22,6 @@
     Objective,
 )
 
-SPIM_RPI = CoordinateSystem(
-    name="SPIM_RPI",
-    origin=Origin.ORIGIN,
-    axis_unit=SizeUnit.MM,
-    axes=[
-        Axis(name=AxisName.X, direction=Direction.LR),
-        Axis(name=AxisName.Y, direction=Direction.AP),
-        Axis(name=AxisName.Z, direction=Direction.SI),
-    ],
-)
-
 objective_1 = Objective(
     name="TLX Objective 1",
     numerical_aperture=0.2,
@@ -264,7 +251,7 @@
     location="440",
     instrument_name="SmartSPIM1",
     modification_date=date(2023, 10, 4),
-    global_coordinate_system=SPIM_RPI,
+    global_coordinate_system=CoordinateSystem.NotApplicable,
     modalities=[Modality.SPIM],
     components=[
         scope,

examples/barseq_acquisition.py

@@ -12,10 +12,12 @@
 
 from biodata_models.modalities import Modality
 
+from biodata_schema.components.coordinates import CoordinateSystem
 from biodata_schema.core.acquisition import Acquisition, ExternalDataStream
 
 acquisition = Acquisition(
     subject_name="123456",
+    global_coordinate_system=CoordinateSystem.NotApplicable,
     specimen_name=["123456_bar001", "123456_bar002"],
     acquisition_start_time=datetime(2025, 1, 1, 9, 0, 0, tzinfo=ZoneInfo("America/Los_Angeles")),
     acquisition_end_time=datetime(2025, 1, 31, 17, 0, 0, tzinfo=ZoneInfo("America/Los_Angeles")),

examples/barseq_instrument.py

@@ -3,12 +3,11 @@
 import argparse
 from datetime import date
 
-from biodata_models.coordinates import AxisName, Direction, Origin
 from biodata_models.modalities import Modality
 from biodata_models.organizations import Organization
 from biodata_models.units import SizeUnit
 
-from biodata_schema.components.coordinates import Axis, CoordinateSystem
+from biodata_schema.components.coordinates import CoordinateSystem
 from biodata_schema.components.devices import (
     BinMode,
     Camera,
@@ -24,17 +23,6 @@
 )
 from biodata_schema.core.instrument import Instrument
 
-IMAGE_XYZ = CoordinateSystem(
-    name="IMAGE_XYZ",
-    origin=Origin.ORIGIN,
-    axis_unit=SizeUnit.PX,
-    axes=[
-        Axis(name=AxisName.X, direction=Direction.POS),
-        Axis(name=AxisName.Y, direction=Direction.POS),
-        Axis(name=AxisName.Z, direction=Direction.POS),
-    ],
-)
-
 objectives = [
     Objective(
         name="20x Objective",
@@ -228,7 +216,7 @@
     location="243",
     instrument_name="Dogwood",
     modification_date=date(2024, 7, 9),
-    global_coordinate_system=IMAGE_XYZ,
+    global_coordinate_system=CoordinateSystem.NotApplicable,
     modalities=[Modality.BARSEQ],
     notes=(
         "BarSEQ imaging system with Nikon Ti2-E inverted microscope, X-Light V3 spinning disk confocal, "

examples/exaspim_acquisition.py

@@ -127,6 +127,7 @@
 
 acq = Acquisition(
     experimenters=["John Smith"],
+    global_coordinate_system=SPIM_RPI,
     specimen_name="123456-123",
     subject_name="123456",
     instrument_name="exaSPIM1",

examples/exaspim_instrument.py

@@ -3,13 +3,12 @@
 import argparse
 import datetime
 
-from biodata_models.coordinates import AxisName, Direction, Origin
 from biodata_models.modalities import Modality
 from biodata_models.organizations import Organization
-from biodata_models.units import FrequencyUnit, SizeUnit
+from biodata_models.units import FrequencyUnit
 
 from biodata_schema.components.connections import Connection
-from biodata_schema.components.coordinates import Axis, CoordinateSystem
+from biodata_schema.components.coordinates import CoordinateSystem
 from biodata_schema.components.devices import (
     AdditionalImagingDevice,
     Computer,
@@ -25,17 +24,6 @@
 )
 from biodata_schema.core.instrument import Instrument
 
-SPIM_RPI = CoordinateSystem(
-    name="SPIM_RPI",
-    origin=Origin.ORIGIN,
-    axis_unit=SizeUnit.MM,
-    axes=[
-        Axis(name=AxisName.X, direction=Direction.LR),
-        Axis(name=AxisName.Y, direction=Direction.AP),
-        Axis(name=AxisName.Z, direction=Direction.SI),
-    ],
-)
-
 objectives = [
     Objective(
         name="Custom Objective",
@@ -284,7 +272,7 @@
     instrument_name="exaSPIM1",
     modalities=[Modality.SPIM],
     modification_date=datetime.date(2023, 10, 4),
-    global_coordinate_system=SPIM_RPI,
+    global_coordinate_system=CoordinateSystem.NotApplicable,
     components=[
         *objectives,
         *detectors,

examples/fip_behavior_instrument.py

@@ -5,13 +5,13 @@
 import argparse
 from datetime import date, datetime, timezone
 
-from biodata_models.coordinates import AnatomicalRelative, AxisName, Direction, Origin
+from biodata_models.coordinates import AnatomicalRelative
 from biodata_models.devices import CameraTarget
 from biodata_models.modalities import Modality
 from biodata_models.units import FrequencyUnit, PowerUnit, SizeUnit
 
 from biodata_schema.components.connections import Connection
-from biodata_schema.components.coordinates import Axis, CoordinateSystem
+from biodata_schema.components.coordinates import CoordinateSystem
 from biodata_schema.components.devices import (
     Camera,
     CameraAssembly,
@@ -38,17 +38,6 @@
 from biodata_schema.components.measurements import Calibration
 from biodata_schema.core.instrument import Instrument
 
-BREGMA_ARI = CoordinateSystem(
-    name="BREGMA_ARI",
-    origin=Origin.BREGMA,
-    axis_unit=SizeUnit.MM,
-    axes=[
-        Axis(name=AxisName.AP, direction=Direction.PA),
-        Axis(name=AxisName.ML, direction=Direction.LR),
-        Axis(name=AxisName.SI, direction=Direction.SI),
-    ],
-)
-
 bonsai_software = Software(name="Bonsai", version="2.5")
 
 computer = Computer(
@@ -399,7 +388,7 @@
     instrument_name="FIP-Behavior",
     modification_date=date(2000, 1, 1),
     modalities=[Modality.BEHAVIOR, Modality.FIB],
-    global_coordinate_system=BREGMA_ARI,
+    global_coordinate_system=CoordinateSystem.NotApplicable,
     components=[
         camera1,
         camera2,

examples/fip_ophys_acquisition.py

@@ -19,6 +19,7 @@
     TriggerType,
 )
 from biodata_schema.components.connections import Connection
+from biodata_schema.components.coordinates import CoordinateSystem
 from biodata_schema.components.identifiers import Code
 from biodata_schema.core.acquisition import (
     Acquisition,
@@ -336,6 +337,7 @@
 
 # Create the acquisition object
 acquisition = Acquisition(
+    global_coordinate_system=CoordinateSystem.NotApplicable,
     experimenters=[
         "Bryan MacLennan",
         "Kenta Hagihara",

examples/fip_ophys_instrument.py

@@ -3,29 +3,18 @@
 import argparse
 from datetime import date, datetime, timezone
 
-from biodata_models.coordinates import AnatomicalRelative, AxisName, Direction, Origin
+from biodata_models.coordinates import AnatomicalRelative
 from biodata_models.modalities import Modality
-from biodata_models.units import FrequencyUnit, PowerUnit, SizeUnit
+from biodata_models.units import FrequencyUnit, PowerUnit
 
 import biodata_schema.components.devices as d
 import biodata_schema.core.instrument as r
 from biodata_schema.components.connections import Connection
-from biodata_schema.components.coordinates import Axis, CoordinateSystem
+from biodata_schema.components.coordinates import CoordinateSystem
 from biodata_schema.components.devices import Computer
 from biodata_schema.components.identifiers import Software
 from biodata_schema.components.measurements import Calibration
 
-BREGMA_ARI = CoordinateSystem(
-    name="BREGMA_ARI",
-    origin=Origin.BREGMA,
-    axis_unit=SizeUnit.MM,
-    axes=[
-        Axis(name=AxisName.AP, direction=Direction.PA),
-        Axis(name=AxisName.ML, direction=Direction.LR),
-        Axis(name=AxisName.SI, direction=Direction.SI),
-    ],
-)
-
 bonsai_software = Software(name="Bonsai", version="2.5")
 
 computer = Computer(
@@ -343,7 +332,7 @@
     instrument_name="FIP1",
     modification_date=date(2023, 10, 3),
     modalities=[Modality.FIB],
-    global_coordinate_system=BREGMA_ARI,
+    global_coordinate_system=CoordinateSystem.NotApplicable,
     components=[
         camera_assembly_1,
         camera_assembly_2,