PlateMotionRequests

A Julia package for plate motion data requests using the UNAVCO Plate Motion Calculator.

The package is open source, and the code is available under the Zero-Clause BSD license. There is also a website with online documentation.

Installation

From the Julia shell, switch to package mode with ] and run

add PlateMotionRequests

For advanced packaging instructions, refer to the Julia Pkg docs.

Usage

Save data whenever possible to avoid repeating requests to the UNAVCO server. Note that the provided methods do not implement any network limits.

julia> using PlateMotionRequests
julia> latitudes = -20:10:20
julia> longitudes = 160:10:200
julia> GSRMdata = platemotion(
           repeat(latitudes, length(longitudes)),
           repeat(longitudes, inner = length(latitudes)),
       )

Data can be written to/read from storage using write_platemotion and read_platemotion. These functions write/read simple tab-delimited text files. By using the .nc file extension, you can tell write_platemotion to use an experimental NetCDF output format (NetCDF tests currently fail on Windows). To store binary representations, the Serialization module from Julia's standard library may prove useful. Other formats like HDF5 or ASDF may be preferred, depending on your requirements.

Responses are tabulated using TypedTables.jl, e.g.:

Table with 6 columns and 25 rows:
      lon    lat    velocity_east  velocity_north  plate_and_reference  model
    ┌────────────────────────────────────────────────────────────────────────────
 1  │ 160.0  -20.0  25.53          49.46           AU(NNR)              GSRM v2.1
 2  │ 160.0  -10.0  -61.14         25.72           PA(NNR)              GSRM v2.1
 3  │ 160.0  0.0    -65.81         25.72           PA(NNR)              GSRM v2.1
 4  │ 160.0  10.0   -68.49         25.72           PA(NNR)              GSRM v2.1
 5  │ 160.0  20.0   -69.1          25.71           PA(NNR)              GSRM v2.1
 6  │ 170.0  -20.0  -56.25         29.02           PA(NNR)              GSRM v2.1
 7  │ 170.0  -10.0  -61.97         29.02           PA(NNR)              GSRM v2.1
 8  │ 170.0  0.0    -65.81         29.03           PA(NNR)              GSRM v2.1
 9  │ 170.0  10.0   -67.66         29.02           PA(NNR)              GSRM v2.1
 10 │ 170.0  20.0   -67.48         29.02           PA(NNR)              GSRM v2.1
 11 │ 180.0  -20.0  20.45          35.23           AU(NNR)              GSRM v2.1
 12 │ 180.0  -10.0  -62.88         31.45           PA(NNR)              GSRM v2.1
 ⋮  │   ⋮      ⋮          ⋮              ⋮                  ⋮               ⋮

Change the model and reference frame using the model and reference keywords, respectively. For a no-net-rotation frame, use the value "NNR" (default). The model argument accepts the value "all", to query all available models for the data.

Change output formats using the format keyword. The supported output formats are "ascii" (default), "ascii_xyz" (WGS-84 coordinates) and "psvelo" (GMT 'psvelo' format).

For the full list of options, see ?platemotion. You may also want to refer to the UNAVCO website linked above.

The author is not affiliated with UNAVCO and cannot guarantee stability of the server.

Feedback and contributions

Please use the public mailing list for feedback and discussion:

~adigitoleo/platemotionrequests.jl-devel@lists.sr.ht

Contributions are handled via patches sent to the same mailing list (preferred) or pull requests at the GitHub mirror. Contributor guidelines are provided with the source code repository (in the file CONTRIBUTING.md). The file TODO.md lists some ideas for planned features. If you want to work on one of them, send an email first to check if an implementation is already underway.

CI is set up for commits pushed to main, next or dev. The CI manifests are in .build.yml and .github/workflows/ci.yml. Logs of test runs are available:

  • Linux CI (latest release) builds.sr.ht status
  • Windows CI (GitHub status

API Reference

PlateMotionRequests.platemotionFunction
platemotion(lats, lons, heights; kwargs...)
platemotion(lats, lons; kwargs...)

Request plate motion data from the [UNAVCO Plate Motion Calculator][1]. Headers and metadata are stripped from the output, which is parsed into a [Table][2]. Accepts either separate vectors for latitude, longitude and optionally height.

See also: write_platemotion.

Note

Site names are not supported. Only 'ansii', 'ansii_xyz' and 'psvelo' formats are supported. Not all optional argument permutations are permitted, see the website linked above for further details.

Optional arguments:

  • model: The plate motion model to use for calculations, or GSRM v2.1 by default.
  • plate: The tectonic plate of attributed motion, or automatic plate selection by default.
  • reference: The fixed reference plate, or NNR (No Net Rotation) by default.
  • up_lat: Custom coordinate of the Euler pole (attributed motion) in decimal degrees.
  • up_lon: See above.
  • up_w: Custom rotation rate (attributed motion) in degrees per million years.
  • up_x: Custom component of the Euler pole (attributed motion) in degrees per million years.
  • up_y: See above.
  • up_z: See above.
  • ur_lat: Custom coordinate of the Euler pole (reference velocity) in decimal degrees.
  • ur_lon: See above.
  • ur_w: Custom rotation rate of the Euler pole (reference velocity) in degrees per million years.
  • ur_x: Custom component of the Euler pole (reference velocity) in degrees per million years.
  • ur_y: See above.
  • ur_z: See above.
  • format: Output format for the data section of the response, or ASCII by default.

[1]: https://www.unavco.org/software/geodetic-utilities/plate-motion-calculator/plate-motion-calculator.html. [2]: https://typedtables.juliadata.org/latest/man/table/

PlateMotionRequests.write_platemotionFunction
write_platemotion(file, table)

Write plate motion table to file as tab-delimited text columns or NetCDF. The experimental NetCDF method will be used if file ends with a .nc extension. For tab-delimited output, the first line is a header containing the column names.

Throws a PlateMotionRequests.WriteError if the table header is not recognised, or if attempting to write a NetCDF file of irregularly sampled data.

Note

Irregular sampling of latitude or longitude values is not supported for NetCDF output.

See also: read_platemotion.

PlateMotionRequests.read_platemotionFunction
read_platemotion(file)

Read tab-delimited plate motion data from file. Expects a single tab-delimited header line, with column names that match one of the supported formats. See platemotion for details.

May throw a PlateMotionRequests.ReadError.