Fixes / changes to docs in "Data processing" pages (#1132)

* docs: Correct spelling error * docs: Fix RTD latex rendering error * docs: move 'Format of processed data' section to more prominenbt page * update range_bin to range_sample in fig --------- Co-authored-by: Wu-Jung Lee <[email protected]>
OSOceanAcoustics · Aug 24, 2023 · 183cf7a · 183cf7a
1 parent 29422d0
commit 183cf7a
Show file tree

Hide file tree

Showing 4 changed files with 626 additions and 634 deletions.
diff --git a/docs/source/data-proc-additional.ipynb b/docs/source/data-proc-additional.ipynb
@@ -1,106 +1,91 @@
 {
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "(data-proc:additional)=\n",
-    "# Additional information for processed data\n",
-    "\n",
-    "This page provide information on some aspects of processed data that may require additional explanation to fully understand the representation and underlying operations."
-   ]
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "(data-proc:additional)=\n",
+        "# Additional information for processed data\n",
+        "\n",
+        "This page provide information on some aspects of processed data that may require additional explanation to fully understand the representation and underlying operations."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "(data-proc:echo-range)=\n",
+        "## Range of echo samples"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "The calibration operation in `compute_Sv` generates a new data variable, `echo_range`, which is the physically meaningful range (in meters) of the echo samples.\n",
+        "`echo_range` is compute from the `range_sample` coordinate (which contains 0-based indices of the digitized sample numbers of the received echoes) of the raw data in combination with the `sample_interval` in the `Sonar/Beam_groupX` group and sound speed either stored in the raw data file or provided by the user.\n",
+        "Echopype assumes a constant sound and does not currently support the use a sound speed profile."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n",
+        "The computation for `echo_range` ($r$) is:\n",
+        "\n",
+        "$$\n",
+        "r = N \\Delta r = N c \\tau / 2\n",
+        "$$\n",
+        "\n",
+        "where $\\Delta r$ is the along-range \"length\" of each sample, $N$ is the index number in `range_sample`, $\\tau$ is the `sample_interval`, and $c$ is sound speed. The factor of 2 is due to the round-trip travel from the transmitter to the scatterer and back to the receiver."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Because `sample_interval` can be different for different channels, the resulting ``echo_range`` arrays can be different across channel even if they have the same number of digitized samples. This is illustrated in the sketch below, in which (**A**) shows the dimensions of the variable `backscatter_r` and (**B**) shows the varying values of `echo_range` that change depending on `sample_interval`. In this example, the `sample_interval` of the first channel is twice of that of the second and the third channel.\n",
+        "\n",
+        "![](./images/echo_range.png)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<!-- ### ADD FIGURE -->"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": []
+    }
+  ],
+  "metadata": {
+    "celltoolbar": "Tags",
+    "interpreter": {
+      "hash": "a292767406182d99a2458e67c2d2e96b524510c4a2166b4b423439fe75c32190"
+    },
+    "kernelspec": {
+      "display_name": "Python 3 (ipykernel)",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.9.7"
+    }
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "(data-proc:format)=\n",
-    "## Format of processed data"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Once raw data (represented by the `EchoData` objects) are calibrated  (via [`compute_Sv`](echopype.calibrate.compute_Sv)), the calibrated data and the outputs of all subsequent [processing functions](data-process:funcionalities) are generic [xarray Datasets](https://docs.xarray.dev/en/stable/user-guide/data-structures.html#dataset).\n",
-    "We currently do not follow any specific conventions for processed data, but we retain provenance information in the dataset, including the [data processing levels](./processing-levels.md).\n",
-    "However, whether and how data variables used in the processing will be stored remain to be determined."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "(data-proc:echo-range)=\n",
-    "## Range of echo samples"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "The calibration operation in `compute_Sv` generates a new data variable, `echo_range`, which is the physically meaningful range (in meters) of the echo samples.\n",
-    "`echo_range` is compute from the `range_sample` coordinate (which contains 0-based indices of the digitized sample numbers of the received echoes) of the raw data in combination with the `sample_interval` in the `Sonar/Beam_groupX` group and sound speed either stored in the raw data file or provided by the user.\n",
-    "Echopype assumes a constant sound and does not currently support the use a sound speed profile."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "\n",
-    "The computation for `echo_range` ($r$) is:\n",
-    "$$\n",
-    "r = N \\Delta r = N c \\tau / 2\n",
-    "$$\n",
-    "where $\\Delta r$ is the along-range \"length\" of each sample, $N$ is the indice number in `range_sample`, $\\tau$ is the `sample_interval`, and $c$ is sound speed. The factor of 2 is due to the round-trip travel from the transmitter to the scatterer and back to the receiver."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Because `sample_interval` can be different for different channels, the resulting ``echo_range`` arrays can be different across channel even if they have the same number of digitized samples. This is illustrated in the sketch below, in which (**A**) shows the dimensions of the variable `backscatter_r` and (**B**) shows the varying values of `echo_range` that change depending on `sample_interval`. In this example, the `sample_interval` of the first channel is twice of that of the second and the third channel.\n",
-    "\n",
-    "![](./images/echo_range.png)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "<!-- ### ADD FIGURE -->"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": []
-  }
- ],
- "metadata": {
-  "celltoolbar": "Tags",
-  "interpreter": {
-   "hash": "a292767406182d99a2458e67c2d2e96b524510c4a2166b4b423439fe75c32190"
-  },
-  "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.9.7"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
+  "nbformat": 4,
+  "nbformat_minor": 4
 }