Allow plotting with non-polar stereographic projections (EPSG other than 3031 or 3413)

.github/ISSUE_TEMPLATE/bug_report.md

@@ -29,3 +29,12 @@ PASTE YOUR CODE HERE
 PASTE ERROR MESSAGE HERE
 ```
 <!-- blacken-docs:on -->
+
+**Info on your environment**
+Paste the output of `polartoolkit.Report()` below:
+
+<!-- blacken-docs:off -->
+```
+Paste the output of `polartoolkit.Report()` HERE
+```
+<!-- blacken-docs:on -->

.github/ISSUE_TEMPLATE/release_checklist.md

@@ -13,7 +13,8 @@ assignees: ''
 
 ## Update dependencies
 
-- [ ] Check all the dependency changes since the last release are  reflected in `environment.yml`
+- [ ] Check all the dependency changes since the last release are  reflected in `environment.yml`, `pyproject.toml`, and the Scooby list in `__init__.py`
+- [ ] Check any new function are added to `__init__.py` and `docs/api/polartoolkit.rst`
 - [ ] Update the backup environment file `env/environment.yml` with `make conda_export`
 - [ ] update PolarToolkit version in `environment.yml` in [PolarToolkit-Binder repo](https://github.com/mdtanker/polartoolkit-binder) to the latest version number
 

.gitignore

@@ -165,3 +165,5 @@ data/*
 tmp*
 
 .vscode*
+
+docs/api/generated/

.pre-commit-config.yaml

@@ -21,7 +21,7 @@ repos:
     rev: "v6.0.0"
     hooks:
       - id: check-added-large-files
-        exclude: ^docs/datasets/
+        exclude: ^(docs/datasets/|docs/gallery/masking_and_subsetting_data.ipynb)
       - id: check-case-conflict
       - id: check-merge-conflict
       - id: check-symlinks

Makefile

@@ -45,8 +45,14 @@ clear_how_to:
 run_how_to:
 	jupyter nbconvert --ExecutePreprocessor.allow_errors=True --execute --inplace docs/how_to/*.ipynb
 
-clear_docs: clear_datasets clear_tutorial clear_how_to
+clear_gallery:
+	jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace docs/gallery/*.ipynb
+
+run_gallery:
+	jupyter nbconvert --ExecutePreprocessor.allow_errors=True --execute --inplace docs/gallery/*.ipynb
+
+clear_docs: clear_datasets clear_tutorial clear_how_to clear_gallery
 	jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace docs/*.ipynb
 
-run_docs: run_datasets run_tutorial run_how_to
+run_docs: run_datasets run_tutorial run_how_to run_gallery
 	jupyter nbconvert --ExecutePreprocessor.allow_errors=True --execute --inplace docs/*.ipynb

README.md

@@ -9,7 +9,7 @@
 
 <!-- SPHINX-START-proj-desc -->
 
-**PolarToolkit** (formerly known as Antarctic-Plots) is a Python package to make polar (i.e. Antarctic, Arctic, Greenland) research more efficient, reproducible, and accessible.
+**PolarToolkit** is a Python package to make polar (i.e. Antarctic, Arctic, Greenland) research more efficient, reproducible, and accessible.
 The software does this by providing:
 
 - convenient functions for downloading and pre-processing a wide range of commonly used polar datasets
@@ -69,7 +69,7 @@ Feel free to use, share, modify, and [contribute](contributing.md) to this proje
 ## What _PolarToolkit_ is for:
 
 - download commonly used datasets related to Antarctica, Greenland and the Arctic
-- making publication-quality maps and cross-sections
+- making publication-quality maps and cross-sections, with some limited support outside of polar regions
 - interactively explore data and define geographic regions
 - plotting and working with data in projected coordinates (meters) in either EPSG 3031 or 3413, for the South and North hemispheres, respectively
 - mostly focused on regularly gridded (interpolated) datasets, with some support for discrete (un-gridded) data

docs/api/polartoolkit.rst

@@ -1,50 +1,209 @@
-polartoolkit package
-====================
+.. _api:
+
+API Reference
+=============
 
 .. automodule:: polartoolkit
-   :members:
-   :show-inheritance:
-   :undoc-members:
 
-Submodules
-----------
+.. currentmodule:: polartoolkit
+
+
+Creating maps
+-------------
+These are the core functions for creating maps and plotting data. These functions all
+wrap the Figure class (below) to allow the various Figure methods to be called from a
+single function. They are designed for convenience, so users don't need to call each of
+the Figure methods individually.
+
+.. autosummary::
+    :toctree: generated/
+
+    basemap
+    plot_grid
+    plot_3d
+    subplots
+
+
+Figure class
+------------
+The Figure class and it's methods are the core of the plotting functionality. The Figure
+class is a wrapper around the GMT figure class and adds some useful attributes which
+help with plots which are focused on data in projected units (such as the Polar
+Stereographic projections commonly used in polar research). The methods allow you to
+quick add map elements such as coastlines, gridlines, imagery, inset maps, as well as
+plot gridded and point datasets. The figure instances can be used directly with any
+PyGMT plotting functions.
+
+.. autosummary::
+    :toctree: generated/
+
+   Figure.add_grid
+   Figure.add_points
+   Figure.add_imagery
+   Figure.add_modis
+   Figure.add_coast
+   Figure.add_gridlines
+   Figure.add_colorbar
+   Figure.add_simple_basemap
+   Figure.add_box
+   Figure.add_inset
+   Figure.add_scalebar
+   Figure.add_north_arrow
+   Figure.add_faults
+   Figure.add_geologic_units
+   Figure.add_bed_type
+   Figure.shift_figure
+
+
+Creating profiles
+-----------------
+The following functions are designed to create profiles and crosssections of gridded
+data. Topography data are plotted as colored layers, while other data can be plotted as
+lines. Profiles are defined by a straight line between two points, by a shapefile, or
+by interactively drawing a line on a map.
+
+.. autosummary::
+   :toctree: generated/
+
+   plot_profile
+   plot_data
+   draw_lines
+   shapes_to_df
+   make_data_dict
+   default_data
+   default_layers
+
+Reprojecting
+------------
+These functions are designed to reproject coordinates or data between different
+coordinate reference systems. The functions also include some convenience functions for
+working with EPSG projection codes and GMT projection strings.
+
+.. autosummary::
+   :toctree: generated/
+
+   reproject
+   latlon_to_epsg3031
+   latlon_to_epsg3413
+   epsg3031_to_latlon
+   epsg3413_to_latlon
+   dd2dms
+   default_epsg
+   epsg_central_coordinates
+   gmt_projection_from_epsg
+
+
+Spatial operations
+------------------
+These functions perform various spatial operations on gridded or point data, such as
+resampling, filtering, masking, and calculating statistics.
+
+.. autosummary::
+   :toctree: generated/
+
+   subset_grid
+   sample_grids
+   resample_grid
+   block_reduce
+   change_registration
+   filter_grid
+   get_min_max
+   get_combined_min_max
+   get_grid_info
+   get_grid_region
+   get_grid_registration
+   get_grid_spacing
+   grid_blend
+   grid_compare
+   grid_trend
+   make_grid
+   mask_from_polygon
+   mask_from_shapefile
+   nearest_grid_fill
+   points_inside_region
+   points_inside_shapefile
+   polygon_to_shapefile
+   rmse
+
+Plotting utilities
+------------------
+Here are a few utility functions which can be helpful for plotting.
+
+.. autosummary::
+   :toctree: generated/
+
+   square_subplots
+   set_proj
+   random_color
+   get_fig_height
+   get_fig_width
+   gmt_str_to_list
+
+Interactive functions
+---------------------
+These functions allow you to interactively plot and explore gridded or point data.
+
+.. autosummary::
+   :toctree: generated/
 
-polartoolkit.fetch module
--------------------------
+   interactive_map
+   interactive_data
+   geoviews_points
 
-.. automodule:: polartoolkit.fetch
-   :members:
-   :show-inheritance:
-   :undoc-members:
 
-polartoolkit.maps module
-------------------------
 
-.. automodule:: polartoolkit.maps
-   :members:
-   :show-inheritance:
-   :undoc-members:
+Region utilities
+-------------------
+These utility functions are used for defining and transforming geographic bounding
+regions, which are used throughout PolarToolkit.
 
-polartoolkit.profiles module
-----------------------------
+.. autosummary::
+   :toctree: generated/
 
-.. automodule:: polartoolkit.profiles
-   :members:
-   :show-inheritance:
-   :undoc-members:
+   alter_region
+   combine_regions
+   regions_overlap
+   draw_region
+   polygon_to_region
+   region_xy_to_ll
+   region_ll_to_xy
+   region_to_df
+   region_to_bounding_box
+   square_around_region
 
-polartoolkit.regions module
----------------------------
 
-.. automodule:: polartoolkit.regions
-   :members:
-   :show-inheritance:
-   :undoc-members:
+Download and fetching data
+--------------------------
+These are all the various datasets you can download and fetch with PolarToolkit.
 
-polartoolkit.utils module
--------------------------
+.. autosummary::
+   :toctree: generated/
 
-.. automodule:: polartoolkit.utils
-   :members:
-   :show-inheritance:
-   :undoc-members:
+   polartoolkit.fetch.EarthDataDownloader
+   polartoolkit.fetch.mass_change
+   polartoolkit.fetch.basal_melt
+   polartoolkit.fetch.buttressing
+   polartoolkit.fetch.ice_vel
+   polartoolkit.fetch.modis
+   polartoolkit.fetch.imagery
+   polartoolkit.fetch.antarctic_bed_type
+   polartoolkit.fetch.geomap
+   polartoolkit.fetch.groundingline
+   polartoolkit.fetch.antarctic_boundaries
+   polartoolkit.fetch.sediment_thickness
+   polartoolkit.fetch.ibcso_coverage
+   polartoolkit.fetch.ibcso
+   polartoolkit.fetch.bedmachine
+   polartoolkit.fetch.bedmap_points
+   polartoolkit.fetch.bedmap3
+   polartoolkit.fetch.bedmap2
+   polartoolkit.fetch.rema
+   polartoolkit.fetch.deepbedmap
+   polartoolkit.fetch.gravity
+   polartoolkit.fetch.etopo
+   polartoolkit.fetch.geoid
+   polartoolkit.fetch.magnetics
+   polartoolkit.fetch.ghf
+   polartoolkit.fetch.gia
+   polartoolkit.fetch.crustal_thickness
+   polartoolkit.fetch.moho

docs/conf.py

@@ -7,7 +7,7 @@
 
 extensions = [
     "myst_parser",
-    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
@@ -75,6 +75,7 @@
 always_document_param_types = True
 add_module_names = False
 add_function_parentheses = False
+# toc_object_entries_show_parents = "hide"
 
 
 nbsphinx_execute = "never"

docs/datasets/antarctica/basal_melt.ipynb

@@ -22,19 +22,14 @@
    "execution_count": null,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2025-11-03T13:00:46.635468Z",
-     "iopub.status.busy": "2025-11-03T13:00:46.635099Z",
-     "iopub.status.idle": "2025-11-03T13:02:52.693486Z",
-     "shell.execute_reply": "2025-11-03T13:02:52.691829Z"
+     "iopub.execute_input": "2026-02-07T12:23:00.549056Z",
+     "iopub.status.busy": "2026-02-07T12:23:00.548799Z",
+     "iopub.status.idle": "2026-02-07T12:23:03.290351Z",
+     "shell.execute_reply": "2026-02-07T12:23:03.290017Z"
     }
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
-    "%load_ext autoreload\n",
-    "%autoreload 2\n",
-    "\n",
-    "\n",
     "import polartoolkit as ptk"
    ]
   },
@@ -43,10 +38,10 @@
    "execution_count": null,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2025-11-03T13:02:52.696885Z",
-     "iopub.status.busy": "2025-11-03T13:02:52.696314Z",
-     "iopub.status.idle": "2025-11-03T13:02:55.251722Z",
-     "shell.execute_reply": "2025-11-03T13:02:55.250097Z"
+     "iopub.execute_input": "2026-02-07T12:23:03.291882Z",
+     "iopub.status.busy": "2026-02-07T12:23:03.291674Z",
+     "iopub.status.idle": "2026-02-07T12:23:03.672164Z",
+     "shell.execute_reply": "2026-02-07T12:23:03.671817Z"
     }
    },
    "outputs": [],
@@ -70,10 +65,10 @@
    "execution_count": null,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2025-11-03T13:02:55.254219Z",
-     "iopub.status.busy": "2025-11-03T13:02:55.253955Z",
-     "iopub.status.idle": "2025-11-03T13:02:55.495365Z",
-     "shell.execute_reply": "2025-11-03T13:02:55.493445Z"
+     "iopub.execute_input": "2026-02-07T12:23:03.710020Z",
+     "iopub.status.busy": "2026-02-07T12:23:03.709854Z",
+     "iopub.status.idle": "2026-02-07T12:23:03.793870Z",
+     "shell.execute_reply": "2026-02-07T12:23:03.793522Z"
     }
    },
    "outputs": [],