diff --git a/README.md b/README.md index 31f3f367..5144fe28 100644 --- a/README.md +++ b/README.md @@ -10,16 +10,14 @@ ![PyPI](https://img.shields.io/pypi/v/gplately?style=for-the-badge) ![Conda (channel only)](https://img.shields.io/conda/vn/conda-forge/gplately?style=for-the-badge) - GPlately was created to accelerate spatio-temporal data analysis leveraging [pyGPlates](https://www.gplates.org/docs/pygplates/index.html) and [PlateTectonicTools](https://github.com/EarthByte/PlateTectonicTools) within a simplified Python interface. This object-oriented package enables the reconstruction of data through deep geologic time (points, lines, polygons, and rasters), the interrogation of plate kinematic information (plate velocities, rates of subduction and seafloor spreading), the rapid comparison between multiple plate motion models, and the plotting of reconstructed output data on maps. All tools are designed to be parallel-safe to accelerate spatio-temporal analysis over multiple CPU processors. ![SeedPointGIF](https://raw.githubusercontent.com/GPlates/gplately/master/Notebooks/NotebookFiles/ReadMe_Files/muller19_seedpoints.gif) - GPlately requires a working installation of pyGPlates, which is freely available at https://www.gplates.org/download. All major system architectures (e.g. Linux, MacOS, Windows) are supported and installation instructions -are [well documented](https://www.gplates.org/docs/pygplates/pygplates_getting_started.html\#installation). +are [well documented](https://www.gplates.org/docs/pygplates/pygplates_getting_started.html#installation). Sample data is also available from [EarthByte servers](https://www.earthbyte.org/category/resources/), which includes rasters, seafloor age grids, rotation files, and more to get started with plate reconstructions. @@ -44,7 +42,7 @@ eprint = {https://rmets.onlinelibrary.wiley.com/doi/pdf/10.1002/gdj3.185}, ## Dependencies - [pyGPlates](https://www.gplates.org/docs/pygplates/pygplates_getting_started.html#installation) -- [PlateTectonicTools](https://github.com/EarthByte/PlateTectonicTools) +- [plate-model-manager](https://pypi.org/project/plate-model-manager/) - [Shapely](https://shapely.readthedocs.io/en/stable/project.html#installing-shapely) - [NumPy](https://numpy.org/install/) > 1.16 - [SciPy](https://scipy.org/install/) > 1.0 @@ -55,7 +53,6 @@ eprint = {https://rmets.onlinelibrary.wiley.com/doi/pdf/10.1002/gdj3.185}, - [GeoPandas](https://geopandas.org/en/stable/getting_started.html) - [netCDF4](https://unidata.github.io/netcdf4-python/#quick-install) - ## Installation ### 1. Using conda (recommended) @@ -86,13 +83,14 @@ Alternatively, you can install the latest stable public release of `GPlately` us ```sh pip install gplately ``` + or from this GitHub repository: ```sh -pip install git+https://github.com/GPlates/gplately.git +pip install git+https://github.com/GPlates/gplately.git ``` -#### Pull from repository +#### Pull from repository **First-time installation:** To install the latest version of GPlately from a specific repository branch (e.g. `master`), copy the following commands into your terminal: @@ -114,7 +112,6 @@ git pull # fetch all recent changes from this branch pip install . ``` - ## Usage GPlately uses objects to accomplish a variety of common tasks. The common objects include: @@ -125,7 +122,6 @@ GPlately uses objects to accomplish a variety of common tasks. The common object - [`Raster`](#the-raster-object) - read in NetCDF grids, interpolation, resampling - [`PlotTopologies`](#the-plottopologies-object) - one stop shop for plotting ridges, trenches, subduction teeth - ### The `DataServer` object `GPlately`'s `DataServer` object can be used to download: @@ -140,8 +136,8 @@ GPlately uses objects to accomplish a variety of common tasks. The common object - geological feature data from assorted plate reconstruction models. These files are needed to construct most of `GPlately`'s objects. For example, -we can download a `rotation model`, a set of `topology features` and some `static polygons` from the [Müller et al. 2019](https://www.earthbyte.org/muller-et-al-2019-deforming-plate-reconstruction-and-seafloor-age-grids-tectonics/) -global Mesozoic–Cenozoic deforming plate motion model. +we can download a `rotation model`, a set of `topology features` and some `static polygons` from the [Müller et al. 2019](https://www.earthbyte.org/muller-et-al-2019-deforming-plate-reconstruction-and-seafloor-age-grids-tectonics/) +global Mesozoic–Cenozoic deforming plate motion model. ```python gDownload = gplately.DataServer("Muller2019") @@ -174,17 +170,18 @@ rotation_model, topology_features, static_polygons = gDownload.get_plate_reconst ... contains methods to reconstruct the positions of present-day feature data back through geological time. You can also use it to calculate plate model data like topological plate velocities, or total trench and ridge lengths per Ma! You can create -the object by passing a `rotation model`, a set of `topology features` and some `static polygons`: +the object by passing a `rotation model`, a set of `topology features` and some `static polygons`: ```python model = gplately.PlateReconstruction(rotation_model, topology_features, static_polygons) ``` + Launch the [Plate Reconstruction](https://github.com/GPlates/gplately/blob/master/Notebooks/02-PlateReconstructions.ipynb) notebook to see more. ### The `Points` object -... can be used to reconstruct the positions of geological point features and calculate their underlying plate velocities -through geological time. +... can be used to reconstruct the positions of geological point features and calculate their underlying plate velocities +through geological time. ```python pt_lon = np.array([-107.662152, -58.082792, 17.483189, 133.674590, 80.412876]) @@ -193,6 +190,7 @@ pt_lat = np.array([48.797807, -12.654857, 11.884395, -26.415630, 31.368509]) # Call the Points object: pass the PlateReconstruction object, and the latitudes and longitudes of the seed points! gpts = gplately.Points(model, pt_lon, pt_lat) ``` + ![PointData](https://raw.githubusercontent.com/GPlates/gplately/master/Notebooks/NotebookFiles/ReadMe_Files/surface_hotspot_plumes.png) ### The `Raster` object @@ -224,36 +222,92 @@ Below is a plot of the [ETOPO1 global relief raster](https://www.ncei.noaa.gov/p ### The `PlotTopologies` object -... can be used to visualise reconstructed feature geometries through time. To call the object, pass a set of `continents`, +... can be used to visualise reconstructed feature geometries through time. To call the object, pass a set of `continents`, `coastlines` and `COBs` (either as file paths or as `` objects), as well as a `PlateReconstruction` -object, and a reconstruction `time`. +object, and a reconstruction `time`. ```python coastlines, continents, COBs = gDownload.get_topology_geometries() time = 50 #Ma gPlot = gplately.plot.PlotTopologies(model, time, coastlines, continents, COBs) ``` + Below are some continents, coastlines, COBs, ridges and transforms, trenches, subduction teeth and seafloor age grids plotted using `PlotTopologies`! ![ReconstructionImage](https://raw.githubusercontent.com/GPlates/gplately/master/Notebooks/NotebookFiles/ReadMe_Files/plot_topologies_img.png) - ## Sample workflows To see GPlately in action, launch a Jupyter Notebook environment and check out the [sample notebooks](./Notebooks): -- [__01 - Getting Started__](https://github.com/GPlates/gplately/blob/master/Notebooks/01-GettingStarted.ipynb): A brief overview of how to initialise GPlately's main objects -- [__02 - Plate Reconstructions__](https://github.com/GPlates/gplately/blob/master/Notebooks/02-PlateReconstructions.ipynb): Setting up a `PlateReconstruction` object, reconstructing geological data through time -- [__03 - Working with Points__](https://github.com/GPlates/gplately/blob/master/Notebooks/03-WorkingWithPoints.ipynb): Setting up a `Points` object, reconstructing seed point locations through time with. This notebook uses point data from the Paleobiology Database (PBDB). -- [__04 - Velocity Basics__](https://github.com/GPlates/gplately/blob/master/Notebooks/04-VelocityBasics.ipynb): Calculating plate velocities, plotting velocity vector fields -- [__05 - Working with Feature Geometries__](https://github.com/GPlates/gplately/blob/master/Notebooks/05-WorkingWithFeatureGeometries.ipynb): Processing and plotting assorted polyline, polygon and point data from [GPlates 2.3's sample data sets](https://www.earthbyte.org/gplates-2-3-software-and-data-sets/) -- [__06 - Rasters__](https://github.com/GPlates/gplately/blob/master/Notebooks/06-Rasters.ipynb): Reading, resizing, resampling raster data, and linearly interpolating point data onto raster data -- [__07 - Plate Tectonic Stats__](https://github.com/GPlates/gplately/blob/master/Notebooks/07-WorkingWithPlateTectonicStats.ipynb): Using [PlateTectonicTools](https://github.com/EarthByte/PlateTectonicTools) to calculate and plot subduction zone and ridge data (convergence/spreading velocities, subduction angles, subduction zone and ridge lengths, crustal surface areas produced and subducted etc.) -- [__08 - Predicting Slab Flux__](https://github.com/GPlates/gplately/blob/master/Notebooks/08-PredictingSlabFlux.ipynb): Predicting the average slab dip angle of subducting oceanic lithosphere. -- [__09 - Motion Paths and Flowlines__](https://github.com/GPlates/gplately/blob/master/Notebooks/09-CreatingMotionPathsAndFlowlines.ipynb): Using pyGPlates to create motion paths and flowines of points on a tectonic plate to illustrate the plate's trajectory through geological time. -- [__10 - SeafloorGrid__](https://github.com/GPlates/gplately/blob/master/Notebooks/10-SeafloorGrids.ipynb): Defines the parameters needed to set up a `SeafloorGrid` object, and demonstrates how to produce age and spreading rate grids from a set of plate reconstruction model files. +- [**01 - Getting Started**](https://github.com/GPlates/gplately/blob/master/Notebooks/01-GettingStarted.ipynb): A brief overview of how to initialise GPlately's main objects +- [**02 - Plate Reconstructions**](https://github.com/GPlates/gplately/blob/master/Notebooks/02-PlateReconstructions.ipynb): Setting up a `PlateReconstruction` object, reconstructing geological data through time +- [**03 - Working with Points**](https://github.com/GPlates/gplately/blob/master/Notebooks/03-WorkingWithPoints.ipynb): Setting up a `Points` object, reconstructing seed point locations through time with. This notebook uses point data from the Paleobiology Database (PBDB). +- [**04 - Velocity Basics**](https://github.com/GPlates/gplately/blob/master/Notebooks/04-VelocityBasics.ipynb): Calculating plate velocities, plotting velocity vector fields +- [**05 - Working with Feature Geometries**](https://github.com/GPlates/gplately/blob/master/Notebooks/05-WorkingWithFeatureGeometries.ipynb): Processing and plotting assorted polyline, polygon and point data from [GPlates 2.3's sample data sets](https://www.earthbyte.org/gplates-2-3-software-and-data-sets/) +- [**06 - Rasters**](https://github.com/GPlates/gplately/blob/master/Notebooks/06-Rasters.ipynb): Reading, resizing, resampling raster data, and linearly interpolating point data onto raster data +- [**07 - Plate Tectonic Stats**](https://github.com/GPlates/gplately/blob/master/Notebooks/07-WorkingWithPlateTectonicStats.ipynb): Using [PlateTectonicTools](https://github.com/EarthByte/PlateTectonicTools) to calculate and plot subduction zone and ridge data (convergence/spreading velocities, subduction angles, subduction zone and ridge lengths, crustal surface areas produced and subducted etc.) +- [**08 - Predicting Slab Flux**](https://github.com/GPlates/gplately/blob/master/Notebooks/08-PredictingSlabFlux.ipynb): Predicting the average slab dip angle of subducting oceanic lithosphere. +- [**09 - Motion Paths and Flowlines**](https://github.com/GPlates/gplately/blob/master/Notebooks/09-CreatingMotionPathsAndFlowlines.ipynb): Using pyGPlates to create motion paths and flowines of points on a tectonic plate to illustrate the plate's trajectory through geological time. +- [**10 - SeafloorGrid**](https://github.com/GPlates/gplately/blob/master/Notebooks/10-SeafloorGrids.ipynb): Defines the parameters needed to set up a `SeafloorGrid` object, and demonstrates how to produce age and spreading rate grids from a set of plate reconstruction model files. ## API Documentation Documentation of GPlately's objects and methods can be found [here](https://gplates.github.io/gplately/)! + +## Command Line Tools + +GPlately comes with a suite of useful command line tools. These tools are designed as GPlately subcommands. Run `gplately -h` to show the list of tools. + +- combine + + Combine multiple feature collections into one. Run `gplately combine -h` for details. + +- filter + + Filter feature collection by various criteria. See scripts/test_feature_filter.sh for usage examples. Run `glately filter -h` for details. + +- agegrid (ag) + + Create age grids for a plate model. Run `glately agegrid -h` for details. + +- fix_crossovers + + Loads one or more input rotation files, fixes any crossovers and saves the rotations to output rotation files. Run `gplately fix_crossovers -h` for details. + +- remove_rotations + + Remove one or more plate IDs from a rotation model (consisting of one or more rotation files). Run `gplately remove_rotations -h` for details. + +- cleanup_topologies + + Remove any regular features not referenced by topological features. Run `gplately cleanup_topologies -h` for details. + +- convert_xy_to_gplates + + Converts geometry in one or more input ascii files (such as '.xy' files) to output files suitable for loading into GPlates. Run `gplately convert_xy_to_gplates -h` for details. + +- diagnose_rotations + + Diagnose one or more rotation files to check for inconsistencies. Run `gplately diagnose_rotations -h` for details. + +- resolve_topologies + + Resolve topological plate polygons (and deforming networks) and saves (to separate files) the resolved topologies, and their boundary sections as subduction zones, mid-ocean ridges (ridge/transform) and others (not subduction zones or mid-ocean ridges). Run `gplately resolve_topologies -h` for details. + +- rotation_tools + + Calculate stage rotations between consecutive finite rotations in plate pairs. Run `gplately rotation_tools -h` for details. + +- separate_ridge_transform_segments + + Split the geometries of isochrons and mid-ocean ridges into ridge and transform segments. Run `gplately separate_ridge_transform_segments -h` for details. + +- subduction_convergence + + Find the convergence rates along trenches (subduction zones) over time. Run `gplately subduction_convergence -h` for details. + +- gpmdb + + Retrieve paleomagnetic data from https://www.gpmdb.net, create GPlates-compatible VGP features and save the VGP features in a .gpmlz file. Run `gplately gpmdb -h` for details. diff --git a/gplately/__main__.py b/gplately/__main__.py index fdc8302c..3d54354e 100644 --- a/gplately/__main__.py +++ b/gplately/__main__.py @@ -23,7 +23,10 @@ def combine_feature_collections(input_files: List[str], output_file: str): - """Combine multiple feature collections into one.""" + """Combine multiple feature collections into one. + + Usage example: gplately combine input_file_1 input_file_2 input_file_3 output_file + """ feature_collection = pygplates.FeatureCollection() for file in input_files: if not os.path.isfile(file): @@ -149,9 +152,10 @@ def main(): # add combine feature sub-command combine_cmd = subparser.add_parser( "combine", - help=combine_feature_collections.__doc__, + help="Combine multiple feature collections into one.", description=combine_feature_collections.__doc__, ) + combine_cmd.formatter_class = argparse.RawDescriptionHelpFormatter # add feature filter sub-command feature_filter.add_parser(subparser) @@ -167,7 +171,7 @@ def main(): # add fix crossovers sub-command fix_crossovers_cmd = subparser.add_parser( "fix_crossovers", - help="fix crossovers", + help="Loads one or more input rotation files, fixes any crossovers and saves the rotations to output rotation files.", add_help=True, ) fix_crossovers.add_arguments(fix_crossovers_cmd) @@ -175,7 +179,7 @@ def main(): # add remove plate rotations sub-command remove_plate_rotations_cmd = subparser.add_parser( "remove_rotations", - help="remove plate rotations", + help="Remove one or more plate IDs from a rotation model (consisting of one or more rotation files).", add_help=True, ) remove_plate_rotations.add_arguments(remove_plate_rotations_cmd) @@ -183,7 +187,7 @@ def main(): # add cleanup topologies sub-command cleanup_topologies_cmd = subparser.add_parser( "cleanup_topologies", - help="cleanup topologies", + help="Remove any regular features not referenced by topological features.", add_help=True, ) cleanup_topologies.add_arguments(cleanup_topologies_cmd) @@ -191,7 +195,7 @@ def main(): # add convert_xy_to_gplates sub-command convert_xy_to_gplates_cmd = subparser.add_parser( "convert_xy_to_gplates", - help="convert xy to GPlates", + help="Converts geometry in one or more input ascii files (such as '.xy' files) to output files suitable for loading into GPlates.", add_help=True, ) convert_xy_to_gplates.add_arguments(convert_xy_to_gplates_cmd) @@ -199,7 +203,7 @@ def main(): # add diagnose_rotations sub-command diagnose_rotations_cmd = subparser.add_parser( "diagnose_rotations", - help="diagnose rotations", + help="Diagnose one or more rotation files to check for inconsistencies.", add_help=True, ) diagnose_rotations.add_arguments(diagnose_rotations_cmd) @@ -207,7 +211,7 @@ def main(): # add resolve_topologies sub-command resolve_topologies_cmd = subparser.add_parser( "resolve_topologies", - help="resolve topologies", + help="Resolve topological plate polygons (and deforming networks) and saves (to separate files) the resolved topologies, and their boundary sections as subduction zones, mid-ocean ridges (ridge/transform) and others (not subduction zones or mid-ocean ridges).", add_help=True, ) resolve_topologies.add_arguments(resolve_topologies_cmd) @@ -215,7 +219,7 @@ def main(): # add rotation_tools sub-command rotation_tools_cmd = subparser.add_parser( "rotation_tools", - help="rotation tools", + help="Calculate stage rotations between consecutive finite rotations in plate pairs.", add_help=True, ) rotation_tools.add_arguments(rotation_tools_cmd) @@ -223,7 +227,7 @@ def main(): # add separate_ridge_transform_segments sub-command separate_ridge_transform_segments_cmd = subparser.add_parser( "separate_ridge_transform_segments", - help="separate ridge transform segments", + help="Split the geometries of isochrons and mid-ocean ridges into ridge and transform segments.", add_help=True, ) separate_ridge_transform_segments.add_arguments( @@ -233,7 +237,7 @@ def main(): # add subduction_convergence sub-command subduction_convergence_cmd = subparser.add_parser( "subduction_convergence", - help="subduction convergence", + help="Find the convergence rates along trenches (subduction zones) over time.", add_help=True, ) subduction_convergence.add_arguments(subduction_convergence_cmd) @@ -241,7 +245,7 @@ def main(): # add gpmdb sub-command gpmdb_cmd = subparser.add_parser( "gpmdb", - help="retrieve data from https://www.gpmdb.net and create VGP features", + help="Retrieve paleomagnetic data from https://www.gpmdb.net, create GPlates-compatible VGP features and save the VGP features in a .gpmlz file.", add_help=True, ) gpmdb.add_arguments(gpmdb_cmd) diff --git a/gplately/feature_filter.py b/gplately/feature_filter.py index 300f1ead..89758c39 100644 --- a/gplately/feature_filter.py +++ b/gplately/feature_filter.py @@ -1,4 +1,5 @@ import abc +import argparse from typing import List import pygplates @@ -96,7 +97,7 @@ class BirthAgeFilter(FeatureFilter): for example: BirthAgeFilter(500) -- keep features whose time of apprearance are bigger than 500 - BirthAgeFilter(500, keep_older=False) -- keep features whose time of apprearance are smaller than 500 + BirthAgeFilter(500, keep_older=False) -- keep features whose time of apprearance are smaller than 500 :param age: the age criterion :param keep_older: if True, return True when the feature's birth age is older than the age criterion. If False, otherwise. @@ -120,7 +121,10 @@ def should_keep(self, feature: pygplates.Feature) -> bool: def filter_feature_collection( feature_collection: pygplates.FeatureCollection, filters: List[FeatureFilter] ): - """the loop to apply fiters""" + """Filter feature collection by various criteria. + + See scripts/test_feature_filter.sh for usage examples. + """ new_feature_collection = pygplates.FeatureCollection() for feature in feature_collection: keep_flag = True @@ -137,9 +141,10 @@ def add_parser(subparser): """add feature filter command line argument parser""" filter_cmd = subparser.add_parser( "filter", - help=filter_feature_collection.__doc__, + help="Filter feature collection by various criteria.", description=filter_feature_collection.__doc__, ) + filter_cmd.formatter_class = argparse.RawDescriptionHelpFormatter # feature filter command arguments filter_cmd.set_defaults(func=run_filter_feature_collection)