docs: calibration

docs/source/acquire_upload/acquire_data.md

@@ -47,4 +47,3 @@ Some tasks are being run on a standardized platform using Bonsai and Harp for da
 |------|-----------|
 | VrForaging | https://github.com/AllenNeuralDynamics/Aind.Behavior.VrForaging |
 | IsoForce | https://github.com/AllenNeuralDynamics/Aind.Behavior.IsoForce |
-

docs/source/acquire_upload/calibration.md

@@ -8,6 +8,66 @@ Common calibrations include measuring power output (e.g. for lasers) with [Power
 
 Calibrations have an option to include fit parameters, if your calibration fit is not available in the [FitType](https://aind-data-schema.readthedocs.io/en/latest/components/measurements.html#fittype) options please request that we add it by opening an [issue](https://github.com/AllenNeuralDynamics/aind-data-schema/issues).
 
-## Instrument testing
+## Testing
 
-When collecting a *test data asset* on an instrument using a "calibration object" instead of a subject or specimen, you should set `subject_id = "calibration"` in all metadata files. Please also use the [CalibrationObject](https://aind-data-schema.readthedocs.io/en/latest/components/subjects.html#calibrationobject) in the `Subject.subject_details` to track information about the physical object used during calibration.
+Use `subject_id="calibration"` to mark data assets as test assets. When a "phantom" or other calibration object is used during testing please provide details about that object in a `CalibrationObject`. Before uploading calibration assets you need to ensure that your asset and metadata are compatible with the processing pipelines that will be run downstream.
+
+Note that test assets that are not intended to be kept long-term should be immediately (or as soon as feasible) marked as archived on Code Ocean. Archived assets are deleted when unused for 30 days.
+
+### Manual calibration metadata
+
+If the processing pipeline that will run on your test data asset **requires certain fields in the subject or procedures metadata to be set** you need to create an actual `subject.json` and `procedures.json` and upload these alongside your data asset.
+
+```{code-block} python
+from aind_data_schema.core.subject import Subject
+from aind_data_schema.core.procedures import Procedures
+from aind_data_schema.components.subjects import CalibrationObject
+from aind_data_schema.components.devices import Device
+from aind_data_schema_models.organizations import Organization
+
+subject_id = "calibration"
+
+subject = Subject(
+    subject_id=subject_id,
+    subject_details=CalibrationObject(
+        empty=True,
+        description="FIP calibration",
+    ),
+)
+
+procedures = Procedures(subject_id=subject_id)
+
+subject.write_standard_file()
+procedures.write_standard_file()
+```
+
+### Automated calibration metadata
+
+If the processing pipeline that will run on your data asset **does not read the subject and/or procedures metadata** you can follow the instructions below to create empty subject and procedures files.
+
+Note that this automation is only available if your job_type runs `aind-metadata-mapper>=1.3.0`. Please include as much detail as possible about your [CalibrationObject](https://aind-data-schema.readthedocs.io/en/latest/components/subjects.html#calibrationobject) in the upload settings.
+
+```{code-block} python
+from aind_data_schema.components.subjects import CalibrationObject
+from aind_data_schema_models.modalities import Modality
+from aind_metadata_mapper.gather_metadata import GatherMetadataJob
+from aind_metadata_mapper.models import JobSettings, DataDescriptionSettings, SubjectSettings
+
+job_settings = JobSettings(
+    output_dir="/path/to/output",
+    subject_id="calibration",
+    data_description_settings=DataDescriptionSettings(
+        project_name="<project-name>",
+        modalities=[Modality.ECEPHYS],
+    ),
+    subject_settings=SubjectSettings(
+        calibration_object=CalibrationObject(
+            description="Neuropixels dummy probe",
+            empty=False,
+        )
+    ),
+)
+
+job = GatherMetadataJob(job_settings=job_settings)
+job.run_job()
+```