docs: update documentation main page (#49)

* docs: update documentation main page

docs: use bibtex for citations
docs: move notebooks to be within docs

* fix: reset execution counts

* Update IS2-ATL15-Viewer.ipynb

IS2view/api.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 api.py
-Written by Tyler Sutterley (06/2024)
+Written by Tyler Sutterley (01/2025)
 Plotting tools for visualizing rioxarray variables on leaflet maps
 
 PYTHON DEPENDENCIES:
@@ -28,6 +28,8 @@
         https://xyzservices.readthedocs.io/en/stable/
 
 UPDATE HISTORY:
+    Updated 01/2025: added more zoom levels and update max_zoom
+        deprecation update for writing the crs to the dataset object
     Updated 06/2024: use wrapper to importlib for optional dependencies
     Updated 04/2024: add connections and functions for changing variables
         and other attributes of the leaflet map visualization
@@ -104,7 +106,15 @@
         2048.0,
         1024.0,
         512.0,
-        256.0
+        256.0,
+        128.0,
+        64.0,
+        32.0,
+        16.0,
+        8.0,
+        4.0,
+        2.0,
+        1.0
     ],
     bounds=[
         [-4194304, -4194304],
@@ -124,7 +134,15 @@
         2048.0,
         1024.0,
         512.0,
-        256.0
+        256.0,
+        128.0,
+        64.0,
+        32.0,
+        16.0,
+        8.0,
+        4.0,
+        2.0,
+        1.0
     ],
     bounds=[
         [-4194304, -4194304],
@@ -288,7 +306,7 @@ def __init__(self, projection, **kwargs):
                 ipyleaflet.basemaps.NASAGIBS.BlueMarble3413
             )
             self.map = ipyleaflet.Map(center=kwargs['center'],
-                zoom=kwargs['zoom'], max_zoom=5,
+                zoom=kwargs['zoom'], max_zoom=15,
                 attribution_control=kwargs['attribution'],
                 basemap=kwargs['basemap'],
                 crs=projections['EPSG:3413'],
@@ -300,7 +318,7 @@ def __init__(self, projection, **kwargs):
                 ipyleaflet.basemaps.NASAGIBS.BlueMarble3031
             )
             self.map = ipyleaflet.Map(center=kwargs['center'],
-                zoom=kwargs['zoom'], max_zoom=5,
+                zoom=kwargs['zoom'], max_zoom=15,
                 attribution_control=kwargs['attribution'],
                 basemap=kwargs['basemap'],
                 crs=projections['EPSG:3031'],
@@ -924,15 +942,15 @@ def get_crs(self):
         except Exception as exc:
             pass
         else:
-            self._ds.rio.set_crs(ds_crs)
+            self._ds.rio.write_crs(ds_crs)
             return
         # get coordinate reference system from crs attribute
         try:
             ds_crs = self._ds.rio.crs.to_wkt()
         except Exception as exc:
             pass
         else:
-            self._ds.rio.set_crs(ds_crs)
+            self._ds.rio.write_crs(ds_crs)
             return
         # raise exception
         raise Exception('Unknown coordinate reference system')
@@ -1259,7 +1277,7 @@ def handle_click(self, **kwargs):
         except Exception as exc:
             crs = self._ds.rio.crs.to_wkt()
         else:
-            self._ds.rio.set_crs(crs)
+            self._ds.rio.write_crs(crs)
         # get the clicked point in dataset coordinate reference system
         x, y = rio.warp.transform('EPSG:4326', crs, [lon], [lat])
         # find nearest point in dataset
@@ -1547,15 +1565,15 @@ def get_crs(self):
         except Exception as exc:
             pass
         else:
-            self._ds.rio.set_crs(ds_crs)
+            self._ds.rio.write_crs(ds_crs)
             return
         # get coordinate reference system from crs attribute
         try:
             ds_crs = self._ds.rio.crs.to_wkt()
         except Exception as exc:
             pass
         else:
-            self._ds.rio.set_crs(ds_crs)
+            self._ds.rio.write_crs(ds_crs)
             return
         # raise exception
         raise Exception('Unknown coordinate reference system')
@@ -1969,15 +1987,15 @@ def get_crs(self):
         except Exception as exc:
             pass
         else:
-            self._ds.rio.set_crs(ds_crs)
+            self._ds.rio.write_crs(ds_crs)
             return
         # get coordinate reference system from crs attribute
         try:
             ds_crs = self._ds.rio.crs.to_wkt()
         except Exception as exc:
             pass
         else:
-            self._ds.rio.set_crs(ds_crs)
+            self._ds.rio.write_crs(ds_crs)
             return
         # raise exception
         raise Exception('Unknown coordinate reference system')

IS2view/tools.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 tools.py
-Written by Tyler Sutterley (11/2023)
+Written by Tyler Sutterley (01/2025)
 User interface tools for Jupyter Notebooks
 
 PYTHON DEPENDENCIES:
@@ -13,8 +13,12 @@
     matplotlib: Python 2D plotting library
         http://matplotlib.org/
         https://github.com/matplotlib/matplotlib
+    cmocean: Beautiful colormaps for oceanography
+        https://matplotlib.org/cmocean/
 
 UPDATE HISTORY:
+    Updated 01/2025: added optional cmocean colormaps to dropdown menu
+        updated the default group list to include lags for release 004
     Updated 06/2024: use wrapper to importlib for optional dependencies
     Updated 11/2023: set time steps using decimal years rather than lags
         setting dynamic colormap with float64 min and max
@@ -34,6 +38,7 @@
 # attempt imports
 ipywidgets = import_dependency('ipywidgets')
 cm = import_dependency('matplotlib.cm')
+cmocean = import_dependency('cmocean')
 
 # set environmental variable for anonymous s3 access
 os.environ['AWS_NO_SIGN_REQUEST'] = 'YES'
@@ -131,7 +136,8 @@ def __init__(self, **kwargs):
 
         # dropdown menu for selecting group to read from file
         # use Release-01 groups as the initial default
-        group_list = ['delta_h', 'dhdt_lag1', 'dhdt_lag4', 'dhdt_lag8']
+        group_list = ['delta_h', 'dhdt_lag1', 'dhdt_lag4', 'dhdt_lag8',
+            'dhdt_lag12', 'dhdt_lag16', 'dhdt_lag20']
         self.group = ipywidgets.Dropdown(
             options=group_list,
             description='Group:',
@@ -240,9 +246,17 @@ def __init__(self, **kwargs):
             cmap_list.extend(val)
         # reduce colormaps to available in program and matplotlib
         cmap_set &= set(cmap_list)
+        cmap_options = sorted(cmap_set)
+        # attempt to add additional colormaps
+        ext_cmaps = []
+        try:
+            ext_cmaps.extend([f'cmo.{c}' for c in sorted(cmocean.cm.cmapnames)])
+        except Exception as exc:
+            pass
+        cmap_options.extend(ext_cmaps)
         # dropdown menu for setting colormap
         self.cmap = ipywidgets.Dropdown(
-            options=sorted(cmap_set),
+            options=cmap_options,
             value='viridis',
             description='Colormap:',
             description_tooltip=("Colormap: matplotlib colormaps "
@@ -383,11 +397,13 @@ def set_groups(self, *args):
         """sets the list of available groups for a release
         """
         group_list = ['delta_h', 'dhdt_lag1', 'dhdt_lag4', 'dhdt_lag8']
-        # append lag12 group
+        # append additional dhdt groups
         if (int(self.release.value) > 1):
             group_list.append('dhdt_lag12')
         if (int(self.release.value) > 2):
             group_list.append('dhdt_lag16')
+        if (int(self.release.value) > 3):
+            group_list.append('dhdt_lag20')
         # set group list
         self.group.options = group_list
         # change regions for Antarctica for Release-03+
@@ -457,13 +473,17 @@ def get_variables(self, d):
         """
         # data and time variables
         self.data_vars = sorted(d.data_vars)
-        self.time_vars = d.time.values if 'time' in d else None
-        # set the default groups
-        self.set_groups()
-        # set the default variables
-        self.set_variables()
-        # set the default time steps
-        self.set_time_steps()
+        if 'time' in d:
+            self.time_vars = d.time.values
+            # set the default groups
+            self.set_groups()
+            # set the default variables
+            self.set_variables()
+            # set the default time steps
+            self.set_time_steps()
+        else:
+            # set the default variables
+            self.set_variables()
 
     def set_time_steps(self, *args, epoch=2018.0):
         """sets available time range

doc/environment.yml

@@ -5,14 +5,17 @@ dependencies:
   - docutils
   - graphviz
   - ipywidgets
+  - myst-nb
   - notebook
   - numpy>=1.21
   - numpydoc
   - pip
   - python>=3.6
   - sphinx
+  - sphinx-argparse>=0.4
+  - sphinxcontrib-bibtex
+  - sphinx-design
   - sphinx_rtd_theme
   - xarray
   - pip:
-    - sphinx-argparse>=0.4
     - ..

doc/source/_assets/is2view-refs.bib

@@ -0,0 +1,61 @@
+@manual{Smith:2023jg, 
+year = {2023}, 
+author = {Smith, B. and Adusumilli, Susheel and Csatho, Beata and Felikson, Denis and Fricker, Helen and Gardner, Alex and Holschuh, Nicholas and Lee, Jeffrey and Nilson, Johan and Paolo, Fernando and Siegfried, Matthew and Sutterley, Tyler and {the ICESat-2 Science Team}}, 
+title = {{ATLAS/ICESat-2 L3A Land Ice Height. (ATL06, Version 6)}}, 
+doi = {10.5067/ATLAS/ATL06.006}, 
+url = {https://doi.org/10.5067/ATLAS/ATL06.006}, 
+organization = {NASA National Snow and Ice Data Center Distributed Active Archive Center},
+address = {Boulder, Colorado USA}
+}
+
+@manual{Smith:2023fd,
+author = {Smith, B. and Dickinson, S. and Jelley, B. P. and Neumann, T. A. and Hancock, D. and Lee, J. and Harbeck, K.},
+title = {{ATLAS/ICESat-2 L3B Slope-Corrected Land Ice Height Time Series}},
+organization = {NASA National Snow and Ice Data Center Distributed Active Archive Center},
+year = {2024},
+note = {Version 4},
+address = {Boulder, Colorado USA},
+publisher = {NASA National Snow and Ice Data Center Distributed Active Archive Center},
+doi = {10.5067/ATLAS/ATL11.006},
+url = {https://doi.org/10.5067/ATLAS/ATL11.006}
+}
+
+@manual{Smith:2024fd,
+author = {Smith, B. and Sutterley, T. C. and Dickinson, S. and Jelley, B. P. and Felikson, D. and Neumann, T. A. and Fricker, H. A. and Gardner, A. and Padman, L. and Markus, T and Kurtz, N. and Bhardwaj, S. and Hancock, D. and Lee, J.},
+title = {{ATLAS/ICESat-2 L3B Antarctic and Arctic Land Ice Height Change}},
+organization = {NASA National Snow and Ice Data Center Distributed Active Archive Center},
+year = {2024},
+note = {Version 4},
+address = {Boulder, Colorado USA},
+publisher = {NASA National Snow and Ice Data Center Distributed Active Archive Center},
+doi = {10.5067/ATLAS/ATL14.004},
+url = {https://doi.org/10.5067/ATLAS/ATL14.004}
+}
+
+@manual{Smith:2024cv,
+author = {Smith, B. and Sutterley, T. C. and Dickinson, S. and Jelley, B. P. and Felikson, D. and Neumann, T. A. and Fricker, H. A. and Gardner, A. and Padman, L. and Markus, T and Kurtz, N. and Bhardwaj, S. and Hancock, D. and Lee, J.},
+title = {{ATLAS/ICESat-2 L3B Gridded Antarctic and Arctic Land Ice Height Change}},
+organization = {NASA National Snow and Ice Data Center Distributed Active Archive Center},
+year = {2024},
+note = {Version 4},
+address = {Boulder, Colorado USA},
+publisher = {NASA National Snow and Ice Data Center Distributed Active Archive Center},
+doi = {10.5067/ATLAS/ATL15.004},
+url = {https://doi.org/10.5067/ATLAS/ATL15.004}
+}
+
+@manual{Smith:2024vr,
+author = {Smith, B. and Jelley, B. and Sutterley, T. C. and Dickinson, S.},
+title = {{ATL1415 [Computer software]}}, 
+year = {2024},
+organization={GitHub}, 
+url={https://www.github.com/SmithB/ATL1415}
+}
+
+@manual{Smith:2024ut,
+author = {Smith, B.},
+title = {{altimetryFit [Computer software]}}, 
+year = {2024},
+organization={GitHub}, 
+url={https://www.github.com/SmithB/altimetryFit}
+}

doc/source/conf.py

@@ -16,6 +16,9 @@
 # sys.path.insert(0, os.path.abspath('.'))
 import importlib.metadata
 
+
+# -- Project information -----------------------------------------------------
+
 # package metadata
 metadata = importlib.metadata.metadata("IS2view")
 project = metadata["Name"]
@@ -35,13 +38,23 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx.ext.autodoc",
+    "myst_nb",
     "numpydoc",
+    'sphinxcontrib.bibtex',
+    "sphinx.ext.autodoc",
     "sphinx.ext.graphviz",
     "sphinx.ext.viewcode",
+    "sphinx_design",
     "sphinxarg.ext"
 ]
 
+# use myst for notebooks
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".ipynb": "myst-nb",
+}
+nb_execution_mode = "off"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -59,6 +72,8 @@
 autodoc_member_order = 'bysource'
 numpydoc_show_class_members = False
 pygments_style = 'native'
+bibtex_bibfiles = ['_assets/is2view-refs.bib']
+bibtex_default_style = 'plain'
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -81,7 +96,14 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_logo = "_assets/IS2view_logo.png"
 html_static_path = ['_static']
-repository_url = f"https://github.com/tsutterley/IS2view"
+# fetch the project urls
+project_urls = {}
+for project_url in metadata.get_all('Project-URL'):
+    name, _, url = project_url.partition(', ')
+    project_urls[name.lower()] = url
+# fetch the repository url
+repository_url = project_urls.get('repository')
+# add html context
 html_context = {
     "menu_links": [
         (
@@ -92,6 +114,10 @@
             '<i class="fa fa-book fa-fw"></i> License',
             f"{repository_url}/blob/main/LICENSE",
         ),
+        (
+            '<i class="fa fa-comment fa-fw"></i> Discussions',
+            f"{repository_url}/discussions",
+        ),
     ],
 }
 

doc/source/getting_started/Bibliography.rst

@@ -0,0 +1,5 @@
+============
+Bibliography
+============
+
+.. bibliography::