dacapo
======

.. py:module:: dacapo


Subpackages
-----------

.. toctree::
   :maxdepth: 1

   /autoapi/dacapo/blockwise/index
   /autoapi/dacapo/compute_context/index
   /autoapi/dacapo/experiments/index
   /autoapi/dacapo/ext/index
   /autoapi/dacapo/gp/index
   /autoapi/dacapo/store/index
   /autoapi/dacapo/utils/index


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/dacapo/apply/index
   /autoapi/dacapo/options/index
   /autoapi/dacapo/plot/index
   /autoapi/dacapo/predict/index
   /autoapi/dacapo/predict_local/index
   /autoapi/dacapo/train/index
   /autoapi/dacapo/validate/index


Classes
-------

.. autoapisummary::

   dacapo.Options


Functions
---------

.. autoapisummary::

   dacapo.apply
   dacapo.train
   dacapo.validate
   dacapo.validate_run


Package Contents
----------------

.. py:class:: Options

   A class that provides options for configuring DaCapo.

   This class is designed as a singleton and should be accessed using the `instance` method.

   .. method:: instance

      Returns an instance of the Options class.

   .. method:: config_file

      Returns the path to the configuration file.

   .. method:: __parse_options_from_file

      Parses options from the configuration file.

   .. method:: __parse_options

      Parses options from the configuration file and updates them with the provided kwargs.
      


   .. py:method:: instance(**kwargs) -> DaCapoConfig
      :classmethod:


      Returns an instance of the Options class.

      :param kwargs: Additional keyword arguments to update the options.

      :returns: An instance of the DaCapoConfig class.

      .. rubric:: Examples

      >>> options = Options.instance()
      >>> options
      DaCapoConfig(type='files', runs_base_dir=PosixPath('/home/user/dacapo'), compute_context={'type': 'LocalTorch', 'config': {}}, mongo_db_host=None, mongo_db_name=None)



   .. py:method:: config_file() -> Optional[upath.UPath]
      :classmethod:


      Returns the path to the configuration file.

      :returns: The path to the configuration file if found, otherwise None.

      .. rubric:: Examples

      >>> Options.config_file()
      PosixPath('/home/user/.config/dacapo/dacapo.yaml')



.. py:function:: apply(run_name: str, input_container: upath.UPath | str, input_dataset: str, output_path: upath.UPath | str, validation_dataset: Optional[dacapo.experiments.datasplits.datasets.dataset.Dataset | str] = None, criterion: str = 'voi', iteration: Optional[int] = None, parameters: Optional[dacapo.experiments.tasks.post_processors.post_processor_parameters.PostProcessorParameters | str] = None, roi: Optional[funlib.geometry.Roi | str] = None, num_workers: int = 12, output_dtype: numpy.dtype | str = np.uint8, overwrite: bool = True, file_format: str = 'zarr')

   Load weights and apply a trained model to a dataset. If iteration is None, the best iteration based on the criterion is used. If roi is None, the whole input dataset is used.

   :param run_name: Name of the run to apply.
   :type run_name: str
   :param input_container: Path to the input container.
   :type input_container: Path | str
   :param input_dataset: Name of the input dataset.
   :type input_dataset: str
   :param output_path: Path to the output container.
   :type output_path: Path | str
   :param validation_dataset: Validation dataset to use for finding the best parameters. Defaults to None.
   :type validation_dataset: Optional[Dataset | str], optional
   :param criterion: Criterion to use for finding the best parameters. Defaults to "voi".
   :type criterion: str, optional
   :param iteration: Iteration to use. If None, the best iteration is used. Defaults to None.
   :type iteration: Optional[int], optional
   :param parameters: Post-processor parameters to use. If None, the best parameters are found. Defaults to None.
   :type parameters: Optional[PostProcessorParameters | str], optional
   :param roi: Region of interest to use. If None, the whole input dataset is used. Defaults to None.
   :type roi: Optional[Roi | str], optional
   :param num_workers: Number of workers to use. Defaults to 12.
   :type num_workers: int, optional
   :param output_dtype: Output dtype. Defaults to np.uint8.
   :type output_dtype: np.dtype | str, optional
   :param overwrite: Overwrite existing output. Defaults to True.
   :type overwrite: bool, optional
   :param file_format: File format to use. Defaults to "zarr".
   :type file_format: str, optional

   :raises ValueError: If validation_dataset is None and criterion is not None.
   :raises ValueError: If parameters is a string that cannot be parsed to PostProcessorParameters.
   :raises ValueError: If parameters is not a PostProcessorParameters object.

   .. rubric:: Examples

   >>> apply(
   ...     run_name="run_1",
   ...     input_container="data.zarr",
   ...     input_dataset="raw",
   ...     output_path="output.zarr",
   ...     validation_dataset="validate",
   ...     criterion="voi",
   ...     num_workers=12,
   ...     output_dtype=np.uint8,
   ...     overwrite=True,
   ... )


.. py:function:: train(run_name: str, do_validate=True)

   Train a run

   :param run_name: Name of the run to train

   :raises ValueError: If run_name is not found in config store

   .. rubric:: Examples

   >>> train("run_name")


.. py:function:: validate(run_name: str, iteration: int = 0, datasets_config=None)

   Validate a run at a given iteration. Loads the weights from a previously
   stored checkpoint. Returns the best parameters and scores for this
   iteration.


.. py:function:: validate_run(run: dacapo.experiments.Run, iteration: int, datasets_config=None)

   Validate an already loaded run at the given iteration. This does not
   load the weights of that iteration, it is assumed that the model is already
   loaded correctly. Returns the best parameters and scores for this
   iteration.