Merge branch 'mc_bvalue_stability' of https://github.com/swiss-seismo…

…logical-service/SeismoStats into mc_bvalue_stability
swiss-seismological-service · Aug 27, 2024 · 09a19cc · 09a19cc
2 parents 68fb843 + 3284040
commit 09a19cc
Show file tree

Hide file tree

Showing 25 changed files with 764 additions and 256 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -20,7 +20,7 @@ help:
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 server:
-	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) --watch "../seismostats"
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) --watch "../seismostats" --re-ignore "api/.*"
 
 clean:
 	rm -rf $(BUILDDIR)/
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -51,3 +51,4 @@
 html_context = {
     "default_mode": "light",
 }
+suppress_warnings = ['autosectionlabel.*']
diff --git a/docs/source/reference/analysis.md b/docs/source/reference/analysis.md
@@ -4,6 +4,15 @@
 .. currentmodule:: seismostats
 ```
 
+## Estimating the Completeness Magnitude
+```{eval-rst}
+.. autosummary::
+    :toctree: api/
+
+    analysis.mc_ks
+    analysis.mc_max_curvature
+```
+
 ## Estimating b-Values
 
 ```{eval-rst}
@@ -12,7 +21,7 @@
 
     estimate_b
     shi_bolt_confidence
-    analysis.estimate_b_tinti
+    analysis.estimate_b_classic
     analysis.estimate_b_positive
     analysis.estimate_b_more_positive
     analysis.estimate_b_utsu
@@ -21,13 +30,15 @@
     analysis.estimate_b_kijko_smit
 ```
 
-## Estimating the Completeness Magnitude
+## Estimating a-Values
+
 ```{eval-rst}
 .. autosummary::
     :toctree: api/
 
-    analysis.mc_ks
-    analysis.mc_max_curvature
+    estimate_a
+    analysis.estimate_a_classic
+    analysis.estimate_a_positive
 ```
 
 ## Other

diff --git a/docs/source/reference/catalog.md b/docs/source/reference/catalog.md
@@ -1,19 +1,27 @@
-# Catalog
+# Catalog Formats
+Basic formats to store earthquake event data. All Structures are subclassing `pandas.DataFrame`, with additional methods to estimate parameters and convert to other formats.
+
 
 ```{eval-rst}
 .. currentmodule:: seismostats
 ```
 
-## Constructor
+## Catalog
+Simple representation of an earthquake catalog, storing each single event as a row.
+
+(constructor-cat)=
+### Constructor
 
 ```{eval-rst}
 .. autosummary::
     :toctree: api/
 
     Catalog
+    Catalog.from_quakeml
+    Catalog.from_dict
 ```
 
-## Modify Catalog
+### Modify Catalog
 
 ```{eval-rst}
 .. autosummary::
@@ -25,7 +33,7 @@
     Catalog.drop_uncertainties
 ```
 
-## Estimate from Catalog
+### Estimate from Catalog
 
 ```{eval-rst}
 .. autosummary::
@@ -35,13 +43,72 @@
     Catalog.estimate_mc
 ```
 
-## Transform from or to other format
+(convert-cat)=
+### Convert to other format
 
 ```{eval-rst}
 .. autosummary::
     :toctree: api/
 
     Catalog.to_quakeml
-    Catalog.from_quakeml
-    Catalog.from_dict
+```
+
+## ForecastCatalog
+Subclass of {ref}`/reference/catalog.md#catalog`, storing events from `n_catalogs` number of forecasted catalogs, distinguished by the `catalog_id` column. Holds additional methods to work with this data structure.
+
+(constructor-fc)=
+### Constructor
+
+```{eval-rst}
+.. autosummary::
+    :toctree: api/
+
+    ForecastCatalog
+```
+
+(convert-fc)=
+### Convert to Other Format
+
+```{eval-rst}
+.. autosummary::
+    :toctree: api/
+
+    ForecastCatalog.to_quakeml
+```
+
+## GRRateGrid
+Subclass of `pandas.DataFrame`, storing the Gutenberg-Richter rate values for a spatial grid. Holds additional methods to work with this data structure.
+
+(constructor-grrg)=
+### Constructor
+
+```{eval-rst}
+.. autosummary::
+    :toctree: api/
+
+    GRRateGrid
+```
+
+### Modify GRRateGrid
+
+```{eval-rst}
+.. autosummary::
+    :toctree: api/
+
+    GRRateGrid.strip
+    GRRateGrid.add_time_index
+    GRRateGrid.reindex_cell_id
+```
+
+## ForecastGRRateGrid
+Subclass of {ref}`/reference/catalog.md#grrategrid`, storing the Gutenberg-Richter rate values for a `n_grids` number of forecasted grids, distinguished by the `grid_id` column. Holds additional methods to work with this data structure.
+
+(constructor-fgrrg)=
+### Constructor
+
+```{eval-rst}
+.. autosummary::
+    :toctree: api/
+
+    ForecastGRRateGrid
 ```
diff --git a/docs/source/reference/utils.md b/docs/source/reference/utils.md
@@ -29,19 +29,26 @@
 
 ## Coordinates
 
+### Spatial Transformations
 ```{eval-rst}
 .. autosummary::
     :toctree: api/
 
-    utils.CoordinateTransformer
-    [//]: <> utils.CoordinateTransformer.to_local_coords
-    [//]: <> utils.CoordinateTransformer.from_local_coords
-    [//]: <> utils.CoordinateTransformer.polygon_from_local_coords
-    [//]: <> utils.CoordinateTransformer.polygon_to_local_coords
     utils.bounding_box_to_polygon
     utils.polygon_to_bounding_box
 
 ```
+### Coordinate Transformer
+```{eval-rst}
+.. autosummary::
+    :toctree: api/
+    
+    utils.CoordinateTransformer
+    utils.CoordinateTransformer.to_local_coords
+    utils.CoordinateTransformer.from_local_coords
+    utils.CoordinateTransformer.polygon_from_local_coords
+    utils.CoordinateTransformer.polygon_to_local_coords
+```
 
 ## Spatial Filtering
 

diff --git a/docs/source/user/docs.md b/docs/source/user/docs.md
@@ -72,13 +72,13 @@ How to reference a section in the documentation.
 
 **Code**
 ```
-Using a custom name:            {ref}`Reference <reference/catalog:transformation>`  
-Using the title of the section: {ref}`/reference/catalog.md#transformation`  
+Using a custom name:            {ref}`Reference <reference/catalog:modify catalog>`  
+Using the title of the section: {ref}`/reference/catalog.md#modify-catalog`  
 ```
 
 **Output**  
-Using a custom name: {ref}`Reference <reference/catalog:transformation>`  
-Using the title of the section: {ref}`/reference/catalog.md#transformation`  
+Using a custom name: {ref}`Reference <reference/catalog:modify catalog>`  
+Using the title of the section: {ref}`/reference/catalog.md#modify-catalog`  
 
 #### Function / Class
 How to reference a function or class in the documentation.
@@ -113,7 +113,54 @@ def _example():
 **Output**  
 ```{eval-rst}
 .. module:: seismostats.utils.docs
+    :noindex:
 ```
 ```{eval-rst}
 .. autofunction:: _example
 ```
+
+### Add Mathematical Equations
+Mathematical expressions can be added to the documentation using LaTeX. 
+The expressions can be added in text or in docstrings.
+
+
+#### In Text
+
+**Code**
+```
+$$
+\frac{\partial u}{\partial t}=-u \frac{\partial u}{\partial x}- \\
+v \frac{\partial u}{\partial y}-w \frac{\partial u}{\partial z}
+$$
+```
+
+**Output**
+$$
+\frac{\partial u}{\partial t}=-u \frac{\partial u}{\partial x}- \\
+v \frac{\partial u}{\partial y}-w \frac{\partial u}{\partial z}
+$$
+
+
+#### In Docstrings
+
+**Code**
+```python
+def _math():
+    """
+    This function is purely used as an example for the documentation.
+
+    Formulas inside docstrings can be used like this 
+    :math:`\\frac{\\partial u}{\\partial t} = 1`. Note that backslashes 
+    need to be escaped by doubling them up.
+    """
+    pass
+```
+
+**Output**  
+```{eval-rst}
+.. module:: seismostats.utils.docs
+    :noindex:
+```
+```{eval-rst}
+.. autofunction:: _math
+```
diff --git a/seismostats/__init__.py b/seismostats/__init__.py
@@ -4,23 +4,19 @@
 
 # analysis
 from seismostats.analysis.estimate_beta import estimate_b, shi_bolt_confidence
+from seismostats.analysis.estimate_a import estimate_a
 
+# seismicity
+from seismostats.catalogs.catalog import Catalog, ForecastCatalog
+from seismostats.catalogs.rategrid import ForecastGRRateGrid, GRRateGrid
 # plots
-from seismostats.plots.basics import (
-    plot_cum_count,
-    plot_cum_fmd,
-    plot_fmd,
-    plot_mags_in_time,
-)
+from seismostats.plots.basics import (plot_cum_count, plot_cum_fmd, plot_fmd,
+                                      plot_mags_in_time)
 from seismostats.plots.seismicity import plot_in_space
 from seismostats.plots.statistical import plot_mc_vs_b
-
-# seismicity
-from seismostats.seismicity.catalog import Catalog, ForecastCatalog
-from seismostats.seismicity.rategrid import ForecastGRRateGrid, GRRateGrid
 from seismostats.utils._config import get_option, set_option
-
 # utils
 from seismostats.utils.binning import bin_to_precision
 from seismostats.utils.filtering import cat_intersect_polygon
-from seismostats.utils.simulate_distributions import simulate_magnitudes
+from seismostats.utils.simulate_distributions import (
+    simulate_magnitudes, simulate_magnitudes_binned)
diff --git a/seismostats/analysis/__init__.py b/seismostats/analysis/__init__.py
@@ -3,7 +3,7 @@
 from seismostats.analysis.estimate_beta import (estimate_b_kijko_smit,
                                                 estimate_b_laplace,
                                                 estimate_b_positive,
-                                                estimate_b_tinti,
+                                                estimate_b_classic,
                                                 estimate_b_utsu,
                                                 estimate_b_weichert,
                                                 estimate_b_kijko_smit,
@@ -13,3 +13,4 @@
                                                 b_value_to_beta
                                                 )
 from seismostats.analysis.estimate_mc import mc_ks, mc_max_curvature
+from seismostats.analysis.estimate_a import estimate_a_positive, estimate_a_classic