Skip to content

Commit

Permalink
use :mod: directive to fix links
Browse files Browse the repository at this point in the history
  • Loading branch information
ocefpaf committed Oct 13, 2022
1 parent 7aa153d commit 3e3c2e2
Showing 1 changed file with 7 additions and 7 deletions.
14 changes: 7 additions & 7 deletions docs/source/usage.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ At its core, ``ioos_qc`` is a collection of modules and methods to run various q

The following implementations are available in ``ioos_qc``:

* `IOOS QARTOD <https://ioos.noaa.gov/project/qartod/>`_ - `API </api/ioos_qc.html#module-ioos_qc.qartod>`_
* `ARGO - API </api/ioos_qc.html#module-ioos_qc.argo>`_
* `AXDS - API </api/ioos_qc.html#module-ioos_qc.axds>`_ - A collection of checks used by `Axiom Data Science <https://axiomdatascience.com>`_
* `IOOS QARTOD <https://ioos.noaa.gov/project/qartod/>`_ - :mod:`API <ioos_qc.qartod>`
* :mod:`ARGO - API <ioos_qc.argo>`
* :mod:`AXDS - API <ioos_qc.axds>` - A collection of checks used by `Axiom Data Science <https://axiomdatascience.com>`_

Basic usage
-----------
Expand Down Expand Up @@ -211,7 +211,7 @@ Usage
Streams
-------

Streams represent the data input types for running quality control tests. A user "runs" a stream of data through a collection of quality control tests defined by a Config_. A list of possible Streams can be found in the `Streams API </api/ioos_qc.html#module-ioos_qc.streams>`_.
Streams represent the data input types for running quality control tests. A user "runs" a stream of data through a collection of quality control tests defined by a Config_. A list of possible Streams can be found in the :mod:`Streams API <ioos_qc.streams>`.
All streams return a generator of QC results that contain contextual information that can be useful when using the results. You can iterate over the results generator directly or you can collect them into more familiar ``list`` or ``dict`` objects before usage. If you are
working in a streaming environment you will want to use generator result objects yourself. If you are running one-time or batch process quality checks you likely want to collect the results or use one of the Stores_ provided by ``ioos_qc``.

Expand All @@ -225,15 +225,15 @@ working in a streaming environment you will want to use generator result objects
Results
~~~~~~~

Each yielded result will be a `StreamConfigResult </api/ioos_qc.html#ioos_qc.results.StreamConfigResult>`_ or a `ContextResult </api/ioos_qc.html#ioos_qc.results.ContextResult>`_, depending on which type of Config_ object was used. Collected results are only ever of one type, a `CollectedResult </api/ioos_qc.html#ioos_qc.results.CollectedResult>`_, and only one ``CollectedResult`` will be returned after collecting Results. The benefit of using a ``CollectedResult`` is that it will piece back together all of the different ContextConfig_ objects in a Config_ and return you one result per unique ``stream_id`` and module/test combination.
Each yielded result will be a :mod:`StreamConfigResult <ioos_qc.results.StreamConfigResult>` or a :mod:`ContextResult <ioos_qc.results.ContextResult>`, depending on which type of Config_ object was used. Collected results are only ever of one type, a :mod:`CollectedResult <ioos_qc.results.CollectedResult>`, and only one ``CollectedResult`` will be returned after collecting Results. The benefit of using a ``CollectedResult`` is that it will piece back together all of the different ContextConfig_ objects in a Config_ and return you one result per unique ``stream_id`` and module/test combination.

.. note::

For example: If you had a Config_ object that contained (3) different ContextConfig_ objects (each defining a time window and test inputs) for a single variable/``stream_id``, running that ``Config`` through any ``Stream`` implementation would yield (3) different ``ContextResult`` objects. You could use them yourself to construct whatever results you wanted to manually, or you could collect those results back into a single ``CollectedResult`` object to only have to deal with one result.

.. warning::

Historically, test results were returned in a ``dict`` structure. While this is still supported it **should be considered deprecated**. The individually yielded result objects or a list of `CollectedResult objects <api/ioos_qc.html#ioos_qc.results.CollectedResult>`_ should be used in any applications, including any implementation of Stores_, going forward.
Historically, test results were returned in a ``dict`` structure. While this is still supported it **should be considered deprecated**. The individually yielded result objects or a list of :mod:`CollectedResult objects <ioos_qc.results.CollectedResult>` should be used in any applications, including any implementation of Stores_, going forward.


.. code-block:: python
Expand Down Expand Up @@ -517,7 +517,7 @@ A subset of the NumpyStream, the NetcdfStream simply extracts numpy arrays from
Stores
------

Stores represent different data formats for storing quality control Results_ from Streams_. The results from any ``Stream`` should be able to be passed into any ``Store`` implementation defined in the `Stores API </api/ioos_qc.html#module-ioos_qc.stores>`_.
Stores represent different data formats for storing quality control Results_ from Streams_. The results from any ``Stream`` should be able to be passed into any ``Store`` implementation defined in the :mod:`Stores API <ioos_qc.stores>`.

``ioos_qc`` comes with some built-in Stores_:

Expand Down

0 comments on commit 3e3c2e2

Please sign in to comment.