docs: Overhaul theory pages (#210)

* add all new theory pages

* readme and index updates

README.md

@@ -24,7 +24,7 @@ and Julia Clemons (@JuliaClemons-NOAA)
 of the NWFSC Fisheries Engineering and Acoustics Team (FEAT)
 for continuing discussions that make Echopop better.
 
-This project is financially supported by NOAA Fisheries.
+This project is supported by NOAA Fisheries.
 
 <img src="docs/images/noaa_fisheries_logo.png" alt="NOAA_fisheries_logo" width="200">
 

docs/_toc.yml

@@ -12,11 +12,11 @@ parts:
   - file: theory
     title: Underlying theory
     sections:
-    - file: theory/acoustics_to_bio
-    - file: theory/apportioning_biological_variables
-    - file: theory/semivariograms
-    - file: theory/kriging
-    - file: theory/stratified_statistics
+    - file: theory/01_acoustics
+    - file: theory/02_bio_estimates
+    - file: theory/03_stratification
+    - file: theory/05_kriging_eq
+    - file: theory/06_semivariograms
     # - file: theory/other
   # - file: algo
   #   title: Algorithmic implementation

docs/index.md

@@ -29,11 +29,11 @@ and Julia Clemons (@JuliaClemons-NOAA)
 of the NWFSC Fisheries Engineering and Acoustics Team (FEAT)
 for continuing discussions that make Echopop better.
 
-This project is financially supported by NOAA Fisheries.
+This project is supported by NOAA Fisheries.
 
 ```{image} images/noaa_fisheries_logo.png
 :alt: NOAA_fisheries_logo
-:width: 240px
+:width: 230px
 ```
 
 

docs/theory/01_acoustics.md

@@ -0,0 +1,53 @@
+# Acoustics basics
+
+## Backscattering cross-section and target strength
+For a given scatterer, the differential backscattering cross section ($\sigma_{bs}$, units: m<sup>2</sup>) and backscattering cross section ($\sigma_{b}$, units: m<sup>2</sup>) are related by
+
+$$
+\sigma_{bs} = \frac{\sigma_b}{ 4 \pi}
+$$
+
+The target strength ($TS$, units: dB re 1 m<sup>2</sup>) is defined as
+
+$$
+TS = 10 \log_{10} \sigma_{bs}
+$$
+
+For a group of $N$ animals, the mean backscattering cross-section is
+
+$$
+\left< \sigma_{bs} \right> = \frac{\sum_{j=1}^N \sigma_{bs,j} }{ N },
+$$
+
+where $\sigma_{bs,j}$ is the backscattering cross-section of animal $j$, which often varies as a function of its length $L_j$:
+
+$$
+\sigma_{bs,j} = \sigma_{bs,j}(L_j)
+$$
+
+
+
+
+## TS-length relationship
+
+One common avenute to estimate TS of a scatterer is based on empirical relationshpi between TS and length, which can be expressed by
+
+$$
+TS = mL + b,
+$$
+
+where $L$ is the total length, $m$ is the slope, and $b$ is the <i>y</i>-intercept.
+
+For Pacific hake, the empitical TS-length relationship used in Echopop is
+
+$$
+TS = 20 L - 68
+$$
+
+where $L$ is the fish fork length in cm.
+
+Therefore, for Pacific hake
+
+$$
+\sigma_{bs} = 10^{TS/10} = 10^{-6.8} L^2
+$$

docs/theory/02_bio_estimates.md

@@ -0,0 +1,141 @@
+# Biological estimates
+
+
+## Number density of scatterers
+
+To obtain the number density of the animal, we define the volume backscattering coefficient ($s_V$, units: m<sup>-1</sup>):
+
+$$
+s_V = \rho_V \left< \sigma_{bs} \right>,
+$$
+
+and its corresponding logarithmic quantity, the volume backscattering strength ($S_V$, units: dB re 1 m<sup>-1</sup>)
+
+$$
+S_V = 10 \log_{10} s_V = 10 \log_{10} \rho_V + 10 \log_{10} \left< \sigma_{bs} \right>
+$$
+
+where $\rho_V$ is the number density of scatterers (fish) per unit volume (units: m<sup>-3</sup>).
+
+In fisheries acoustics, we are often interested in quantities per unit area. Therefore, we define the areal backscattering coefficient (ABC, or $s_a$, units: m<sup>2</sup>m<sup>-2</sup>)
+
+$$
+s_a = s_V H,
+$$
+
+where $H$ is the integration height in meter, and the corresponding nautical areal scattering coefficient ($NASC$, or $s_A$, units: m<sup>2</sup>nmi<sup>-2</sup>)
+
+$$
+NASC = s_A = 4 \pi \times 1852^2 \times s_a,
+$$
+
+in which the conversion of 1 nmi = 1852 m is used.
+
+Using the above quantities, we obtain
+
+$$
+s_a = s_V H = \rho_V \left< \sigma_{bs} \right> H,
+$$
+
+Let the areal number density ($\rho_a$, units: m<sup>-2</sup>) be
+
+$$
+\rho_a = \rho_V H,
+$$
+
+then
+
+$$
+s_a = \rho_a \left< \sigma_{bs} \right>.
+$$
+
+Similarly, with the corresponding nautical areal number density ($\rho_A$, units: nmi<sup>-2</sup>) being
+
+$$
+\rho_A = 1852^2 \rho_a,
+$$
+
+then
+
+$$
+s_A = NASC = \rho_A \left< \sigma_{bs} \right>.
+$$
+
+Note that $NASC$ is the typical output from software packages such as Echoview for biological estimates.
+
+
+
+
+
+## Biomass estimates
+
+We can obtain an estimate of biomass density ($\rho_w$, units: kg nmi<sup>-2</sup>) by multiplying the areal number density of animals by the average weight ($\left< w \right>$, units: kg)
+
+$$
+\rho_w = \rho_A \left< w \right>.
+$$
+
+The average weight is
+
+$$
+\left< w \right> = \frac{\sum_{j=1}^N w_j}{N},
+$$
+
+where $w_j$ is the weight of fish $j$, and $N$ is the total number of fish samples.
+
+In the case when the fish length is binned, which is the case for most fisheries surveys,
+
+$$
+\left< w \right> = \mathbf{L}^\top \mathbf{w}.
+$$
+
+Here, $\mathbf{L}$ is a vector representing the number frequency $L_\ell$ of fish samples in length bin $\ell$
+
+$$
+\mathbf{L} = \begin{bmatrix}
+L_1 \\
+L_2 \\
+L_3 \\
+\vdots
+\end{bmatrix}
+$$
+
+and $\mathbf{w}$ is a vector representing the weight of fish at length $L_\ell$
+
+$$
+\mathbf{w} = \begin{bmatrix}
+w_1 \\
+w_2 \\
+w_3 \\
+\vdots
+\end{bmatrix}.
+$$
+
+Note that the number frequency of fish length is normalized across all length bins, i.e.,
+
+$$
+\sum_\ell L_\ell = 1.
+$$
+
+The $w_\ell$ values can be estimated by the regressed length-weight relationship derived from trawl samples.
+
+With the above quantities, the biomass ($W$, units: kg) can then be estimated by
+
+$$
+W = A \rho_w,
+$$
+
+where $A$ is the unit area associated with the density measure.
+
+<!-- ## Imputation
+
+Let $\hat{i}$ represents the expected strata, $\hat{i}_{\mathrm{miss}} = i$, and $ \hat{i}$ which represents values of $i$ missing from $\hat{i}$
+
+$$
+\bar{\sigma}_{\mathrm{bs}}^{i} = \begin{cases}
+    \bar{\sigma}_{\mathrm{bs}}^{i+1} & \text{if } i = \hat{i}_{\mathrm{min}}  \text{ and } i + 1 \in \hat{i} \\
+    \bar{\sigma}_{\mathrm{bs}}^{i-1} & \text{if } i = \hat{i}_{\mathrm{max}}  \text{ and } i + 1 \in \hat{i} \\
+    \frac{1}{2}(\bar{\sigma}_{\mathrm{bs}}^{i-1} + \bar{\sigma}_{\mathrm{bs}}^{i+1}) & \text{if } i \in \hat{i}_{\mathrm{miss}} \text{ and } (i-1, i+1) \subseteq \hat{i} \\
+    \bar{\sigma}_{\mathrm{bs}}^{i} & \text{if } i \in \hat{i} 
+\end{cases}
+$$ -->

docs/theory/03_stratification.md

@@ -0,0 +1,147 @@
+# Stratification and apportioning of biological estimates
+
+
+## Stratification
+In practice, the acoustic quantities and biological estimates discussed in previous sections can vary depending on geospatial variation of the biological aggregations themselves. For example, the size and age of fish can vary depending on the survey location, as well as the sex of the fish. Therefore, the acoustic measurements and biological samples are typically stratified to account for these variations, and the biomass density is a function of the stratum (which depends on the geospatial locations) and sex, i.e.
+
+$$
+\rho_{w; s} = \rho^i_{w; s}(x,y) = \rho_A(x,y) (\mathbf{L}^i_s)^\top \mathbf{w}^i_s,
+$$
+
+where $i$ is the stratum, $\rho_A(x,y)$ is the nautical areal number density at location $(x, y)$, and $\mathbf{L}^i_s$ and $\mathbf{w}^i_s$ are the vectors characterizing the number frequency of fish length and the corresponding weight in stratum $i$, for fish of sex $s$:
+
+$$
+\mathbf{L}^i_s = \begin{bmatrix}
+L^i_{s,1} \\
+L^i_{s,2} \\
+L^i_{s,3} \\
+\vdots
+\end{bmatrix},
+$$
+
+and
+
+$$
+\mathbf{w}^i_s = \begin{bmatrix}
+w^i_{s,1} \\
+w^i_{s,2} \\
+w^i_{s,3} \\
+\vdots
+\end{bmatrix}.
+$$
+
+
+Note that the number frequency of fish here is normalized across all length bins and sex, i.e., 
+
+$$
+\sum_{s,\ell} L^i_{s,\ell} = 1
+$$
+
+
+### Including age data
+In the case when fish age is measured and binned, the biomass density is a function of the stratum (which depends on the geospatial locations), sex, and age:
+
+$$
+\rho_{w; s,\alpha} = \rho^i_{w; s,\alpha}(x,y) = \rho_A(x,y) (\mathbf{L}^i_{s,\alpha})^\top \mathbf{w}^i_{s,\alpha},
+$$
+
+where $\alpha$ is the age bin,
+
+$$
+\mathbf{L}^i_{s,\alpha} = \begin{bmatrix}
+L^i_{s,\alpha,1} \\
+L^i_{s,\alpha,2} \\
+L^i_{s,\alpha,3} \\
+\vdots
+\end{bmatrix},
+$$
+
+and 
+
+$$
+\mathbf{w}^i_{s,\alpha} = \begin{bmatrix}
+w^i_{s,\alpha,1} \\
+w^i_{s,\alpha,2} \\
+w^i_{s,\alpha,3} \\
+\vdots
+\end{bmatrix}.
+$$
+
+All of $L^i_{s,\alpha,\ell}$ and $w^i_{s,\alpha,\ell}$ vary depending on the stratum $i$, the fish sex $s$, and the age bin $\alpha$.
+
+
+Note that the number frequency of fish length here is normalized across all age bins, length bins, and sex within a stratum, i.e.
+
+$$
+\sum_{s,\ell,\alpha} L^i_{s,\alpha,\ell} = 1
+$$
+
+
+
+## Apportioning of kriged biomass
+
+In Echopop, the kringing procedure interpolates the biomass density $\rho_w$ derived based on $NASC$ to finer grids where acoustic data are not collected. Let $\hat{\rho}_w$ be the kriged biomass density. The biomass of fish of sex $s$, length $\ell$, and age $\alpha$ at the kriging grid $(x_k, y_k)$ can be obtained by
+
+$$
+W_{s,\alpha,\ell}(x_k, y_k) = A(x_k, y_k) \; L^i_{s, \alpha, \ell} \; \hat{\rho}_w(x_k, y_k),
+$$
+
+where $A(x_k, y_k)$ and $\hat{\rho}_w(x_k, y_k)$ are the area and biomass density at the kriging grid $(x_k, y_k)$.
+
+Note that the kriging grids can only be stratified with the INPFC straficiation (see below) based on the grid location, which also determins the stratum $i$ of the grid. The grid stratum in turn determins the number frequency of fish length $L^i_{s, \alpha, \ell}$ used in the apportioning.
+
+
+
+
+<!-- ## Jolly-Hampton (1990) stratified sampling 
+
+Mean density for stratum $i$:
+
+$$
+\hat{ \rho }_{A,B}^{ i } = 
+    \frac{1}{ n^{ i } }
+    \sum\limits_{i=0}^{n^{i} } w^{i,j} \hat{ \rho }_{A,B}^{ i,j,k}
+$$
+
+where $w^{i,j}$ is the transect weight calculated via:
+
+$$
+w^{i,j} = \frac{
+    d(x,y)^{i,j}
+}{
+    \frac{1}{n^{i}}
+    \sum\limits_{j=1}^{n^{i}} d(x,y)^{i,j}
+}
+$$
+
+where $d(x,y)^{i,j}$ is the transect length of $n^{i}$ transects within each stratum. 
+This procedure is then repeated by using the different areas ($A^{i}$) of each stratum to
+weight the final $\hat{ \rho }_{A,B}$ estimate:
+
+$$
+\hat{ \rho }_{A,B} =
+    \frac{
+        \sum\limits_{i} A_{i} \hat{ \rho_{A,B}^{ i } }
+    }{
+        \sum\limits_{i} A_{i}
+    }
+$$ -->
+
+
+
+
+
+## Hake survey specifics
+
+### Stratification
+For Pacific hake, two types of stratifications are used:
+
+- **INPFC**: Stratification set by the International North Pacific Fisheries Commission (INFPC) that is based solely on latitude. The US-Canada bienniel hake survey region encompasses 6 strata.
+- **KS**: Stratification determined based on the Kolomogorov-Smirnov test for differences of the fish length distributions across survey hauls.
+
+### Haul sample measurements
+
+After each haul, the hake samples are processed at two stations:
+
+- Station 1: the length, weight, sex, and age of each fish are measured, and additional tissue samples are collected
+- Station 2: only the length, weight, and sex of each fish are measured