Common Use Cases
================

.. contents::
   :local:
   :depth: 2
   
DataServer
----------

The :py:class:`gplately.DataServer` class allows users to automatically download and cache the plate reconstruction model files to a designated folder 
on your system. These files include rotation models, topology features, and static geometries such as coastlines, continents, and 
continent-ocean boundaries. Additionally, it supports the retrieval of other data types, including rasters, grids, and feature data.

.. seealso::

  The :py:class:`gplately.DataServer` class is implemented using the plate-model-manager_ Python package. 
  To simply access plate model files, you can use the plate-model-manager_ Python package directly.
  
.. _plate-model-manager: https://pypi.org/project/plate-model-manager/


.. code-block:: python
   :linenos:
   :emphasize-lines: 3

   from gplately import DataServer

   data_server = DataServer("Muller2019")

   # Download plate reconstruction files and geometries from the Müller et al. 2019 model
   rotation_model, topology_features, static_polygons = (
      data_server.get_plate_reconstruction_files()
   )
   coastlines, continents, COBs = data_server.get_topology_geometries()

   # Download the age grid at 100Ma from the Müller et al. 2019 model
   age_grid = data_server.get_age_grid(times=100)

   # Download the ETOPO1 geotiff raster
   etopo = data_server.get_raster("ETOPO1_tif")

.. seealso::

  `This page <plate_models.html>`__ contains a list of all available plate reconstruction models.


PlateReconstruction
-------------------

The :py:class:`gplately.PlateReconstruction` class contains tools to reconstruct geological features like tectonic plates and plate boundaries,
and to interrogate plate kinematic data like plate motion velocities, and rates of subduction and seafloor spreading.

.. code-block:: python
   :linenos:
   :emphasize-lines: 6

   from gplately import PlateReconstruction, PlateModelManager

   model = PlateModelManager().get_model("Muller2019")

   # Build a plate reconstruction model using a rotation model, a set of topology features and static polygons
   recon_model = PlateReconstruction(
      model.get_rotation_model(),
      topology_features=model.get_layer("Topologies"),
      static_polygons=model.get_layer("StaticPolygons"),
   )


Alternatively, you may use the auxiliary functions to create a :py:class:`gplately.PlateReconstruction` object.

.. code-block:: python
   :linenos:
   :emphasize-lines: 4

   from gplately.auxiliary import get_plate_reconstruction

   # use the auxiliary function to create a PlateReconstruction object
   plate_reconstruction_instance = get_plate_reconstruction("Muller2019")


The `PlateReconstructions example`_ demonstrates in detail how to use the :py:class:`gplately.PlateReconstruction` class.
The latest `02-PlateReconstructions.ipynb`_ Jupyter Notebook is available in the GitHub GPlately repository.

.. _`02-PlateReconstructions.ipynb`: https://github.com/GPlates/gplately/blob/master/Notebooks/02-PlateReconstructions.ipynb
.. _`PlateReconstructions example`: ../../notebook-html/02-PlateReconstructions.html

Points
------

The methods in the :py:class:`gplately.Points` class track the motion of a point (or group of points) represented by a latitude and longitude
through geologic time. This motion can be visualised using flowlines or motion paths and quantified with point motion velocities.

.. code-block:: python
   :linenos:
   :emphasize-lines: 13

   import numpy as np

   from gplately import Points, auxiliary

   # Create a plate reconstruction model using a rotation model, a set of topology features and static polygons
   recon_model = auxiliary.get_plate_reconstruction("Muller2019")

   # Define some points using their latitude and longitude coordinates so we can track them through time!
   pt_lons = np.array([140.0, 150.0, 160.0])
   pt_lats = np.array([-30.0, -40.0, -50.0])

   # Create a Points object from these points
   gpts = Points(recon_model, pt_lons, pt_lats)


The `WorkingWithPoints example`_ demonstrates in detail how to use the Points class. 
The latest `03-WorkingWithPoints.ipynb`_ Jupyter Notebook is available in the GitHub GPlately repository.

.. _`WorkingWithPoints example`: ../../notebook-html/03-WorkingWithPoints.html
.. _`03-WorkingWithPoints.ipynb`: https://github.com/GPlates/gplately/blob/master/Notebooks/03-WorkingWithPoints.ipynb

.. image:: images/Reconstructed-Jurassic-Foraminifera-locations-min.png
      :width: 600
      :alt: PointsDemo

The `CreatingMotionPathsAndFlowlines example`_ demonstrates how to create motion paths and flowlines.
The latest `09-CreatingMotionPathsAndFlowlines.ipynb`_ Jupyter Notebook is available in the GitHub GPlately repository.

.. _`CreatingMotionPathsAndFlowlines example`: ../../notebook-html/09-CreatingMotionPathsAndFlowlines.html
.. _`09-CreatingMotionPathsAndFlowlines.ipynb`: https://github.com/GPlates/gplately/blob/master/Notebooks/09-CreatingMotionPathsAndFlowlines.ipynb

.. image:: images/Hawaii_Emperor_motion_path.png
      :width: 600
      :alt: motion paths and flowlines

Raster
------

The :py:class:`gplately.Raster` class contains methods to work with netCDF4 or MaskedArray gridded data. Grids may be filled,
resized, resampled, and reconstructed back and forwards through geologic time. Other array data can also be
interpolated onto Raster grids.

.. code-block:: python
   :linenos:
   :emphasize-lines: 8, 16

   from gplately import PresentDayRasterManager, Raster, auxiliary

   model = auxiliary.get_plate_model("Muller2019")
   # Create a plate reconstruction model using a rotation model, a set of topology features and static polygons
   recon_model = auxiliary.get_plate_reconstruction(model)

   # Any numpy array can be turned into a Raster object!
   raster = Raster(
      plate_reconstruction=recon_model,
      data=PresentDayRasterManager().get_raster("topography"),
      extent="global",  # equivalent to (-180, 180, -90, 90)
      origin="lower",  # or set extent to (-180, 180, -90, 90)
   )

   # Reconstruct the raster data to 50 million years ago!
   reconstructed_raster = raster.reconstruct(
      time=50,
      partitioning_features=model.get_layer("ContinentalPolygons"),
   )


The `Rasters example`_ demonstrates in detail how to use the :py:class:`gplately.Raster` class. 
The latest `06-Rasters.ipynb`_ Jupyter Notebook is available in the GitHub GPlately repository.

.. _`06-Rasters.ipynb`: https://github.com/GPlates/gplately/blob/master/Notebooks/06-Rasters.ipynb
.. _`Rasters example`: ../../notebook-html/06-Rasters.html

.. image:: images/etopo_reconstruction.png
      :width: 600
      :alt: RasterDemo

PlotTopologies
--------------

The :py:class:`gplately.PlotTopologies` class works with the aforementioned :py:class:`gplately.PlateReconstruction` class to plot
geologic features of different types, such as coastlines, continents and continent-ocean boundaries reconstructed through time using pyGPlates.

.. code-block:: python
   :linenos:
   :emphasize-lines: 6

   from gplately import PlotTopologies, auxiliary

   model = auxiliary.get_plate_model("Muller2019")
   recon_model = auxiliary.get_plate_reconstruction(model)

   gplot = PlotTopologies(
      recon_model,
      coastlines=model.get_layer("Coastlines"),
      COBs=model.get_layer("COBs"),
      continents=model.get_layer("ContinentalPolygons"),
      time=55,
   )


You may use the auxiliary functions to create a :py:class:`gplately.PlotTopologies` object.

.. code-block:: python
   :linenos:
   :emphasize-lines: 4

   from gplately.auxiliary import get_gplot

   # use the auxiliary function to create a PlotTopologies object
   plot_topologies_obj = get_gplot("Muller2019", time=55)

The `PlateReconstructions example`_ demonstrates in detail how to use the :py:class:`gplately.PlotTopologies` class.
The `02-PlateReconstructions.ipynb`_ Jupyter Notebook is available in the GitHub GPlately repository.

.. image:: images/plottopologies.png
      :width: 600
      :alt: PlotTopologiesDemo

SeafloorGrid
------------

The :py:class:`gplately.SeafloorGrid` class wraps an automatic workflow to grid seafloor ages and seafloor spreading rates
as encoded by a plate reconstruction model.

.. code-block:: python
   :linenos:
   :emphasize-lines: 11, 20

   import os

   os.environ["GPLATELY_DISABLE_DEV_WARNING"] = "true"

   from gplately import SeafloorGrid, auxiliary

   model = auxiliary.get_plate_model("Muller2019")
   plate_reconstruction = auxiliary.get_plate_reconstruction(model)

   # Set up automatic gridding from 5Ma to present day
   seafloorgrid = SeafloorGrid(
      plate_reconstruction=plate_reconstruction,  # the PlateReconstruction object
      max_time=5,  # start time (Ma)
      min_time=0,  # end time (Ma)
      ridge_time_step=1,  # time increment (Myr)
      continent_polygon_features=model.get_layer("ContinentalPolygons"),  # the continent polygons
   )

    # Begin automatic gridding!
    seafloorgrid.reconstruct_by_topologies()

The `SeafloorGrids example`_ is a tutorial notebook that demonstrates
how to set up and use the :py:class:`gplately.SeafloorGrid` object, and shows a sample set of output grids. 
The latest `10-SeafloorGrids.ipynb`_ Jupyter Notebook is available in the GitHub GPlately repository.

.. _`SeafloorGrids example`: ../../notebook-html//10-SeafloorGrids.html
.. _`10-SeafloorGrids.ipynb`: https://github.com/GPlates/gplately/blob/master/Notebooks/10-SeafloorGrids.ipynb

.. image:: images/seafloor_age_65Ma.png
      :width: 600
      :alt: SeafloorGridDemo