Diagrams_in_doc (#257)

* add diagram to doc * remove warnings * Move Sphinx code for chunk illustrations into the code docstrings * Add a hook for the ragged-array illustration * Revert to chunk diagrams via api.rst --------- Co-authored-by: Philippe Miron <philippe.miron@dtn.com> Co-authored-by: milancurcic <caomaco@gmail.com>
Cloud-Drift · Sep 15, 2023 · ac0bdd4 · ac0bdd4
1 parent 6b2f04f
commit ac0bdd4
Show file tree

Hide file tree

Showing 6 changed files with 28 additions and 3 deletions.
diff --git a/clouddrift/analysis.py b/clouddrift/analysis.py
@@ -118,8 +118,7 @@ def chunk(
     number of chunks is determined based on the length of ``x``, ``length``,
     and ``overlap``.
 
-    ``chunk`` can be combined with :func:`apply_ragged` in order to chunk a ragged
-    array.
+    ``chunk`` can be combined with :func:`apply_ragged` to chunk a ragged array.
 
     Parameters
     ----------

diff --git a/docs/api.rst b/docs/api.rst
@@ -38,8 +38,24 @@ Analysis
 
 .. automodule:: clouddrift.analysis
   :members:
+  :exclude-members: chunk
   :undoc-members:
 
+  .. autofunction:: chunk
+
+    .. image:: img/chunk.png
+      :width: 800
+      :align: center
+      :alt: chunk schematic
+
+    Combined with :func:`clouddrift.analysis.apply_ragged`, :func:`clouddrift.analysis.chunk`
+    can be used to divide a ragged array into equal chunks.
+
+    .. image:: img/chunk_ragged.png
+      :width: 800
+      :align: center
+      :alt: ragged array chunk schematic
+
 Datasets
 --------
 

diff --git a/docs/img/chunk.png b/docs/img/chunk.png
diff --git a/docs/img/chunk_ragged.png b/docs/img/chunk_ragged.png
diff --git a/docs/img/ragged_array.png b/docs/img/ragged_array.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -12,7 +12,17 @@ The `Global Drifter Program (GDP) <https://www.aoml.noaa.gov/phod/gdp/>`_ of the
 
 There are a few ways to retrieve the data, but all typically require time-consuming preprocessing steps in order to prepare the data for analysis. As an example, the datasets can be retrieved through an `ERDDAP server <https://data.pmel.noaa.gov/generic/erddap/tabledap/gdp_hourly_velocities.html>`_, but requests are limited in size. The latest `6-hourly dataset <https://www.aoml.noaa.gov/ftp/pub/phod/lumpkin/netcdf/>`_ is distributed as a collection of thousands of individual NetCDF files or as a series of `ASCII files <https://www.aoml.noaa.gov/phod/gdp/>`_. Until recently, the `hourly dataset <https://www.aoml.noaa.gov/ftp/pub/phod/lumpkin/hourly/v2.00/netcdf/>`_ was distributed as a collection of individual NetCDF files (17,324 for version 1.04c) but is now distributed by NOAA NCEI as a `single NetCDF file <https://doi.org/10.25921/x46c-3620>`_ containing a series of ragged arrays, thanks to the work of CloudDrift. A single file simplifies data distribution, decreases metadata redundancies, and efficiently stores a Lagrangian data collection of uneven lengths.
 
-CloudDrift goals are to *simplify* the necessary steps to get started with the GDP dataset or any Lagrangian datasets, and to provide a cloud-ready library to *accelerate* Lagrangian analysis.
+CloudDrift's analysis functions are centered around the ragged-array data
+structure:
+
+.. image:: img/ragged_array.png
+  :width: 800
+  :align: center
+  :alt: Ragged array schematic
+
+CloudDrift's goals are to simplify the necessary steps to get started with
+Lagrangian datasets and to provide a cloud-ready library to accelerate
+Lagrangian analysis.
 
 Getting started
 ---------------