375 update main readme and seafloorgridsipynb

Notebooks/06-Rasters.ipynb

@@ -376,14 +376,15 @@
     "reverse_reconstructed = reconstructed.reconstruct(0, fill_value=\"white\", threads=4)\n",
     "\n",
     "# plot\n",
-    "fig, axs = plt.subplots(3, 1, figsize=(8, 12), subplot_kw={\"projection\": ccrs.Mollweide(central_longitude=0)})\n",
-    "etopo.imshow(ax=axs[0])\n",
-    "reconstructed.imshow(ax=axs[1])\n",
-    "reverse_reconstructed.imshow(ax=axs[2])\n",
-    "\n",
-    "axs[0].set_title(\"Original image (present day)\")\n",
-    "axs[1].set_title(\"Reconstructed to 50 Ma\")\n",
-    "axs[2].set_title(\"Reverse reconstructed back to present day\")\n",
+    "fig, axs = plt.subplots(2, 2, figsize=(12, 6), subplot_kw={\"projection\": ccrs.Mollweide(central_longitude=0)})\n",
+    "etopo.imshow(ax=axs[0][0])\n",
+    "reconstructed.imshow(ax=axs[0][1])\n",
+    "reverse_reconstructed.imshow(ax=axs[1][0])\n",
+    "axs[1][1].set_visible(False)\n",
+    "\n",
+    "axs[0][0].set_title(\"Original image (present day)\")\n",
+    "axs[0][1].set_title(\"Reconstructed to 50 Ma\")\n",
+    "axs[1][0].set_title(\"Reverse reconstructed back to present day\")\n",
     "plt.show()"
    ]
   },

Notebooks/10-SeafloorGrids.ipynb

@@ -9,6 +9,10 @@
     "\n",
     "An adaptation of [agegrid-01](https://github.com/siwill22/agegrid-0.1) written by Simon Williams, Nicky Wright and John Cannon for gridding general z-values onto seafloor basin points using GPlately.\n",
     "\n",
+    "This notebook demonstrates how to generate seafloor age and spreading-rate grids through time. The figure below, generated by this notebook, shows seafloor age and spreading rates at 200 Ma. You may adjust the time parameter to generate grids at different geological times.\n",
+    "\n",
+    "![Figure: age-and-spreading-rate-200ma.png](https://raw.githubusercontent.com/GPlates/gplately/refs/heads/master/Notebooks/NotebookFiles/age-and-spreading-rate-200ma.png)\n",
+    "\n",
     "### Citation:\n",
     "Simon Williams, Nicky M. Wright, John Cannon, Nicolas Flament, R. Dietmar Müller, Reconstructing seafloor age distributions in lost ocean basins, Geoscience Frontiers, Volume 12, Issue 2, 2021, Pages 769-780, ISSN 1674-9871,\n",
     "https://doi.org/10.1016/j.gsf.2020.06.004."
@@ -23,7 +27,6 @@
    "source": [
     "import gplately\n",
     "\n",
-    "import pygplates\n",
     "import glob, os\n",
     "import matplotlib.pyplot as plt\n",
     "import cartopy.crs as ccrs\n",
@@ -36,7 +39,7 @@
    "metadata": {},
    "source": [
     "### Define a rotation model, topology features and continents for the `PlateReconstruction` model\n",
-    "There are two ways to do this. To use local files, pass `use_local_files = True`. To use gplately's `PlateModelManager`, use `use_local_files = False`."
+    "There are two ways to do this. To use local files, set `use_local_files = True`. To use `PlateModelManager`, set `use_local_files = False`."
    ]
   },
   {
@@ -66,34 +69,38 @@
    "source": [
     "if use_local_files:\n",
     "    # Method 1: manually point to files\n",
-    "    input_directory = \"/Users/laurenilano/Downloads/SM2-Merdith_et_al_1_Ga_reconstruction_v1.1\"\n",
-    "    rotation_filenames = glob.glob(os.path.join(input_directory, '*.rot'))\n",
-    "    rotation_model = pygplates.RotationModel(rotation_filenames)\n",
-    "\n",
+    "    # you can download the model files at \n",
+    "    # https://www.earthbyte.org/webdav/ftp/Data_Collections/Merdith_etal_2021_ESR/SM2-Merdith_et_al_1_Ga_reconstruction_v1.2.4.zip\n",
+    "    input_directory = \"./SM2-Merdith_et_al_1_Ga_reconstruction_v1.2.4\"\n",
+    "    \n",
+    "    rotation_model = glob.glob(os.path.join(input_directory, '*.rot'))\n",
     "    static_polygons = input_directory+\"/shapes_static_polygons_Merdith_et_al.gpml\"\n",
-    "\n",
-    "    topology_filenames = [\n",
+    "    topology_features = [\n",
     "        input_directory+\"/250-0_plate_boundaries_Merdith_et_al.gpml\",\n",
     "        input_directory+\"/410-250_plate_boundaries_Merdith_et_al.gpml\",\n",
     "        input_directory+\"/1000-410-Convergence_Merdith_et_al.gpml\",\n",
     "        input_directory+\"/1000-410-Divergence_Merdith_et_al.gpml\",\n",
     "        input_directory+\"/1000-410-Topologies_Merdith_et_al.gpml\",\n",
-    "        input_directory+\"/1000-410-Transforms_Merdith_et_al.gpml\"\n",
+    "        input_directory+\"/1000-410-Transforms_Merdith_et_al.gpml\",\n",
+    "        input_directory+\"/TopologyBuildingBlocks_Merdith_et_al.gpml\"\n",
     "        ]\n",
-    "    topology_features = pygplates.FeatureCollection()\n",
-    "    for topology_filename in topology_filenames:\n",
-    "        topology_features.add( pygplates.FeatureCollection(topology_filename) )\n",
-    "            \n",
+    "    \n",
+    "    continents = input_directory+\"/shapes_continents.gpml\"\n",
+    "    coastlines = input_directory+\"/shapes_coastlines_Merdith_et_al_v2.gpmlz\"\n",
+    "    COBs =  None\n",
     "\n",
-    "    continents = input_directory+\"/shapes_continents_Merdith_et_al.gpml\""
+    "    from pathlib import Path\n",
+    "    if not Path(input_directory).is_dir():\n",
+    "        raise FileNotFoundError(f\"The input directory does not exist: {input_directory}. Ensure your files are in the correct locations or download the example input files at https://www.earthbyte.org/webdav/ftp/Data_Collections/Merdith_etal_2021_ESR/SM2-Merdith_et_al_1_Ga_reconstruction_v1.2.4.zip\")\n",
+    "        "
    ]
   },
   {
    "cell_type": "markdown",
    "id": "1519da7c",
    "metadata": {},
    "source": [
-    "#### 2) Using GPlately's `PlateModelManager`"
+    "#### 2) Using `PlateModelManager`"
    ]
   },
   {
@@ -104,7 +111,7 @@
    "outputs": [],
    "source": [
     "if not use_local_files:\n",
-    "    # Method 2: GPlately's PlateModelManager\n",
+    "    # Method 2: use PlateModelManager\n",
     "    pm_manager = PlateModelManager()\n",
     "    plate_model = pm_manager.get_model(\"Merdith2021\", data_dir=\"plate-model-repo\")\n",
     "    \n",
@@ -132,8 +139,7 @@
     "* **`PlateReconstruction_object`**: The gplately `PlateReconstruction` object defined in the cell below. This object is a collection of methods for calculating plate tectonic stats through geological time.\n",
     "* **`PlotTopologies_object`**: The gplately `PlotTopologies` object defined in the cell below. This object is a collection of methods for resolving geological features needed for gridding to a certain geological time.\n",
     "\n",
-    "#### Define the `PlateReconstruction` and `PlotTopologies` objects\n",
-    "...using the outputs of Method 1 OR Method 2."
+    "#### Define the `PlateReconstruction` and `PlotTopologies` objects"
    ]
   },
   {
@@ -267,6 +273,7 @@
     "    output_parent_directory,\n",
     "    \"seafloor_grid_output\",\n",
     ")\n",
+    "print(f\"The ouput files created by this notebook will be saved in folder {save_directory}.\" )\n",
     "\n",
     "# A string to help name files according to a plate model \"Merdith2021\"\n",
     "file_collection = \"Merdith2021\"\n"
@@ -425,7 +432,6 @@
     "import datetime\n",
     "import time\n",
     "\n",
-    "\n",
     "start = time.time()\n",
     "seafloorgrid.reconstruct_by_topologies()\n",
     "end = time.time()\n",
@@ -499,7 +505,6 @@
     "srgrid_unmasked_filename = \"{}/SPREADING_RATE/{}_SPREADING_RATE_grid_unmasked_{:0.2f}Ma.nc\".format(seafloorgrid.save_directory, seafloorgrid.file_collection, time)\n",
     "unmasked_sr_grid = gplately.grids.Raster(srgrid_unmasked_filename)\n",
     "\n",
-    "\n",
     "# Prepare plots\n",
     "fig = plt.figure(figsize=(18,10), dpi=300, linewidth=2)\n",
     "plt.subplots_adjust(wspace=.05, hspace=0) # spacing between subplots \n",
@@ -508,14 +513,39 @@
     "ax = fig.add_subplot(221, projection=ccrs.Mollweide(central_longitude=20))\n",
     "gplot.time = time\n",
     "plt.title(\"{} age grid (myr), {} Ma\".format(seafloorgrid.file_collection, time))\n",
+    "\n",
+    "agegrid_cmap = \"YlGnBu\"\n",
+    "spreading_rate_cmap = \"magma\"\n",
+    "spreading_rate_cpt_file = \"NotebookFiles/spreading_full_rate.cpt\"\n",
+    "agegrid_cpt_file = \"NotebookFiles/agegrid.cpt\"\n",
+    "if not os.path.isfile(agegrid_cpt_file):\n",
+    "    print(f\"The file {agegrid_cpt_file} does not exist locally. It can be found at https://raw.githubusercontent.com/GPlates/gplately/refs/heads/master/Notebooks/NotebookFiles/agegrid.cpt\")\n",
+    "    print(f\"The '{agegrid_cmap}' will be used to plot the age grid.\")\n",
+    "    agegrid_cpt_file = None\n",
+    "if not os.path.isfile(spreading_rate_cpt_file):\n",
+    "    print(f\"The file {spreading_rate_cpt_file} does not exist locally. It can be found at https://raw.githubusercontent.com/GPlates/gplately/refs/heads/master/Notebooks/NotebookFiles/spreading_full_rate.cpt\")\n",
+    "    print(f\"The '{spreading_rate_cmap}' will be used to plot the spreading rate grid.\")\n",
+    "    spreading_rate_cpt_file = None\n",
+    "if agegrid_cpt_file or spreading_rate_cpt_file:\n",
+    "    try:\n",
+    "        from gplately.mapping.gmt_cpt import get_cmap_from_gmt_cpt\n",
+    "        if agegrid_cpt_file:\n",
+    "            agegrid_cmap=get_cmap_from_gmt_cpt(agegrid_cpt_file)\n",
+    "        if spreading_rate_cpt_file:\n",
+    "            spreading_rate_cmap=get_cmap_from_gmt_cpt(spreading_rate_cpt_file)\n",
+    "    except ImportError as e:\n",
+    "        print(\"To use GMT cpt file, ensure you are using GPlately version 2.1 or higher.\")\n",
+    "        print(e)\n",
+    "\n",
     "im = gplot.plot_grid(\n",
     "    ax, \n",
     "    age_grid.data, \n",
-    "    cmap=\"YlGnBu\",\n",
+    "    cmap = agegrid_cmap,\n",
     "    vmin = 0, \n",
     "    vmax =410,\n",
     ")\n",
     "gplot.plot_ridges(ax)\n",
+    "gplot.plot_continents(ax, edgecolor=\"grey\", facecolor=\"lightgrey\", linewidth=0.5)\n",
     "plt.colorbar(im, label=\"Age (Ma)\", shrink=0.5, pad=0.05)\n",
     "\n",
     "# Unmasked agegrid\n",
@@ -525,25 +555,25 @@
     "im = gplot.plot_grid(\n",
     "    ax, \n",
     "    unmasked_age_grid.data, \n",
-    "    cmap=\"YlGnBu\",\n",
+    "    cmap=agegrid_cmap,\n",
     "    vmin = 0, \n",
     "    vmax =410,\n",
     ")\n",
     "gplot.plot_ridges(ax)\n",
     "plt.colorbar(im, label=\"Age (Ma)\", shrink=0.5, pad=0.05)\n",
     "\n",
-    "\n",
     "# Masked spreading rate grid\n",
     "ax1 = fig.add_subplot(223, projection=ccrs.Mollweide(central_longitude=20))\n",
     "gplot.time = time\n",
     "plt.title(\"{} spreading rate grid (mm/yr), {} Ma\".format(seafloorgrid.file_collection, time))\n",
     "im1 = gplot.plot_grid(\n",
     "    ax1, \n",
     "    sr_grid.data, \n",
-    "    cmap=\"magma\",\n",
+    "    cmap=spreading_rate_cmap,\n",
     "    alpha=0.7,\n",
     ")\n",
     "gplot.plot_ridges(ax1)\n",
+    "gplot.plot_continents(ax1, edgecolor=\"grey\", facecolor=\"lightgrey\", linewidth=0.5)\n",
     "plt.colorbar(im1, label=\"Spreading rate (mm/yr)\", shrink=0.5, pad=0.05)\n",
     "\n",
     "# Unmasked spreading rate grid\n",
@@ -553,7 +583,7 @@
     "im1 = gplot.plot_grid(\n",
     "    ax1, \n",
     "    unmasked_sr_grid.data, \n",
-    "    cmap=\"magma\",\n",
+    "    cmap=spreading_rate_cmap,\n",
     "    alpha=0.7,\n",
     ")\n",
     "gplot.plot_ridges(ax1)\n",

Notebooks/NotebookFiles/agegrid.cpt

@@ -0,0 +1,39 @@
+0	135/42/43	5	135/42/43
+5	164/38/44	10	164/38/44
+10	194/35/45	15	194/35/45
+15	219/30/38	20	219/30/38
+20	241/71/28	25	241/71/28
+25	245/107/29	30	245/107/29
+30	245/134/28	35	245/134/28
+35	250/147/21	40	250/147/21
+40	248/157/14	45	248/157/14
+45	250/179/12	50	250/179/12
+50	252/199/7	55	252/199/7
+55	254/215/23	60	254/215/23
+60	254/222/39	65	254/222/39
+65	245/227/35	70	245/227/35
+70	243/240/29	75	243/240/29
+75	233/240/53	80	233/240/53
+80	220/240/67	85	220/240/67
+85	204/230/75	90	204/230/75
+90	162/224/157	95	162/224/157
+95	153/219/184	100	153/219/184
+100	123/212/195	105	123/212/195
+105	102/204/206	110	102/204/206
+110	72/198/208	115	72/198/208
+115	51/188/207	120	51/188/207
+120	38/188/224	125	38/188/224
+125	25/181/241	130	25/181/241
+130	4/161/230	135	4/161/230
+135	11/142/216	140	11/142/216
+140	23/111/193	145	23/111/193
+145	30/92/179	150	30/92/179
+150	29/63/163	155	29/63/163
+155	27/41/153	160	27/41/153
+160	35/24/144	165	35/24/144
+165	53/19/143	170	53/19/143
+170	65/0/135	200	65/0/135
+200	92/0/125	350	92/0/125
+B	white
+F	black
+N	128

Notebooks/NotebookFiles/spreading_full_rate.cpt

@@ -0,0 +1,23 @@
+0 255 0 255 10 255 0 255
+10 234 0 255 20 234 0 255
+20 142 0 255 30 142 0 255
+30 35 0 255 40 35 0 255
+40 0 85 255 50 0 85 255
+50 0 216 255 60 0 216 255
+60 0 255 168 70 0 255 168
+70 0 255 32 80 0 255 32
+80 73 255 0 90 73 255 0
+90 149 255 0 100 149 255 0
+100 195 255 0 110 195 255 0
+110 228 255 0 120 228 255 0
+120 255 247 0 130 255 247 0
+130 255 213 0 140 255 213 0
+140 255 183 0 150 255 183 0
+150 255 146 0 160 255 146 0
+160 255 120 0 170 255 120 0
+170 255 100 0 180 255 100 0
+180 255 85 0 190 255 85 0
+190 255 73 0 200 255 73 0
+B 255 0 255    
+F 255 73 0    
+N 125 125 125    

README.md

@@ -42,6 +42,19 @@ eprint = {https://rmets.onlinelibrary.wiley.com/doi/pdf/10.1002/gdj3.185},
 }
 ```
 
+## Common Use Cases
+
+- Generating Seafloor Age and Spreading Rate Grids Through Time
+  ![Figure: age-and-spreading-rate-200ma.png](https://raw.githubusercontent.com/GPlates/gplately/375-update-main-readme-and-seafloorgridsipynb/Notebooks/NotebookFiles/age-and-spreading-rate-200ma.png)
+- Plotting Paleomaps with Cartopy
+  ![Figure: plottopologies.png](https://gplates.github.io/gplately/latest/sphinx/html/_images/plottopologies.png)
+- Rasters Reconstruction
+  ![Figure: etopo_reconstruction.png](https://gplates.github.io/gplately/latest/sphinx/html/_images/etopo_reconstruction.png)
+- Locations Reconstruction 
+  ![Figure: Reconstructed-Jurassic-Foraminifera-locations-min.png](https://gplates.github.io/gplately/latest/sphinx/html/_images/Reconstructed-Jurassic-Foraminifera-locations-min.png)
+- Calculating Motion Path
+  ![Figure: Hawaii_Emperor_motion_path.png](https://gplates.github.io/gplately/latest/sphinx/html/_images/Hawaii_Emperor_motion_path.png)
+
 ## Documentation
 
 - [latest stable](https://gplates.github.io/gplately/stable/sphinx/html/index.html)

gplately/mapping/cartopy_plot.py

@@ -1,5 +1,5 @@
 #
-#    Copyright (C) 2024-2025 The University of Sydney, Australia
+#    Copyright (C) 2024-2026 The University of Sydney, Australia
 #
 #    This program is free software; you can redistribute it and/or modify it under
 #    the terms of the GNU General Public License, version 2, as published by