List of Functions
The Antarctic Mapping Tools (AMT) package for Matlab contains functions for working with Antarctic geospatial data and creating maps in Matlab. These functions are called by several data-specific plugins for AMT.
Contents
- Lookup functions
- Coordinate Transformations
- Other useful calculations
- Mapping in polar stereographic coordinates
- Mapping in unprojected coordinates
- Mapping with Matlab's Mapping Toolbox
- Helper functions
- Data-specific plugins
- Getting started with AMT
- More examples
- Citing Antarctic Mapping Tools for Matlab
- Author Info
Lookup functions
These functions search databases for location names:
Coordinate Transformations
Currently, polar stereographic coordinate transformations are supported by AMT. Let me know if you'd like to see more.
- ll2ps transforms geo coordinates (lat,lon) to polar stereographic (x,y) meters.
- ps2ll performs the inverse of ll2ps, converting polar stereographic (x,y) meters to georeferenced (lat,lon) coordinates.
- psgrid returns georeferenced coordinates of polar stereographic equally-spaced grids.
- uv2vxvy transforms vector components from zonal and meridional components cartesian grid vx and vy.
- vxvy2uv transforms vector components from cartesian grid vx and vy to zonal and meridional components.
- wgs2gl04c converts WGS84 ellipsoid-referenced elevations to the GL04c geoid.
- gl04c2wgs converts sea level-referenced elevations to WGS84 ellipsoid-referenced elevations using the GL04c geoid.
Other useful calculations
These functions often come in handy when analyzing Antarctic geospatial data:
- inpsquad determines whether points are bounded by a polar stereographic quadrangle.
- pathdist calculates cumulative distance traveled along a flight line, ship track, snowmobile traverse, or satellite ground track. (Requires Mapping Toolbox)
- pathdistps calculates cumulative distance traveled along a flight line, ship track, snowmobile traverse, or satellite ground track. (Does NOT require Mapping Toolbox)
- psdistortion estimates the spatial distortion of a polar stereographic projection.
- pspath creates a path of equal spacing in polar stereographic coordinates, such as for interpolation to a common spacing along any repeat-track analysis.
- pathcrossingps71 finds intersection points of two paths.
- crossovers efficiently calculates self intersections of a spaghetti-like path.
- freeboard2thickness assumes hydrostatic equilibrium to convert ice surface elevation to ice thickness.
- thickness2freeboard assumes hydrostatic equilibrium to convert ice thickness to ice surface elevation.
- base2freeboard assumes hydrostatic equilibrium to convert ice basal elevation to ice surface elevation.
Mapping in polar stereographic coordinates
These functions plot georeferenced (lat,lon) data in polar stereographic meters or kilometers. They do not require Matlab's Mapping Toolbox.
- mapzoomps zooms a polar stereographic map to a location given by name, geo coordinates, or polar stereographic coordinates, and can create inset maps.
- plotps acts like Matlab's plot function, but transforms georeferenced data to polar stereographic cartesian coordinates before plotting.
- plot3ps acts like Matlab's plot3 function, but transforms georeferenced data to polar stereographic cartesian coordinates before plotting.
- pcolorps acts like Matlab's pcolor function, but transforms georeferenced data to polar stereographic coordinates before plotting.
- surfps acts like Matlab's surf function, but transforms georeferenced data to polar stereographic coordinates before plotting.
- patchps acts like Matlab's patch function, but transforms georeferenced data to polar stereographic coordinates before plotting.
- scatterps acts like Matlab's scatter function, but transforms georeferenced data to polar stereographic coordinates before plotting.
- contourps acts like Matlab's contour function, but transforms georeferenced data to polar stereographic coordinates before plotting.
- contourfps acts like Matlab's contourf function, but transforms georeferenced data to polar stereographic coordinates before plotting.
- quiverps is similar to Matlab's quiver function, but transforms zonal and meridional components of vector fields to polar stereographic components before plotting.
- textps acts like Matlab's text function, but transforms georeferenced data to polar stereographic coordinates before plotting.
- graticuleps places a georeferenced grid or graticule on a polar stereographic cartesian coordinate grid.
- circleps places circles of given radii on a polar stereographic map.
- geoquadps plots a box bound by geographic limits, on polar stereographic map.
- scalebarps places a graphical reference scale on polar stereographic coordinates.
- scarlabel labels features by looking up their locations in the SCAR database.
- shadem applies topographic relief shading to DEM data.
- coord returns geo- or polar stereographic coordinates from mouse clicks.
- clickz returns gridded z data such as elevation or velocity interpolated mouse click locations.
Mapping in unprojected coordinates
Oceanographers seem to like making maps in unprojected coordinates, where longitudes are plotted as x values, latitudes are y values, and south is always on the bottom. Unprojected coordinates tend to have quite a bit of spatial distortion near the poles, but if your data are gridded in equally-spaced lats and lons, it might make sense to give each grid cell equal real estate in your plot. If you want to plot in unprojected coordinates, simply use Matlab's standard plotting functions, but replace x with lon and y with lat. For example,
plot(lon,lat) pcolor(lon,lat,z)
and so forth. AMT does not provide much support for plotting in unprojected coordinates. In fact, as of now there's just one function for unprojected coordinates:
- inset_unproj creates an inset map for plotting in unprojected coordinates.
Mapping with Matlab's Mapping Toolbox
I've recently been moving away from dependence on Matlab's Mapping Toolbox because most folks don't have it, it's expensive, it's often computationally inefficient, and troubleshooting can be a bear. Nonetheless, if you do use Matlab's Mapping Toolbox, these functions might make your life a little more convenient:
- antmap initializes a polar stereographic map centered on the South Pole. The antmap function can also be called to place a grid or "graticule".
- mapzoom calls antmap and zooms to any location given by geo coordinates or by location name. The mapzoom function can also create inset maps for zoomed regions.
- scarlabel labels features by looking up their locations in the SCAR database.
- corelabel labels ice core locations.
- scarclick lets you click on a map to get the names of features.
- scalebar places a graphical reference scale on a map.
- shadem applies topographic relief shading to DEM data.
- quivermc shows formatted vector fields such as wind, ice, or water motion.
- coord returns geo- or polar stereographic coordinates from mouse clicks.
- clickz returns gridded z data such as elevation or velocity interpolated mouse click locations.
Helper functions
A couple of functions exist mostly in the background, but were developed at some point or another to assist an AMT plugin.
- islatlon is used for input parsing to determine whether function inputs are likely georeferenced coordinates.
- find2drange returns matrix indices corresponding to a range of input coordinates. This is sometimes used to find relevant pixel indices before loading a large gridded dataset, however for most applications find2drange can now be replaced by inpsquad.
- C2xyz converts a Matlab-formatted contour matrix to x,y,z values.
Data-specific plugins
Here's a list of data-specific plugins available for AMT. Newer datasets may be available, so check the Matlab File Exchange site for the AMT tag if you want to make sure you're up to date:
DEMs and masks
- Antarctic boundaries and masks from Mouginot et al. 2017 has helpful masking functions isgrounded, isiceshelf, isopenocean, etc. This plugin is very useful and highly recommended.
- Bedmap2 Toolbox contains surface, bed, and ice thickness DEMs.
- ALBMAP Le Brocq's consistent dataset of surface, bed, firn air content, heat flux, and a whole lot more.
- BedMachine Morlighem's mass-conserving full ice topography (surface, bed, etc) dataset.
- REMA PGC's Reference Elevation Map of Antarctica high-resolution surface topography.
- CryoSat-2 Toolbox contains functions for fast loading and interpolating CryoSat-2 surface elevation DEM data.
- IBCSO Toolbox contains functions for plotting, interpolating, or accessing raw IBCSO DEM data.
- RTopo-2 contains ice bottom, bed, surface, masks, and water column thickness from Schaffer et al. 2016.
- Bamber et al. DEM contains Antarctic surface elevations from ERS-1 and ICESat.
- CPOM Antarctic surface elevation change Surface elevation changes from CryoSat-2 (Shepherd et al.).
Grounding lines, coast lines, and ice shelf outlines:
- Antarctic boundaries and masks from Mouginot et al. 2017 has an uninterrupted grounding line and coast line.
- asaid ASAID-derived break-in-slope and hydrostatic lines.
- Bedmap2 Toolbox contains a grounding line and coast line inferred from Bedmap2 masks.
- RTopo-2 contains grounding lines and coast lines from Schaffer et al. 2016. Also contains ice shelf outlines given by name.
- MEaSUREs Toolbox contains time-dependent landward limit of flexure (ground line) from the 1990s to today.
- ICESat Grounding Zones plots an ICESat-derived interpretation of different parts of Antarctic grounding zones.
- Grounding Line Migration estimated from Konrad et al., 2018.
Satellite image mosaics:
- MODIS Mosaic of Antarctica plots MODIS Mosaic of Antarctica images.
- lima plots Landsat Image Mosaic of Antarctica images.
- ramp plots Radarsat Image Mosaic of Antarctica images.
Other gridded datasets:
- MEaSUREs Toolbox plots ice speed or ice velocity. Contains tools for interpolation, including interpolation along or across an arbitrary track, such as for calculating ice flux across a grounding line. Also has a function for annual velocities from 2005 to 2016.
- flowline predicts ice flow lines from seed locations using MEaSUREs surface velocity data.
- seaice plots daily sea ice concentration grids.
- SODB Toolbox tools for plotting, interpolating, and creating profiles of Southern Ocean Database data.
- slr_interp interpolates local trends in sea level rise.
- pgr_interp interpolates local trends of glacial isostatic adjustment or post-glacial rebound.
- grainsize_interp returns snow grain sizes from MODIS MOA.
- heatflux_interp returns geothermal heat flux at any Antarctic location(s).
- Antarctic Gravity Data offers raw gridded or interpolated gravity anomalies.
- DTU Mean Dynamic Topography a global 1 min dataset of dynamic topography from Andersen and Knudsen 2009.
- Antarctic accumulation mean accumulation from Arthern et al. 2006.
- Antarctic Gravimetric Mass Balance from Groh and Horwath's processing of GRACE data.
- Antarctic Ice Sheet basal properties basal slipperiness and englacial rate factor from Gudmundsson.
Other polygons:
- basins outlines ice drainage basins from Zwally et al., 2012.
- Antarctic boundaries and masks from Mouginot et al. 2017 contains IMBIE ice basins and IMBIE refined basins.
- smithlakes plots locations of ICESat-detected active subglacial lakes.
- ACC Fronts plots Antarctic Circumpolar Current Fronts.
Tools developed for specific types of analyses:
- bedhead calculates subglacial pressure head or hydrostatic potential.
- iceflex_interp estimates tide-induced vertical flexure in the grounding zone of Antarctic ice shelves.
- ICPcampaign returns UTIG ICECAP field seasons based on timestamps.
Please, feel free to develop and share your own AMT plugins.
Getting started with AMT
If you're new to AMT, new to glaciology, or new to Matlab, I recommend going through the tutorial called AMT Getting Started. It will walk you through some of the basics. Then go though the documentation files for each of the functions and make sure you understand how the work. If anything doesn't make sense or doesn't work, drop me a line and I'll be glad to help troubleshoot.
More examples
Taking inspiration from musical fake books, I have written a number of AMT-related example files and I'm calling them a Glaciology Fake Book. The Glaciology Fake Book is intended to
- teach how scientific results were obtained,
- ensure scientific repeatability, and
- provide examples of how to use AMT functions.
In addition to the Glaciology Fake Book, I've written a few other examples which rely heavily on AMT. How to estimate subglacial flow accumulation uses TopoToolbox to generate subglacial water routing maps. and How to drape Landsat images over Bedmap2 topography explains, well, how to drape Landsat images over Bedmap2 topography.
Citing Antarctic Mapping Tools for Matlab
If Antarctic Mapping Tools is useful for you, please cite the paper that describes AMT. If you use any datasets that are available as plugins for AMT, cite those datasets too. Here's how you can cite AMT:
Greene, C. A., Gwyther, D. E., & Blankenship, D. D. Antarctic Mapping Tools for Matlab. Computers & Geosciences. 104 (2017) pp.151-157. doi:10.1016/j.cageo.2016.08.003.
Or you may prefer BibTeX:
@article{amt,
title={{Antarctic Mapping Tools for \textsc{Matlab}}},
author={Greene, Chad A and Gwyther, David E and Blankenship, Donald D},
journal={Computers \& Geosciences},
year={2017},
volume={104},
pages={151--157},
publisher={Elsevier},
doi={10.1016/j.cageo.2016.08.003},
url={http://www.sciencedirect.com/science/article/pii/S0098300416302163}
}Author Info
Antarctic Mapping Tools, supporting plugins, and all documentation were written by Chad Greene of the University of Texas at Austin's Institute for Geophysics with some help from David Gwyther of the University of Tasmania. Some bits in AMT were adapted from codes written by Andrew Bliss, Kelly Kearney, and Andrew Roberts.