.. role:: raw-html-m2r(raw)
:format: html
Remapper for "online" remapping of data sets
============================================
:raw-html-m2r:`
Xylar Asay-Davis
date: 2017/04/15
`
.. raw:: html
Summary
This document describes the design and implementation of a ``Remapper`` class
for performing either "online" (in memory) or "offline" (through files
via ``ncremap``\ ) remapping of horizontal data sets. The ``Remapper`` is needed in
order to support remapping to and from grids grids not currently supported by
``ncremap`` such as polar stereographic grids commonly used for polar data sets.
.. raw:: html
Requirements
.. raw:: html
Requirement: Support for remapping to and from stereographic grids
Date last modified: 2017/04/15
Contributors: Xylar Asay-Davis
There should exist a method for interpolating from stereographic grids to
the comparison grid used in MPAS-Analysis. This is needed to support
observations that are stored on stereographic grids.
It would often be more efficient (in terms of the size of data sets) and more
practical to perform analysis of polar data sets on a stereographic grid
centered at that pole. Support for mapping to stereographic grids should be
included, if feasible.
.. raw:: html
Algorithmic Formulations
.. raw:: html
Design solution: Support for remapping to and from stereographic grids
Date last modified: 2017/04/15
Contributors: Xylar Asay-Davis
The design solution is somewhat complex and will be described in multiple
sections.
.. raw:: html
MeshDescriptor classes
To support mapping to and from MPAS meshes, lat/lon grid and stereographic
grids (as well as future grids we might want to support), I propose defining a
"mesh descriptor" that defines the mesh either by reading it from a file or by
creating it from simple numpy ndarrays. Each ``MeshDescriptor`` class defines
enough information (such as the locations of cell centers and corners) about
the mesh or grid to allow remapping between meshes.
An ``MpasMeshDescriptor`` class will define MPAS meshes read from a file.
A ``LatLonGridDescriptor`` class will define global lat/lon grids such as the
existing comparison grid.
A ``ProjectionGridDescriptor`` class will define any grid that can be described
by a logically rectangular grid with ``pyproj`` projection. In particular, such
a projection grid could be used to support both polar stereographic grids and
regional lat/lon grids.
.. raw:: html
Remapper class
Remapping between meshes described by ``MeshDescriptor`` classes will be performed
by a ``Remapper`` class. This class will support both "online" mapping in memory
and "offline" mapping with ``ncremap``. Only "online" mapping will be supported
for grids defined with the ``ProjectionGridDescriptor``\ , as these are not
supported by ``ncremap``. A ``Remapper`` object will be created by giving it source
and destintion ``MeshDescriptor`` objects and an optional mapping file name.
(If the mapping file name is not given, it is assumed that the source and
destination grids are the same, and no remapping is needed.)
If remapping is performed "online", it supports renormalization of masked
arrays. If a data sets includes ``NaN``\ s in a given data array, both the data
array and a mask are remapped, and renormalization is performed anywhere the
remapped mask exceeds a given threshold.
.. raw:: html
Design and Implementation
.. raw:: html
Implementation: Support for remapping to and from stereographic grids
Date last modified: 2017/04/15
Contributors: Xylar Asay-Davis
The implementation is on the branch `xylar/MPAS-Analysis/add_polar_stereographic_interp `_
.. raw:: html
MeshDescriptor classes
Each ``MeshDescriptor`` subclass includes the following member variables or
methods:
* ``meshName``\ : a name of the mesh or grid, used for naming mapping files and
climatologies
* ``regional``\ : whether the mesh is regional or global
* ``coords`` and ``dims``\ : dictionaries defining the coordinates and dimensions
of this mesh, used to update a data set following remapping
* ``to_scrip`` method: used to write out a SCRIP file defining the mesh.
.. raw:: html
Remapper class
Below is a skeleton of the ``Remapper`` public API.
.. code-block:: python
class Remapper(object):
def __init__(self, sourceDescriptor, destinationDescriptor,
mappingFileName=None):
'''
Create the remapper and read weights and indices from the given file
for later used in remapping fields.
'''
def build_mapping_file(self, method='bilinear',
additionalArgs=None):
'''
Given a source file defining either an MPAS mesh or a lat-lon grid and
a destination file or set of arrays defining a lat-lon grid, constructs
a mapping file used for interpolation between the source and
destination grids.
'''
def remap_file(self, inFileName, outFileName,
variableList=None, overwrite=False):
'''
Given a source file defining either an MPAS mesh or a lat-lon grid and
a destination file or set of arrays defining a lat-lon grid, constructs
a mapping file used for interpolation between the source and
destination grids.
'''
def remap(self, ds, renormalizationThreshold=None):
'''
Given a source data set, returns a remapped version of the data set,
possibly masked and renormalized.
'''
.. raw:: html
Testing and Validation: Support for remapping to and from stereographic
grids
Date last modified: 2017/04/15
Contributors: Xylar Asay-Davis
On the branch `xylar/MPAS-Analysis/add_polar_stereographic_interp `_\ ,
climatologies have ben updated to use ``Remapper`` objects. Analysis has been
run on both ``QU240`` and ``EC60to30`` beta0 ACME results, and results have been
compared by eye. Results from ``ncremap`` are identical, as expected. Because of
renormalization, results with "online" remapping differ from those from
``ncremap``\ , typically with less severe masking of missing data.
Continuous integration unit tests for climatology and interpolation have both
been updated to make use of the ``Remapper`` class. New tests have been added to
perform remapping with stereographic grids.