From ff49b94e851c71415e40e56420fc161c640dd35f Mon Sep 17 00:00:00 2001 From: bruno-f-cruz <7049351+bruno-f-cruz@users.noreply.github.com> Date: Thu, 30 May 2024 11:53:36 -0700 Subject: [PATCH 1/3] Fix header priority --- docs/api.base/rig.rst | 2 +- docs/api.base/task_logic.rst | 2 +- docs/api.calibration/aind_manipulator.rst | 2 +- docs/api.calibration/load_cells.rst | 2 +- docs/api.calibration/olfactometer.rst | 2 +- docs/api.calibration/water_valve.rst | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api.base/rig.rst b/docs/api.base/rig.rst index a34eef82..62bc369b 100644 --- a/docs/api.base/rig.rst +++ b/docs/api.base/rig.rst @@ -1,5 +1,5 @@ AindBehaviorRigModel -------------- +------------------------- .. autopydantic_model:: aind_behavior_services.AindBehaviorRigModel :members: diff --git a/docs/api.base/task_logic.rst b/docs/api.base/task_logic.rst index 79d41cf8..d75b0820 100644 --- a/docs/api.base/task_logic.rst +++ b/docs/api.base/task_logic.rst @@ -1,5 +1,5 @@ AindBehaviorTaskLogicModel -------------- +-------------------------------- .. autopydantic_model:: aind_behavior_services.AindBehaviorTaskLogicModel :members: diff --git a/docs/api.calibration/aind_manipulator.rst b/docs/api.calibration/aind_manipulator.rst index 8d726196..0e7b6282 100644 --- a/docs/api.calibration/aind_manipulator.rst +++ b/docs/api.calibration/aind_manipulator.rst @@ -7,7 +7,7 @@ aind_manipulator :show-inheritance: Example --------- +########## .. literalinclude:: ../../examples/aind_manipulator.py :language: python diff --git a/docs/api.calibration/load_cells.rst b/docs/api.calibration/load_cells.rst index d52d76ba..1f61c27e 100644 --- a/docs/api.calibration/load_cells.rst +++ b/docs/api.calibration/load_cells.rst @@ -7,7 +7,7 @@ load_cells :show-inheritance: Example --------- +######## .. literalinclude:: ../../examples/load_cells.py :language: python diff --git a/docs/api.calibration/olfactometer.rst b/docs/api.calibration/olfactometer.rst index 60a1c4c4..1113e614 100644 --- a/docs/api.calibration/olfactometer.rst +++ b/docs/api.calibration/olfactometer.rst @@ -7,7 +7,7 @@ olfactometer :show-inheritance: Example --------- +######## .. literalinclude:: ../../examples/olfactometer.py :language: python diff --git a/docs/api.calibration/water_valve.rst b/docs/api.calibration/water_valve.rst index 401d38ac..f6e32919 100644 --- a/docs/api.calibration/water_valve.rst +++ b/docs/api.calibration/water_valve.rst @@ -7,7 +7,7 @@ water_valve :show-inheritance: Example --------- +######## .. literalinclude:: ../../examples/water_valve.py :language: python From 67f2b3d6d96e1a0f8aaf7756a2dd93e230ddb0dc Mon Sep 17 00:00:00 2001 From: bruno-f-cruz <7049351+bruno-f-cruz@users.noreply.github.com> Date: Thu, 30 May 2024 11:53:57 -0700 Subject: [PATCH 2/3] Upper case titles --- docs/api.base.rst | 2 +- docs/api.rst | 2 +- docs/index.rst | 2 ++ docs/json-schemas.rst | 2 +- 4 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/api.base.rst b/docs/api.base.rst index 150debeb..0c3bdfc8 100644 --- a/docs/api.base.rst +++ b/docs/api.base.rst @@ -1,4 +1,4 @@ -api.base +Base ------------- .. toctree:: diff --git a/docs/api.rst b/docs/api.rst index aae0ca2a..953190c1 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,4 +1,4 @@ -api +API ------------- .. toctree:: diff --git a/docs/index.rst b/docs/index.rst index 796e0a29..cc33d3e1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,8 +13,10 @@ Welcome to AIND Behavior Services's documentation! :maxdepth: 4 :caption: Contents: + self api json-schemas + GitHub Source Code Indices and tables ================== diff --git a/docs/json-schemas.rst b/docs/json-schemas.rst index 14a06faf..ee377943 100644 --- a/docs/json-schemas.rst +++ b/docs/json-schemas.rst @@ -1,5 +1,5 @@ -json-schemas +JsonSchema ------------- .. toctree:: :maxdepth: 4 From 9346638bd8eb58c05e1ab284aba65a9506aaab7d Mon Sep 17 00:00:00 2001 From: bruno-f-cruz <7049351+bruno-f-cruz@users.noreply.github.com> Date: Thu, 30 May 2024 11:54:12 -0700 Subject: [PATCH 3/3] Add conceptual documentation to calibration --- docs/api.calibration.rst | 117 ++++++++++++++++++++++++++++++++++++++- docs/conf.py | 3 +- 2 files changed, 117 insertions(+), 3 deletions(-) diff --git a/docs/api.calibration.rst b/docs/api.calibration.rst index 962e0cc3..ff653cb6 100644 --- a/docs/api.calibration.rst +++ b/docs/api.calibration.rst @@ -1,10 +1,123 @@ -api.calibration +Calibration ------------- +Calibration Module +#################### + +The calibration module of this library is used to generate the metadata necessary configure and run calibration workflows for different assets/devices. + +The metadata follows the general logic of the library by implementing the three core classes: + - :py:class:`~aind_behavior_services.session.AindBehaviorSessionModel` + - :py:class:`~aind_behavior_services.rig.AindBehaviorRigModel` + - :py:class:`~aind_behavior_services.task_logic.AindBehaviorTaskLogicModel` + +A fourth class :py:class:`~aind_behavior_services.calibration.Calibration`, +specific to the Calibration module, is also implemented to keep track of the calibration metrics. +This class was written to be aligned to the Calibration class in aind-data-schemas +(https://github.com/AllenNeuralDynamics/aind-data-schema/blob/2fd0e403bf46f0f1a47e5922c4228517e68376a3/src/aind_data_schema/components/devices.py#L274). +An application example will be provided below. + +While we use the base :py:class:`~aind_behavior_services.session.AindBehaviorSessionModel` class to keep track of the session metadata, +both :py:class:`~aind_behavior_services.rig.AindBehaviorRigModel` and :py:class:`~aind_behavior_services.task_logic.AindBehaviorTaskLogicModel` are +expected to be sub-classed to specify the necessary dependencies of the calibration workflow. + +Sub-classing :py:class:`~aind_behavior_services.calibration.Calibration` +########################################################################## + +Sub-classing :py:class:`~aind_behavior_services.calibration.Calibration` boils down to providing a subtype of the `input` and `output` fields. +These fields are expected to be of a sub-type of `~pydantic.BaseModel` and define the structure of the calibration outcome. +Conceptually, `input` is the pre-process data that resulted from the calibration workflow (i.e. the weight of delivered water), +whereas `output` is used to represent a post-processed version of the calibration outcome (e.g. a linear model that relates valve-opening times to water volume). + +An example of a sub-class of `Calibration` is provided below: + +.. code-block:: python + + from pydantic import BaseModel, Field + from typing import List, Literal + from aind_behavior_services.calibration import Calibration + + + class BarContainer(BaseModel): + baz: string = Field(..., description="Baz value") + bar: float = Field(..., description="Bar value") + + + class DeviceCalibrationInput(BaseModel): + measured_foo: List[int] = Field(..., description="Measurements of Foo") + bar_container: List[BarContainer] = Field(..., description="Bar container") + + + class DeviceCalibrationOutput(BaseModel): + param_a = float = Field(default=1, description="Parameter A") + param_b = float = Field(default=0, description="Parameter B") + + + class DeviceCalibration(Calibration): + device_name: Literal["MyDevice"] = "MyDevice" + description: Literal["Stores the calibration of a device"] = "Stores the calibration of a device" + input: DeviceCalibrationInput = Field(..., title="Input of the calibration") + output: DeviceCalibrationOutput = Field(..., title="Output of the calibration") + +Sub-classing :py:class:`~aind_behavior_services.rig.AindBehaviorRigModel` +########################################################################## + +We adopt the following pattern to sub-class the :py:class:`~aind_behavior_services.rig.AindBehaviorRigModel` class: + +.. code-block:: python + + from aind_behavior_services.rig import AindBehaviorRigModel, Device + + RIG_VERSION = "1.0.0" # Use SemVer + + class FooDevice(Device): + calibration: DeviceCalibration = Field(..., title="Calibration of the device foo") + + + class CalibrationRig(AindBehaviorRigModel): + version: Literal[RIG_VERSION] = RIG_VERSION + device_foo: FooDevice = Field(..., title="Device Foo") + device_bar: Device = Field(..., title="Device Bar") + + +For an example see :py:class:`aind_behavior_services.calibration.olfactometer.CalibrationRig`. + + + +Sub-classing :py:class:`~aind_behavior_services.task_logic.AindBehaviorTaskLogicModel` +################################################################################ + +The same way a :py:class:`~aind_behavior_services.task_logic.AindBehaviorTaskLogicModel` is used to define +the settings to run a behavior task, it is also used to define the settings to run a calibration workflow. +It will thus fallow an identical sub-classing pattern: + + +.. code-block:: python + + from aind_behavior_services.task_logic import AindBehaviorTaskLogicModel, TaskParameters + + TASK_LOGIC_VERSION = "0.1.0" + + class CalibrationParameters(TaskParameters): + n_iterations: int = Field(default=10, description="Number of iterations to run the calibration") + channels_to_calibrate: List[Literal[1,2,3]] = Field(default=[1], description="List of channels to calibrate") + + class CalibrationLogic(AindBehaviorTaskLogicModel): + name: Literal["CalibrationLogic"] = "CalibrationLogic + version: Literal[TASK_LOGIC_VERSION] = TASK_LOGIC_VERSION + task_parameters: CalibrationParameters = Field(default=CalibrationParameters(), title="Task parameters", validate_default=True) + + +For an example see :py:class:`aind_behavior_services.calibration.olfactometer.CalibrationLogic`. + + + .. toctree:: - :maxdepth: 3 + :maxdepth: 4 api.calibration/aind_manipulator api.calibration/load_cells api.calibration/olfactometer api.calibration/water_valve + + diff --git a/docs/conf.py b/docs/conf.py index 7e59209c..529da1e0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -32,7 +32,7 @@ rst_target_path = os.path.abspath("json-schemas") root_template = """ -json-schemas +JsonSchema ------------- .. toctree:: :maxdepth: 4 @@ -75,6 +75,7 @@ "sphinx.ext.linkcode", "myst_parser", "sphinxcontrib.autodoc_pydantic", + 'sphinx_copybutton' ] templates_path = ["_templates"] exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]