Improve docs and readme (#93)

.pre-commit-config.yaml

@@ -20,4 +20,9 @@ repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v2.3.0
   hooks:
-  -   id: check-yaml
+  -   id: check-yaml
+- repo: https://github.com/kynan/nbstripout
+  rev: 0.5.0
+  hooks:
+    - id: nbstripout
+      files: ^docs/

README.md

@@ -52,49 +52,55 @@ Note: Craterpy is not a crater detection algorithm (e.g. [PyCDA](https://github.
 
 ## Quickstart
 
-Install with `pip install craterpy` then follow the full worked example in the docs [Getting Started](https://craterpy.readthedocs.io/latest/getting_started.html).
+Install with `pip install craterpy` then see example usage at [Getting Started](https://craterpy.readthedocs.io/latest/getting_started.html).
 
 ## Demo
 
 Quickly import tabluar crater data from a CSV and visualize it on a geotiff in 2 lines of code:
 
 ```python
-from craterpy import CraterDatabase, sample_data
+from craterpy import CraterDatabase, sample_data as sd
 
-cdb = CraterDatabase(sample_data['vesta_craters.csv'], 'Vesta', units='m')
-cdb.plot(sample_data['vesta.tif'], alpha=0.5, color='tab:green')
+cdb = CraterDatabase(sd['vesta_craters_km.csv'], 'Vesta', units='km')
+cdb.plot(sd['vesta.tif'], alpha=0.5, color='tab:green', savefig='readme_vesta_cdb.png')
 ```
 
 ![Vesta map plot](https://github.com/cjtu/craterpy/raw/main/docs/_images/readme_vesta_cdb.png)
 
 Clip and plot targeted regions around each crater from large raster datasets.
 
 ```python
-cdb.add_circles('crater_rois', 3)
-cdb.plot_rois(sample_data['vesta.tif'], 'crater_rois', range(1500, 1503))
+cdb.add_circles('crater_roi', 1.5)
+cdb.plot_rois(sd['vesta.tif'], 'crater_roi', range(3, 12))
 ```
 
 ![Vesta plot rois](https://github.com/cjtu/craterpy/raw/main/docs/_images/readme_vesta_rois.png)
 
 Extract zonal statistics for crater regions of interest.
 
 ```python
-# Import lunar crater and define the floor and rim
-cdb = CraterDatabase(sample_data['moon_craters.csv'], 'Moon', units='km')
-cdb.add_annuli("floor", 0.4, 0.8)  # Crater floor (exclude central peak and rim)
-cdb.add_annuli("rim", 0.9, 1.1)  # Thin annulus at crater rim
-
-# Compute summary statistics for every ROI see docs for supported stats
-stats = cdb.get_stats(sample_data['moon_dem.tif'], regions=['floor', 'rim'], stats=['median'])
-
-# Compute crater depth as rim elevation - floor elevation
-stats['depth (m)'] = (stats.median_rim - stats.median_floor)
-print(stats.head(3).round(2))
-
-# Name     Rad      Lat     Lon     median_floor  median_rim  depth (m)
-# Olbers D  50.015  10.23  -78.03      -1452.50    -1322.88     129.62
-# Schuster   50.04   4.44  146.42        445.58     1976.97    1531.39
-# Gilbert  50.125  -3.20   76.16      -2213.66     -731.64    1482.02
+import pandas as pd
+from craterpy import CraterDatabase, sample_data as sd
+df = df = pd.read_csv(sd["moon_craters_km.csv"])
+cdb = CraterDatabase(df[df["Diameter (km)"] < 60], "Moon", units="km")
+
+# Define regions for crater floor, rim (sizes in crater radii)
+cdb.add_annuli("floor", 0.4, 0.6)  # crater floor, excluding possible central peak
+cdb.add_annuli("rim", 0.99, 1.01)  # thin annulus at rim
+
+# Pull statistics from a Lunar Digital Elevation Model (DEM) GeoTiff
+stats = cdb.get_stats(sd["moon_dem.tif"], regions=['floor', 'rim'], stats=['mean'])
+
+# Use mean elevations to compute depth (rim to floor)
+stats['crater_depth (m)'] = (stats.mean_rim - stats.mean_floor)
+print(stats.head().to_string(float_format='%.1f', index=False))
+
+#  Diameter (km)  Latitude  Longitude  mean_floor  mean_rim  crater_depth (m)
+#           60.0      19.4     -146.5      6070.0   10792.9            4722.9
+#           60.0      44.2      145.3      -976.4    3114.0            4090.4
+#           60.0     -43.6       -7.5     -3617.5     186.8            3804.4
+#           60.0      -9.6      134.7      1843.4    6127.9            4284.4
+#           59.9     -25.3        2.4     -2634.2    -945.0            1689.1
 ```
 
 ## Documentation

craterpy/classes.py

@@ -319,8 +319,7 @@ def plot(
 
         Returns
         -------
-        ax : matplotlib.Axes
-            Original axes, now with data plotted.
+        ax : matplotlib.Axes, cartopy.mpl.geoaxes.GeoAxes
         """
         ellipsoid = ccrs.CRS(self._crs).ellipsoid
         globe = ccrs.Globe(

craterpy/helper.py

@@ -174,8 +174,6 @@ def greatcircdist(lat1, lon1, lat2, lon2, radius):
 
     Examples
     --------
-    .. code-block:: doctest
-
         >>> greatcircdist(36.12, -86.67, 33.94, -118.40, 6372.8)
         2887.259950607111
 
@@ -209,8 +207,6 @@ def inglobal(lat, lon):
 
     Examples
     --------
-    .. code-block:: doctest
-
         >>> inglobal(0, 0)
         True
         >>> inglobal(91, 0)
@@ -557,8 +553,6 @@ def findcol(df, names, exact=False):
 
     Examples
     --------
-    .. code-block:: doctest
-
         >>> df = pd.DataFrame({'Lat': [10, -20., 80.0],
                             'Lon': [14, -40.1, 317.2],
                             'Diam': [2, 12., 23.7]})
@@ -640,8 +634,6 @@ def latlon_to_cartesian(lat, lon, radius):
 
     Examples
     --------
-    .. code-block:: doctest
-
         >>> latlon_to_cartesian(0, 0, 1)
         (1.0, 0.0, 0.0)
 

docs/source/api.md

@@ -1,24 +1,23 @@
 # Craterpy API Documentation
 
-## The CraterDatabase
+## CraterDatabase
 
 ```{eval-rst}
 .. autoclass:: craterpy.classes.CraterDatabase
     :members:
 ```
-<!-- TODO: update plotting and helper docs
-## Plotting module
+
+## CRS handling
 
 ```{eval-rst}
-.. automodule:: craterpy.plotting
+.. automodule:: craterpy.crs
     :members:
-    :undoc-members:
 ```
 
-## Helper functions
+## Helper
 
 ```{eval-rst}
 .. automodule:: craterpy.helper
     :members:
     :undoc-members:
-``` -->
+```