nc5ng-python documentation pages

nc5ng-python is a project providing python libraries for import, analysis, generation, plotting, export, filitering, and manipulation of geodetic datum transformation data.

The source data for transformations come from the United States National Geodetic Survey NADCON5 data and Fortran processing programs linked into python in the nc5ng.org project nadcon5-ng (Home Page) . Transformation grids can be provided from either source or built yourself (See: Install Conversion Data)

Installation

Installation instructions for nc5ng-python

System Installation

nc5ng offers common installation options for python distributions

Note

It is recommended to use a python virtual environment (virtualenv) to install this package and dependencies. Installing directly to a system python distribution can break certain system packages.

Requirements

  • Python 3.x - pip and virtualenv (Recommended)
  • Fortran (gfortran)
  • GMT (4.x-6.x)
  • GMT/Python (Optional) - GMT6.0 Required for ``GMT/Python``(Development Release Only)

Python Package Index

Released versions of nc5ng can be installed directly from the PyPi by using pip

pip install nc5ng

Specific versions can be installed by specifying nc5ng==VERSION

Development Versions

pip can be used to install development versions of python packages by specifying the git repository, including branch or commit

pip install -U git+git://github.com/nc5ng/nc5ng-python@stable
pip install -U git+git://github.com/nc5ng/nc5ng-python@8f482ba1ce6484ab18e6ccd88d6e251655cd61f2

Local Copies can be installed in editable mode for development

git clone git@github.com/nc5ng/nc5ng-python
pip install -U -e ./nc5ng-python

Docker Deployment

Docker images are provided to use nc5ng through container virtualization.

Pre-configured images are available from the nc5ng-docker project (Dockerhub), and base images with gmt tools are available from the gmt-docker project (Dockerhub).

For convenience, the docker image nc5ng/nc5ng contains a pre-compiled conversion for testing.

For more information on deployment and use please see the docker project pages.

Requirements

  • docker
  • docker-compose (Optional)

Install Conversion Data

Raw Source data is provided directly from the nc5ng-core package. However conversion data must either be built or downloaded seperately.

Conversion data are released publically on the nadcon5-ng github or upstream via National Geodetic Survey. For compilation please see the source library docs , project homepage, and github

Conversion data can be placed anywhere and is referenced by configration arguments used to load data.

Reference Manual

nc5ng.nc5data Conversion Data API

PyPi Package: nc5ng-core

nc5ng.gmt GMT Wrapper API

PyPi Package: nc5ng-common

GMT Wrapper Library and Convenience Methods for nc5ng

GMT Options

GMTOptions form a loose wrapper on the GMT command line arguments and GMT/Python shorthands

It is a subtype of dict but has additional properties for creating appropirate GMT arguments

class nc5ng.gmt.GMTOptions(projection='M10.0i', region=[240, 190, 30, 80], frame=True, insert=None, border=None, scale=None, dir_rose=None, mag_rose=None, logo=False, area_thresh=None, lakes=None, resolution='c', land=None, rivers=None, borders=None, water=None, shorelines=1, linear_lines=False, cpt=None, offset=None, errors=None, color=None, symbol=None, pen=None, basemap=None, coast=None, plot=None, **kwargs)[source]

GMTOptions are decorated dictionaries to wrap GMT/Python Keyword options

GMTOptions takes keywords or other dictionary to construct gmt plot options for basemap, coast, plot via properties GMTOptions.basemap, .coast .plot

GMT Options can be combined (copy-combine) by calling one with the other

p1 = GMTOptions(lakes=0) p2 = GMTOptions(**PLOT_OPTS[‘default’])

p3 = p2(p1) # override default by turning off lakes

Warning

GMTOptions do not track single letter GMT Arguments, because ambiguous double-mappings exist (e.g. -A means different things to coast vs plot).

Instead, single letter options can be overriden as keyword arguments to GMTPlotter

GMT Plotter

GMTPlotter forms a loose wrapper around gmt.Figure object, that constructs plots from embedded gmt options inside nc5ng objects (meta-api, object.gmt_meta)

class nc5ng.gmt.plotter.GMTPlotter(base_plot_options={'__class__': <class 'nc5ng.gmt.options.GMTOptions'>, 'area_thresh': 1200, 'basemap': None, 'border': None, 'borders': ['1', '2'], 'coast': None, 'color': None, 'cpt': None, 'dir_rose': None, 'errors': None, 'frame': True, 'insert': None, 'kwargs': {}, 'lakes': None, 'land': None, 'linear_lines': False, 'logo': False, 'mag_rose': None, 'offset': None, 'pen': None, 'plot': None, 'projection': 'M10.0i', 'region': [240, 190, 30, 80], 'resolution': 'fine', 'rivers': None, 'scale': None, 'self': {'offset': None, 'borders': ['1', '2'], 'coast': None, 'rivers': None, 'pen': None, 'region': [240, 190, 30, 80], 'kwargs': {}, 'water': 'lightblue', 'color': None, 'insert': None, 'cpt': None, 'plot': None, 'symbol': None, 'mag_rose': None, '__class__': <class 'nc5ng.gmt.options.GMTOptions'>, 'shorelines': 1, 'land': None, 'border': None, 'frame': True, 'errors': None, 'resolution': 'fine', 'scale': None, 'projection': 'M10.0i', 'linear_lines': False, 'self': {...}, 'area_thresh': 1200, 'dir_rose': None, 'lakes': None, 'logo': False, 'basemap': None}, 'shorelines': 1, 'symbol': None, 'water': 'lightblue'})[source]

Wrapper for GMT/Python Plotter

static plot_conversion(conversion, coverage='all', vector='all', plotter=None, **kwargs)[source]

Static Method to Plot an nc5ng.nc5data.Conversion

Plotting options are Applied in the order

  1. GMTPlotter configured or default options
  2. Conversion configured options Conversion.gmt_meta
  3. Data Set Options PointData.gmt_meta
  4. Keyword overrides (full option name)
  5. Keyowrd overrides (single letter GMT Style arguments)
Parameters:
  • conversion – Conversion data
  • coverage – Coverage files (no file extension), to plot. Can be list of names (coverage = ['cvacdlat','cvacdlon',]), single file name (coverage = 'cvacdlat'), None, or 'all'
  • vector – Vector files (no file extension) to plot. Can be list of names, single file name, None, or 'all'.
  • plotter – plotter to use, if None one will be created and returned

nc5ng.types Core Types

PyPi Package: nc5ng-common

Indices and tables