polartoolkit package#
Helpful tools for polar researchers
Submodules#
polartoolkit.fetch module#
- class EarthDataDownloader[source]#
Bases:
objectEither pulls login details from pre-set environment variables, or prompts user to input username and password. Will persist the entered details within the python session.
- antarctic_boundaries(version)[source]#
Load various files from the MEaSUREs Antarctic Boundaries for IPY 2007-2009
from Mouginot et al.[1]. accessed at https://nsidc.org/data/nsidc-0709/versions/2
Requires an EarthData login, see Tutorials/Download Polar datasets for how to configure this.
- Parameters:
version (str,) – choose which file to retrieve from the following list: “Coastline”, “Basins_Antarctica”, “Basins_IMBIE”, “IceBoundaries”, “IceShelf”, “Mask”
- Returns:
file path
- Return type:
References
- basal_melt(version='w_b', variable=None, region=None, spacing=None, registration=None, **kwargs)[source]#
Antarctic ice shelf basal melt rates for 1994-2018 from satellite radar altimetry. from Adusumilli et al.[2].
accessed from http://library.ucsd.edu/dc/object/bb0448974g
reading files and preprocessing from supplied jupyternotebooks: sioglaciology/ice_shelf_change
Units are in m/yr
- Parameters:
version (str) – choose which version to load, either ‘w_b’ for basal melt rate, ‘w_b_interp’, for basal melt rate with interpolated values, and ‘w_b_uncert’ for uncertainty
- Returns:
Returns a dataarray of basal melt rate values
- Return type:
References
- bedmachine(layer, reference='eigen-6c4', region=None, spacing=None, registration=None, hemisphere=None, **kwargs)[source]#
Load BedMachine topography data from either Greenland (v5) or Antarctica (v3), from Morlighem[3] or IceBridge BedMachine Greenland, Version 5[4].
Antarctica: Accessed from NSIDC via https://nsidc.org/data/nsidc-0756/versions/3. Also available from ldeo-glaciology/pangeo-bedmachine
Greenland: Accessed from NSIDC via https://nsidc.org/data/idbmg4/versions/5
Referenced to the EIGEN-6C4 geoid. To convert to be ellipsoid-referenced, we add the geoid grid. use reference=’ellipsoid’ to include this conversion in the fetch call.
For Antarctica: Surface and ice thickness are in ice equivalents. Actual snow surface is from REMA [5], and has had firn thickness added(?) to it to get Bedmachine Surface.
To get snow surface: surface+firn To get firn and ice thickness: thickness+firn
Here, icebase will return a grid of surface-thickness This should be the same as snow-surface - (firn and ice thickness)
Requires an EarthData login, see Tutorials/Download Polar datasets for how to configure this.
- Parameters:
layer (str) – choose which layer to fetch: ‘bed’, ‘dataid’, ‘errbed’, ‘firn’, ‘geoid’, ‘mask’, ‘source’, ‘surface’, ‘ice_thickness’; ‘icebase’ will give results of surface-thickness
reference (str) – choose whether heights are referenced to ‘eigen-6c4’ geoid or the ‘ellipsoid’ (WGS84), by default is eigen-6c4’
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 500m. If spacing >= 5000m, will resample the grid to 5km, and save it as a preprocessed grid, so future fetch calls are performed faster.
registration (str, optional) – change registration with either ‘p’ for pixel or ‘g’ for gridline registration, by default is None.
hemisphere (str, optional) – choose which hemisphere to retrieve data for, “north” or “south”, by default None
**kwargs (Any) – additional keyword arguments to pass to the resample_grid function
- Returns:
Returns a loaded, and optional clip/resampled grid of Bedmachine.
- Return type:
References
- bedmap2(layer, reference='eigen-gl04c', region=None, spacing=None, registration=None, fill_nans=False, **kwargs)[source]#
Load bedmap2 data as xarray.DataArrays from Fretwell et al.[6]. accessed from https://ramadda.data.bas.ac.uk/repository/entry/show?entryid=fa5d606c-dc95-47ee-9016-7a82e446f2f2.
All grids are by default referenced to the EIGEN-GL04C geoid. Use the reference=’ellipsoid’ to convert to the WGS-84 ellipsoid or reference=’eigen-6c4’ to convert to the EIGEN-6c4 geoid.
Unlike Bedmachine data, Bedmap2 surface and icethickness contain NaN’s over the ocean, instead of 0’s. To fill these NaN’s with 0’s, set fill_nans=True. Note, this only makes since if the reference is the geoid, therefore, if reference=’ellipsoid and fill_nans=True, the nan’s will be filled before converting the results to the geoid (just for surface, since thickness isn’t relative to anything).
- Parameters:
layer (str) – choose which layer to fetch: “bed”, “coverage”, “grounded_bed_uncertainty”, “icemask_grounded_and_shelves”, “lakemask_vostok”, “rockmask”, “surface”, “ice_thickness”, “ice_thickness_uncertainty”, “gl04c_geiod_to_WGS84”, “icebase”, “water_thickness”
reference (str) – choose whether heights are referenced to the ‘eigen-6c4’ geoid, the WGS84 ellipsoid, ‘ellipsoid’, or by default the ‘eigen-gl04c’ geoid.
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 1000m. If spacing >= 5000m, will resample the grid to 5km, and save it as a preprocessed grid, so future fetch calls are performed faster.
registration (str, optional,) – choose between ‘g’ (gridline) or ‘p’ (pixel) registration types, by default is the original type of the grid
fill_nans (bool, optional,) – choose whether to fill nans in ‘surface’ and ‘thickness’ with 0. If converting to reference to the geoid, will fill nan’s before conversion, by default is False
**kwargs (optional) – additional keyword arguments to pass to the resample_grid function
- Returns:
Returns a loaded, and optional clip/resampled grid of Bedmap2.
- Return type:
References
- bedmap3(layer, reference='eigen-gl04c', region=None, spacing=None, registration=None, fill_nans=False, **kwargs)[source]#
Load Bedmap3 data as an xarray.DataArray from Pritchard et al.[7]. accessed from https://ramadda.data.bas.ac.uk/repository/entry/show?entryid=2d0e4791-8e20-46a3-80e4-f5f6716025d2.
All grids are by default referenced to the EIGEN-GL04C geoid. Use the reference=’ellipsoid’ to convert to the WGS-84 ellipsoid or reference=’eigen-6c4’ to convert to the EIGEN-6c4 geoid.
Unlike Bedmachine data, Bedmap2 surface and icethickness contain NaN’s over the ocean, instead of 0’s. To fill these NaN’s with 0’s, set fill_nans=True. Note, this only makes since if the reference is the geoid, therefore, if reference=’ellipsoid and fill_nans=True, the nan’s will be filled before converting the results to the geoid (just for surface, since thickness isn’t relative to anything).
- Parameters:
layer (str) – choose which layer to fetch: “surface”, “icebase”, “bed”, “ice_thickness”, “water_thickness”, “bed_uncertainty”, “ice_thickness_uncertainty”, and “mask”.
reference (str) – choose whether heights are referenced to the ‘eigen-6c4’ geoid, the WGS84 ellipsoid, ‘ellipsoid’, or by default the ‘eigen-gl04c’ geoid.
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 500m. If spacing >= 5000m, will resample the grid to 5km, and save it as a preprocessed grid, so future fetch calls are performed faster.
registration (str, optional,) – choose between ‘g’ (gridline) or ‘p’ (pixel) registration types, by default is the original type of the grid
fill_nans (bool, optional,) – choose whether to fill nans in ‘surface’ and ‘thickness’ with 0. If converting to reference to the geoid, will fill nan’s before conversion, by default is False
**kwargs (optional) – additional keyword arguments to pass to the resample_grid function
- Returns:
Returns a loaded, and optional clip/resampled grid of Bedmap2.
- Return type:
References
- bedmap_points(version, region=None)[source]#
Load bedmap point data, choose from Bedmap 1, 2 or 3 or all combined.
All elevations are in meters above the WGS84 ellipsoid.
version == ‘bedmap1’ from Lythe and Vaughan[8]. accessed from https://data.bas.ac.uk/full-record.php?id=GB/NERC/BAS/PDC/01619
version == ‘bedmap2’ from Fretwell et al.[6]. accessed from https://data.bas.ac.uk/full-record.php?id=GB/NERC/BAS/PDC/01616
version == ‘bedmap3’ from Fremand et al.[9]. accessed from https://data.bas.ac.uk/full-record.php?id=GB/NERC/BAS/PDC/01614#access-data download link was found from https://ramadda.data.bas.ac.uk/repository/entry/show?entryid=61100714-1e32-44af-a237-0a517529bc49 under DOI/BEDMAP3 datapoints, right click on the download link and copy link address
- Parameters:
- Returns:
Return a dataframe, optionally subset by a region
- Return type:
References
- buttressing(version, variable=None, region=None, spacing=None, registration=None, **kwargs)[source]#
Antarctic ice shelf buttressing. from Fürst et al.[10].
accessed from https://nsidc.org/data/nsidc-0664/versions/1
Units are in m/yr
- Parameters:
version (str) – choose which version to load, either ‘max’ for maximum buttressing, ‘min’ for minimum buttressing, ‘flow’ for along-flow buttressing, or ‘viscosity’ for estimated ice viscosity values
- Returns:
Returns a dataarray of buttressing or viscosity values
- Return type:
References
- crustal_thickness(version, region=None, spacing=None, registration=None, **kwargs)[source]#
Load 1 of x ‘versions’ of Antarctic crustal thickness grids.
version=’shen-2018’ Crustal thickness (excluding ice layer) from Shen et al.[11]. Accessed from https://sites.google.com/view/weisen/research-products?authuser=0
version=’an-2015’ Crustal thickness (distance from solid (ice and rock) top to Moho discontinuity) from An et al.[12]. Accessed from http://www.seismolab.org/model/antarctica/lithosphere/index.html#an1s File is the AN1-CRUST model, paper states “Moho depths and crustal thicknesses referred to below are the distance from the solid surface to the Moho. We note that this definition of Moho depth is different from that in the compilation of AN-MOHO”. Unclear, but seems moho depth is just negative of crustal thickness. Not sure if its to the ice surface or ice base.
- Parameters:
version (str) – Either ‘shen-2018’, will add later: ‘lamb-2020’, ‘an-2015’, ‘baranov’, ‘chaput’, ‘crust1’, ‘szwillus’, ‘llubes’, ‘pappa’, ‘stal’
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (int, optional) – grid spacing to resample the loaded grid to, by default spacing is read from downloaded files
registration (str, optional) – change registration with either ‘p’ for pixel or ‘g’ for gridline registration, by default is None.
**kwargs (Any) – additional keyword arguments to pass to the resample_grid function
- Returns:
Returns a loaded, and optional clip/resampled grid of crustal thickness.
- Return type:
References
- deepbedmap(region=None, spacing=None, registration=None, **kwargs)[source]#
Load DeepBedMap data, from Leong and Horgan[13] and Leong and Horgan[14].
- Parameters:
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 10e3
registration (str, optional) – change registration with either ‘p’ for pixel or ‘g’ for gridline registration, by default is None.
**kwargs (optional) – additional keyword arguments to pass to the resample_grid function
- Returns:
Returns the grid of DeepBedMap.
- Return type:
References
- etopo(region=None, spacing=None, registration=None, hemisphere=None, **kwargs)[source]#
Loads a grid of Antarctic topography from ETOPO1 from ETOPO1 1 Arc-Minute Global Relief Model: Procedures, Data Sources and Analysis[15]. Originally at 10 arc-min resolution, reference to mean sea-level (geoid).
originally from https://www.ncei.noaa.gov/access/metadata/landing-page/bin/iso?id=gov.noaa.ngdc.mgg.dem:316 Accessed via the Fatiando data repository fatiando-data/earth-topography-10arcmin
- Parameters:
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 10e3
registration (str, optional) – change registration with either ‘p’ for pixel or ‘g’ for gridline registration, by default is None.
hemisphere (str, optional) – choose which hemisphere to retrieve data for, “north” or “south”, by default None
**kwargs (optional) – additional keyword arguments to pass to the resample_grid function
- Returns:
Returns a loaded, and optional clip/resampled grid of topography.
- Return type:
References
- geoid(region=None, spacing=None, registration=None, hemisphere=None, **kwargs)[source]#
Loads a grid of Antarctic geoid heights derived from the EIGEN-6C4 from Förste et al.[16] spherical harmonic model of Earth’s gravity field. Originally at 10 arc-min resolution. Negative values indicate the geoid is below the ellipsoid surface and vice-versa. To convert a topographic grid which is referenced to the ellipsoid to be referenced to the geoid, add this grid. To convert a topographic grid which is referenced to the geoid to be referencde to the ellipsoid, add this grid.
originally from https://dataservices.gfz-potsdam.de/icgem/showshort.php?id=escidoc:1119897 Accessed via the Fatiando data repository fatiando-data/earth-geoid-10arcmin DOI: 10.5281/zenodo.5882205
- Parameters:
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 10e3
registration (str, optional) – change registration with either ‘p’ for pixel or ‘g’ for gridline registration, by default is None.
hemisphere (str, optional) – choose which hemisphere to retrieve data for, “north” or “south”, by default None
kwargs (Any) – additional kwargs to pass to resample_grid.
- Returns:
Returns a loaded, and optional clip/resampled grid of geoid height.
- Return type:
References
- geomap(version='faults', region=None)[source]#
Data from GeoMAP accessed from https://doi.pangaea.de/10.1594/PANGAEA.951482?format=html#download
from Cox et al.[17] and Cox et al.[18].
- Parameters:
- Returns:
Returns a geodataframe
- Return type:
References
- ghf(version, region=None, spacing=None, registration=None, **kwargs)[source]#
Load 1 of 6 ‘versions’ of Antarctic geothermal heat flux data.
version=’an-2015’ From An et al.[19]. Accessed from http://www.seismolab.org/model/antarctica/lithosphere/index.html
version=’martos-2017’ From Martos et al.[20] and Martos[21]. Accessed from https://doi.pangaea.de/10.1594/PANGAEA.882503
version=’shen-2020’: From Shen et al.[22]. Accessed from https://sites.google.com/view/weisen/research-products?authuser=0 Used https://paperform.co/templates/apps/direct-download-link-google-drive/ to generate a direct download link from google drive page. https://drive.google.com/uc?export=download&id=1Fz7dAHTzPnlytuyRNctk6tAugCAjiqzR
version=’burton-johnson-2020’ From Burton-Johnson et al.[23]. Accessed from supplementary material Choose for either of grid, or the point measurements
version=’losing-ebbing-2021’ From Lösing and Ebbing[24] and Lösing and Ebbing[25]. Accessed from https://doi.pangaea.de/10.1594/PANGAEA.930237
version=’aq1’ From Stål et al.[26] and Stål et al.[27]. Accessed from https://doi.pangaea.de/10.1594/PANGAEA.924857
- Parameters:
version (str) – Either ‘burton-johnson-2020’, ‘losing-ebbing-2021’, ‘aq1’,
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (int, optional) – grid spacing to resample the loaded grid to, by default spacing is read from downloaded files
registration (str, optional) – change registration with either ‘p’ for pixel or ‘g’ for gridline registration, by default is None.
kwargs (Any) – if version=’burton-johnson-2020’, then kwargs are passed to return point measurements instead of the grid.
**kwargs (Any) – additional keyword arguments to pass to the resample_grid function
- Returns:
Returns a loaded, and optional clip/resampled grid of GHF data.
- Return type:
References
- gia(version, region=None, spacing=None, registration=None, **kwargs)[source]#
Load 1 of 1 ‘versions’ of Antarctic glacial isostatic adjustment grids.
version=’stal-2020’ From Stål et al.[28] and Stål et al.[29].
- Parameters:
version (str) – For now the only option is ‘stal-2020’,
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (int, optional) – grid spacing to resample the loaded grid to, by default spacing is read from downloaded files
registration (str, optional) – change registration with either ‘p’ for pixel or ‘g’ for gridline registration, by default is None.
**kwargs (Any) – additional keyword arguments to pass to the resample_grid function
- Returns:
Returns a loaded, and optional clip/resampled grid of GIA data.
- Return type:
References
- gravity(version, region=None, spacing=None, registration=None, hemisphere=None, **kwargs)[source]#
Loads gravity anomaly data for the Arctic and Antarctic.
version=’antgg’ Antarctic-wide gravity data compilation of ground-based, airborne, and shipborne data, from Scheinert et al.[30]. Accessed from https://doi.pangaea.de/10.1594/PANGAEA.848168 Anomalies are at the ice surface, or bedrock surface in areas of no ice. These surfaces are defined by Bedmap2 and are relative to the ellipsoid.
version=’antgg-2021’ Updates on 2016 AntGG compilation. Accessed from https://doi.pangaea.de/10.1594/PANGAEA.971238?format=html#download Anomalies are at the ice surface, or bedrock surface in areas of no ice. These surfaces are defined by Bedmap2 and are relative to the ellipsoid.
version=’eigen’ Earth gravity grid (eigen-6c4) at 10 arc-min resolution at 10km geometric (ellipsoidal) height from Förste et al.[16]. originally from https://dataservices.gfz-potsdam.de/icgem/showshort.php?id=escidoc:1119897 Accessed via the Fatiando data repository fatiando-data/earth-gravity-10arcmin
- Parameters:
version (str) – choose which version of gravity data to fetch.
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 10e3
registration (str, optional) – change registration with either ‘p’ for pixel or ‘g’ for gridline registration, by default is None.
hemisphere (str, optional) – choose which hemisphere to retrieve data for, “north” or “south”, by default None
kwargs (Any) – additional kwargs to pass to resample_grid and set the anomaly_type.
- Keyword Arguments:
anomaly_type (str) – either ‘FA’ or ‘BA’, for free-air and bouguer anomalies, respectively. For antgg-update can also be ‘DG’ for gravity disturbance, or ‘Err’ for error estimates.
- Returns:
Returns a loaded, and optional clip/resampled grid of either observed, free-air or Bouguer gravity anomalies.
- Return type:
References
- groundingline(version='measures-v2')[source]#
Load the file path of two versions of groundingline shapefiles
version = “depoorter-2013” from Depoorter et al.[31]. Supplement to Depoorter et al.[32]. accessed at https://doi.pangaea.de/10.1594/PANGAEA.819147
version = “measures-v2” from Mouginot et al.[1]. accessed at https://nsidc.org/data/nsidc-0709/versions/2
version = “BAS” from Gerrish[33]. accessed at https://ramadda.data.bas.ac.uk/repository/entry/show?entryid=8cecde06-8474-4b58-a9cb-b820fa4c9429
version = “measures-greenland” from Haran et al.[34].
Some versions require an EarthData login, see Tutorials/Download Polar datasets for how to configure this.
- Parameters:
version (str, optional) – choose which version to retrieve, by default “measures-v2”
- Returns:
file path
- Return type:
References
- ibcso(layer, reference='geoid', region=None, spacing=None, registration=None, **kwargs)[source]#
Load IBCSO v2 data, from Dorschel et al.[35] and Dorschel et al.[36].
By default the elevations are relative to Mean Sea Level (the geoid). To convert them to be relative to the WGS84 ellipsoid, set reference=”ellipsoid which will add the EIGEN-6C4 geoid anomaly.
- Parameters:
layer (str) – choose which layer to fetch: ‘surface’, ‘bed’
reference (str, optional) – choose which vertical reference to use, ‘geoid’ or ‘ellipsoid’, by default ‘geoid’
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 500m. If spacing >= 5000m, will resample the grid to 5km, and save it as a preprocessed grid, so future fetch calls are performed faster.
registration (str, optional) – change registration with either ‘p’ for pixel or ‘g’ for gridline registration, by default is None.
**kwargs (Any) – additional keyword arguments to pass to the resample_grid function
- Returns:
Returns a loaded, and optional clip/resampled grid of IBCSO data.
- Return type:
References
- ibcso_coverage(region=None)[source]#
Load IBCSO v2 data, from Dorschel et al.[35] and Dorschel et al.[36].
- Parameters:
region (tuple[float, float, float, float] or None) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
- Returns:
Returns two geodataframes; points and polygons for a subset of IBCSO v2 point measurement locations. Column ‘dataset_tid’ is the type identifier from IBCSO. The points geodataframe contains all individual point measurements, including single-beam (TID 10), seismic points (TID 12), isolated soundings (TID 13), ENC sounding (TID 14), grounded iceberg draft (TID 46), and gravity-inverted bathymetry (TID 45). The polygon geodataframe contains all polygon measurements, including multi-beam (swath) (TID 11), contours from charts (TID 42), or other unknown sources (TID 71).
- Return type:
References
- ice_vel(region=None, spacing=None, registration=None, hemisphere=None, **kwargs)[source]#
MEaSUREs Phase-Based Ice Velocity Maps for Antarctica and Greenland.
Antarctica: version 1 from Mouginot et al.[37] and Mouginot et al.[38].
accessed from https://cmr.earthdata.nasa.gov/virtual-directory/collections/C3298047930-NSIDC_CPRD Data part of https://doi.org/10.1029/2019GL083826
Greenland: version 1 from MEaSUREs Multi-year Greenland Ice Sheet Velocity Mosaic, Version 1[39]
accessed from https://cmr.earthdata.nasa.gov/virtual-directory/collections/C3291956575-NSIDC_CPRD
Units are in m/yr
Requires an EarthData login, see Tutorials/Download Polar datasets for how to configure this.
- Parameters:
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (float, optional,) – grid spacing to resample the loaded grid to, by default is 5km for Antarctica (original data is 450m), and 250m for Greenland
registration (str, optional) – change registration with either ‘p’ for pixel or ‘g’ for gridline registration, by default is None.
hemisphere (str, optional) – choose which hemisphere to retrieve data for, “north” or “south”, by default None
kwargs (Any) – additional keyword arguments to pass to resample_grid
- Returns:
Returns a calculated grid of ice velocity in meters/year.
- Return type:
References
- imagery()[source]#
Load the file path of Antarctic imagery geotiff from LIMA from Bindschadler et al.[40]. accessed from https://lima.usgs.gov/
will replace with below once figured out login issue with pooch MODIS Mosaic of Antarctica: https://doi.org/10.5067/68TBT0CGJSOJ Assessed from https://daacdata.apps.nsidc.org/pub/DATASETS/nsidc0730_MEASURES_MOA2014_v01/geotiff/
- Returns:
file path
- Return type:
References
- magnetics(version, region=None, spacing=None, registration=None, hemisphere=None, **kwargs)[source]#
Load magnetic anomaly data for the Arctic and Antarctic. from Golynsky et al.[41] and Golynsky et al.[42].
version=’admap1’ ADMAP-2001 magnetic anomaly compilation of Antarctica. Accessed from http://admap.kopri.re.kr/databases.html
version=’admap2’ ADMAP2 magnetic anomaly compilation of Antarctica from Golynsky et al.[43]. Accessed from https://doi.pangaea.de/10.1594/PANGAEA.892723?format=html#download
version=’admap2_gdb’ Geosoft-specific .gdb abridged files Golynsky et al.[44]. Accessed from https://doi.pangaea.de/10.1594/PANGAEA.892722?format=html#download
version=’LCS-1’ Satellite-only derived magnetic anomaly at Earth’s surface (WGS84 ellipsoid) for spherical harmonic degrees n=14-185 Accessed from https://www.spacecenter.dk/files/magnetic-models/LCS-1/
- Parameters:
version (str) – Either ‘admap1’, ‘admap2’, ‘admap2_gdb’ or ‘LCS-1’.
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 10e3
registration (str, optional,) – choose between ‘g’ (gridline) or ‘p’ (pixel) registration types, by default is the original type of the grid
hemisphere (str, optional) – choose which hemisphere to retrieve data for, “north” or “south”, by default None
kwargs (Any) – key word arguments to pass to resample_grid.
- Returns:
Returns a loaded, and optional clip/resampled grid of magnetic anomalies.
- Return type:
References
- mass_change(version=None, hemisphere=None, region=None, spacing=None, registration=None, **kwargs)[source]#
Ice-sheet height and thickness changes from ICESat to ICESat-2 for both Antarctica and Greenland from Smith et al.[45].
Choose a version of the data to download with the format: “ICESHEET_VERSION_TYPE” where ICESHEET is “ais” or “gris”, for Antarctica or Greenland, VERSION is “dhdt” for total thickness change or “dmdt” for corrected for firn-air content. For Antarctic data, TYPE is “floating” or “grounded”.
add “_filt” to retrieve a filtered version of the data for some versions.
accessed from https://digital.lib.washington.edu/researchworks/handle/1773/45388
Units are in m/yr
- Parameters:
version (str, optional,) – choose which version to retrieve, by default is “ais_dhdt_grounded” for Antarctica and “gris_dhdt” for Greenland.
hemisphere (str, optional) – choose which hemisphere to retrieve data for, “north” or “south”, by default None
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (float, optional,) – grid spacing to resample the loaded grid to, by default is 5km
registration (str, optional) – change registration with either ‘p’ for pixel or ‘g’ for gridline registration, by default is “p”.
kwargs (Any) – additional keyword arguments to pass to resample_grid
- Returns:
Returns a grid of Antarctic or Greenland ice mass change in meters/year.
- Return type:
References
- measures_boundaries(version=None)[source]#
Deprecated, see the new function antarctic_boundaries instead
Deprecated since version 0.4.0: This will be removed in 2.0.0. Use the new function antarctic_boundaries instead
- modis(version=None, hemisphere=None)[source]#
Load the MODIS Mosaic of Antarctica (MoA) or Greenland (MoG) imagery.
Antarctica: from Haran et al.[46] and Scambos et al.[47].
accessed from https://nsidc.org/data/nsidc-0593/versions/2
Greenland: from Haran et al.[34] accessed from https://nsidc.org/data/nsidc-0547/versions/2
Requires an EarthData login, see Tutorials/Download Polar datasets for how to configure this.
- Parameters:
- Returns:
filepath for MODIS Imagery
- Return type:
References
- modis_moa(version='750m')[source]#
deprecated function, use modis(hemisphere=”south”) instead
Deprecated since version 0.4.0: This will be removed in 2.0.0. Use the new function modis(hemisphere=’south’) instead
- modis_mog(version='500m')[source]#
deprecated function, use modis(hemisphere=”north”) instead
Deprecated since version 0.4.0: This will be removed in 2.0.0. Use the new function modis(hemisphere=’north’) instead
- moho(version, region=None, spacing=None, registration=None, **kwargs)[source]#
Load 1 of x ‘versions’ of Antarctic Moho depth grids.
version=’shen-2018’ Depth to the Moho relative to the surface of solid earth (bottom of ice/ocean) from Shen et al.[11]. Accessed from https://sites.google.com/view/weisen/research-products?authuser=0 Appears to be almost identical to crustal thickness from Shen et al. 2018
version=’an-2015’ This is fetch.crustal_thickness(version=’an-2015)* -1 Documentation is unclear whether the An crust model from An et al.[12] is crustal thickness or moho depths, or whether it makes a big enough difference to matter.
version=’pappa-2019’ from Pappa et al.[48]. Accessed from supplement material
- Parameters:
version (str) – Either ‘shen-2018’, ‘an-2015’, ‘pappa-2019’, will add later: ‘lamb-2020’, ‘baranov’, ‘chaput’, ‘crust1’, ‘szwillus’, ‘llubes’,
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (int, optional) – grid spacing to resample the loaded grid to, by default spacing is read from downloaded files
registration (str, optional,) – choose between ‘g’ (gridline) or ‘p’ (pixel) registration types, by default is the original type of the grid
**kwargs (Any) – additional keyword arguments to pass to the resample_grid function
- Returns:
Returns a loaded, and optional clip/resampled grid of crustal thickness.
- Return type:
References
- rema(version='1km', region=None, spacing=None, registration=None, **kwargs)[source]#
Load the REMA surface elevation data from Howat et al.[5]. The data are in EPSG3031 and reference to the WGS84 ellipsoid. To convert the data to be geoid-referenced, subtract a geoid model, which you can get from fetch.geoid().
Choose between “1km” or “500m” resolutions with parameter version.
accessed from https://www.pgc.umn.edu/data/rema/
- Parameters:
version (str, optional,) – choose which resolution to fetch, either “1km” or “500m”, by default is “1km”
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 10e3
registration (str, optional,) – choose between ‘g’ (gridline) or ‘p’ (pixel) registration types, by default is the original type of the grid
**kwargs (optional) – additional keyword arguments to pass to the resample_grid function
- Returns:
Returns a loaded, and optional clip/resampled grid of the REMA DEM.
- Return type:
References
- resample_grid(grid, spacing=None, region=None, registration=None, **kwargs)[source]#
Resample a grid to a new spacing, region, and/or registration. Method of resampling depends on comparison with initial and supplied values for spacing, region, and registration. If initial values not supplied, will try and extract them from the grid.
- Parameters:
grid (xarray.DataArray) – grid to resample
spacing (float | None, optional) – new spacing for grid, by default None
region (tuple[float, float, float, float] | None, optional) – new region for grid in format [xmin, xmax, ymin, ymax], by default None
registration (str | None, optional) – new registration for grid, by default None
- Returns:
grid, either resampled or same as original depending on inputs. If no resampling, and supplied grid is a filepath, returns filepath.
- Return type:
- sediment_thickness(version, region=None, spacing=None, registration=None, **kwargs)[source]#
Load 1 of 4 ‘versions’ of sediment thickness data.
version=’ANTASed’ From Baranov et al.[49]. Accessed from https://www.itpz-ran.ru/en/activity/current-projects/antased-a-new-sediment-model-for-antarctica/
version=’tankersley-2022’ From Tankersley et al.[50], Tankersley et al.[51].
version=’lindeque-2016’ From Lindeque et al.[52] and Lindeque et al.[53].
version=’GlobSed’ From Straume et al.[54]. Accessed from https://ngdc.noaa.gov/mgg/sedthick/
- Parameters:
version (str,) – choose which version of data to fetch.
region (tuple[float, float, float, float], optional) – region to clip the loaded grid to, in format [xmin, xmax, ymin, ymax], by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 10e3
registration (str, optional) – change registration with either ‘p’ for pixel or ‘g’ for gridline registration, by default is None.
**kwargs (Any) – additional keyword arguments to pass to the resample_grid function
- Returns:
Returns a loaded, and optional clip/resampled grid of sediment thickness.
- Return type:
References
polartoolkit.maps module#
- class Figure(fig=None, reg=None, hemisphere=None, height=None, width=None)[source]#
Bases:
FigureA simple class that inherits from a pygmt Figure instance and stores additional figure parameters for easy access and provides addition methods.
- Parameters:
- add_coast(no_coast=False, pen=None, version=None, label=None)[source]#
add coastline and or groundingline to figure.
- Parameters:
no_coast (bool) – If True, only plot groundingline, not coastline, by default is False
pen (None) – GMT pen string, by default “0.6p,black”
version (str, optional) – version of groundingline to plot, by default is ‘BAS’ for north hemisphere and ‘measures-v2’ for south hemisphere
label (str, optional) – label to add to the legend, by default is None
- Return type:
- add_colorbar(hist=False, cpt_lims=None, cbar_frame=None, verbose='w', **kwargs)[source]#
Add a colorbar based on the last cmap used by PyGMT and optionally a histogram of the data values.
- Parameters:
hist (bool, optional) – choose whether to add a colorbar histogram, by default False
cpt_lims (tuple[float, float], optional) – cpt lims to use for the colorbar histogram, must match those used to create the colormap. If not supplied, will attempt to get values from kwargs grid, by default None
cbar_frame (list[str] | str, optional) – frame for the colorbar, by default None
verbose (str, optional) – verbosity level for pygmt, by default “w” for warnings
**kwargs (Any) – additional keyword arguments to pass
- Return type:
- add_faults(fault_activity=None, fault_motion=None, fault_exposure=None, pen=None, style=None, label=None)[source]#
add various types of faults from GeoMap to a map, from Cox et al.[17] and Cox et al.[18]
- Parameters:
fault_activity (str, optional) – type of fault activity, options are active or inactive, by default both
fault_motion (str, optional) – type of fault motion, options are sinistral, dextral, normal, or reverse, by default all
fault_exposure (str, optional) – type of fault exposure, options are exposed or inferred, by default both
pen (str, optional) – GMT pen string, by default “1p,magenta,-”
style (str, optional) – GMT style string, by default None
label (str, optional) – label to add to the legend, by default None
- Return type:
- add_grid(grid, cmap='viridis', shading=False, nan_transparent=True, colorbar=True, **kwargs)[source]#
Add a grid to the figure.
- Parameters:
grid (str or xarray.DataArray) – Path to the grid file or an xarray DataArray containing the grid data.
cmap (str or bool, optional) – Colormap to use for the grid, by default “viridis”. If True, last used colormap will be used.
shading (bool or str, optional) – If True, apply shading to the grid. If a string, it will be passed to pygmt.grdshade as the shading argument. By default, False (no shading).
nan_transparent (bool, optional) – If True, set NaN values to be transparent in the grid image. Default is True unless shading is False, in which case it is set to False.
colorbar (bool, optional) – If True, add a colorbar to the figure. Default is True.
**kwargs (Any) – Additional keyword arguments to pass
- Return type:
- add_gridlines(x_spacing=None, y_spacing=None, annotation_offset='20p')[source]#
add lat lon grid lines and annotations to a figure. Use kwargs x_spacing and y_spacing to customize the interval of gridlines and annotations.
- add_imagery(transparency=0)[source]#
Add satellite imagery to a figure. For southern hemisphere uses LIMA imagery, but for northern hemisphere uses MODIS imagery.
- add_inset(inset_position='jTL+jTL+o0/0', inset_width=0.25, inset_reg=None, **kwargs)[source]#
add an inset map showing the figure region relative to the Antarctic continent.
- Parameters:
inset_position (str, optional) – GMT location string for inset map, by default ‘jTL+jTL+o0/0’ (top left)
inset_width (float, optional) – Inset width as percentage of the smallest figure dimension, by default is 25% (0.25)
inset_reg (tuple[float, float, float, float], optional) – Region of Antarctica/Greenland to plot for the inset map, by default is whole area
kwargs (
Any)
- Return type:
- add_modis(version=None, transparency=0, cmap='grayC')[source]#
Add MODIS imagery to a figure.
- Parameters:
version (str | None, optional) – which version (resolution) of MODIS imagery to use, by default “750m” for southern hemisphere and “500m” for northern hemisphere.
transparency (int, optional) – transparency of the MODIS imagery, by default 0
cmap (str, optional) – colormap to use for MODIS imagery, by default “grayC”
- Return type:
- add_points(points, cmap='viridis', fill='black', style='c.2c', pen=None, label=None, colorbar=True, **kwargs)[source]#
Add points to the figure.
- Parameters:
points (pandas.DataFrame or geopandas.GeoDataFrame) – DataFrame containing point data with columns ‘x’ and ‘y’ or ‘easting’ and ‘northing’.
cmap (str or bool, optional) – Colormap to use for the points, by default “viridis”. If True, last used colormap will be used.
**kwargs (Any) – Additional keyword arguments.
fill (
str)style (
str)colorbar (
bool)
- Return type:
- add_simple_basemap(version=None, transparency=0, pen='0.2p,black', grounded_color='grey', floating_color='skyblue')[source]#
Add a simple basemap to a figure with grounded ice shown as grey and floating ice as blue.
- Parameters:
version (str | None, optional) – which version of shapefiles to use for grounding line / coastline, by default “measures-v2” for southern hemisphere and “BAS” for northern hemisphere
transparency (int, optional) – transparency of all the plotted elements, by default 0
pen (str, optional) – GMT pen string for the coastline, by default “0.2p,black”
grounded_color (str, optional) – color for the grounded ice, by default “grey”
floating_color (str, optional) – color for the floating ice, by default “skyblue”
- Return type:
- add_box(fig, box, pen='2p,black', verbose='w')[source]#
deprecated function, use class method add_box instead
Deprecated since version 1.0.7: This will be removed in 2.0.0. add_box has been replaced with a class method.
- add_coast(fig, hemisphere=None, region=None, projection=None, no_coast=False, pen=None, version=None, label=None)[source]#
deprecated function, use class method add_coast instead
Deprecated since version 1.0.7: This will be removed in 2.0.0. add_coast has been replaced with a class method.
- add_colorbar(fig, hist=False, cpt_lims=None, cbar_frame=None, verbose='w', **kwargs)[source]#
deprecated function, use class method add_colorbar instead
Deprecated since version 1.0.7: This will be removed in 2.0.0. add_colorbar has been replaced with a class method.
- add_faults(fig, region=None, projection=None, fault_activity=None, fault_motion=None, fault_exposure=None, pen=None, style=None, label=None)[source]#
deprecated function, use class method add_faults instead
Deprecated since version 1.0.7: This will be removed in 2.0.0. add_faults has been replaced with a class method.
- add_gridlines(fig, region=None, projection=None, x_spacing=None, y_spacing=None, annotation_offset='20p')[source]#
deprecated function, use class method add_gridlines instead
Deprecated since version 1.0.7: This will be removed in 2.0.0. add_gridlines has been replaced with a class method.
- add_imagery(fig, hemisphere=None, transparency=0)[source]#
deprecated function, use class method add_imagery instead
Deprecated since version 1.0.7: This will be removed in 2.0.0. add_imagery has been replaced with a class method.
- add_inset(fig, hemisphere=None, region=None, inset_position='jTL+jTL+o0/0', inset_width=0.25, inset_reg=None, **kwargs)[source]#
deprecated function, use class method add_inset instead
Deprecated since version 1.0.7: This will be removed in 2.0.0. add_inset has been replaced with a class method.
- add_modis(fig, hemisphere=None, version=None, transparency=0, cmap='grayC')[source]#
deprecated function, use class method add_modis instead
Deprecated since version 1.0.7: This will be removed in 2.0.0. add_modis has been replaced with a class method.
- add_north_arrow(fig, **kwargs)[source]#
deprecated function, use class method add_north_arrow instead
Deprecated since version 1.0.7: This will be removed in 2.0.0. add_north_arrow has been replaced with a class method.
- add_scalebar(fig, region=None, projection=None, **kwargs)[source]#
deprecated function, use class method add_scalebar instead
Deprecated since version 1.0.7: This will be removed in 2.0.0. add_scalebar has been replaced with a class method.
- add_simple_basemap(fig, hemisphere=None, version=None, transparency=0, pen='0.2p,black', grounded_color='grey', floating_color='skyblue')[source]#
deprecated function, use class method add_simple_basemap instead
Deprecated since version 1.0.7: This will be removed in 2.0.0. add_simple_basemap has been replaced with a class method.
- basemap(region=None, hemisphere=None, coast=False, north_arrow=False, scalebar=False, faults=False, simple_basemap=False, imagery_basemap=False, modis_basemap=False, title=None, inset=False, points=None, gridlines=False, origin_shift=None, fig=None, **kwargs)[source]#
Create a figure basemap in polar stereographic projection, and add a range of features such as coastline and grounding lines, inset figure location maps, background imagery, scalebars, gridlines and northarrows. Plot supplied points with either constant color or colored by a colormap. Reuse the figure instance to either plot additional features on top, or shift the plot to create subplots. There are many keyword arguments which can either be passed along to the various functions in the maps module, or specified specifically. Kwargs can be passed directly to the following functions: add_colorbar, add_north_arrow, add_scalebar, add_inset, set_cmap. Other kwargs are specified below.
- Parameters:
region (tuple[float, float, float, float] | None, optional) – region for the figure in format [xmin, xmax, ymin, ymax], by default None
hemisphere (str, optional) – set whether to plot in “north” hemisphere (EPSG:3413) or “south” hemisphere (EPSG:3031), can be set manually, or will read from the environment variable: “POLARTOOLKIT_HEMISPHERE”
coast (bool, optional) – choose whether to plot coastline and grounding line, by default False. Version of shapefiles to plots depends on hemisphere, and can be changed with kwargs coast_version, which defaults to BAS for the northern hemisphere and measures-v2 for the southern.
north_arrow (bool, optional) – choose to add a north arrow to the plot, by default is False.
scalebar (bool, optional) – choose to add a scalebar to the plot, by default is False. See add_scalebar for additional kwargs
faults (bool, optional) – choose to plot faults on the map, by default is False
simple_basemap (bool, optional) – choose to plot a simple basemap with floating ice colored blue and grounded ice colored grey, with boarders defined by simple_basemap_version.
simple_basemap_transparency (int, optional) – transparency to use for the simple basemap, by default is 0
simple_basemap_version (str, optional) – version of the simple basemap to plot, by default is None
imagery_basemap (bool, optional) – choose to add a background imagery basemap, by default is False. If true, will use LIMA for southern hemisphere and MODIS MoG for the northern hemisphere.
imagery_transparency (int, optional) – transparency to use for the imagery basemap, by default is 0
modis_basemap (bool, optional) – choose to add a MODIS background imagery basemap, by default is False.
modis_transparency (int, optional) – transparency to use for the MODIS basemap, by default is 0
modis_version (str, optional) – version of the MODIS basemap to plot, by default is None
title (str | None, optional) – title to add to the figure, by default is None
inset (bool, optional) – choose to plot inset map showing figure location, by default is False
points (pandas.DataFrame | None, optional) – points to plot on map, must contain columns ‘x’ and ‘y’ or ‘easting’ and ‘northing’.
gridlines (bool, optional) – choose to plot lat/lon grid lines, by default is False
origin_shift (str, | None, optional) – choose what to do with the plot when creating the figure. By default is ‘initialize’ which will create a new figure instance. To plot additional grids on top of the existing figure provide a figure instance to fig and set origin_shift to None. To create subplots, provide the existing figure instance to fig, and set origin_shift to ‘x’ to add the the new plot to the right of previous plot, ‘y’ to add the new plot above the previous plot, or ‘both’ to add the new plot to the right and above the old plot. By default each of this shifts will be the width/height of the figure instance, this can be changed with kwargs xshift_amount and yshift_amount, which are in multiples of figure width/height.
fig (pygmt.Figure, optional) – supply a figure instance for adding subplots or using other PyGMT plotting methods, by default None
fig_height (int or float) – height in cm for figures, by default is 15cm.
fig_width (int or float) – width in cm for figures, by default is None and is determined by fig_height and the projection.
xshift_amount (int or float) – amount to shift the origin in the x direction in multiples of current figure instance width, by default is 1.
yshift_amount (int or float) – amount to shift the origin in the y direction in multiples of current figure instance height, by default is -1.
frame (str | bool) – GMT frame string to use for the basemap, by default is “nesw+gwhite”
frame_pen (str) – GMT pen string to use for the frame, by default is “auto”
frame_font (str) – GMT font string to use for the frame, by default is “auto”
transparency (int) – transparency to use for the basemap, by default is 0
inset_position (str) – position for inset map with PyGMT syntax, by default is “jTL+jTL+o0/0”
title_font (str) – font to use for the title, by default is ‘auto’
show_region (tuple[float, float, float, float]) – show a rectangular region on the map, in the format [xmin, xmax, ymin, ymax].
region_pen (str) – GMT pen string to use for the region box, by default is None
x_spacing (float) – spacing for x gridlines in degrees, by default is None
y_spacing (float) – spacing for y gridlines in degrees, by default is None
points_style (str) – style of points to plot in GMT format, by default is ‘c.2c’.
points_fill (str) – fill color of points, either string of color name or column name to color points by, by default is ‘black’.
points_pen (str) – pen color and width of points, by default is ‘1p,black’ if constant color or None if using a cmap.
points_label (str) – label to add to legend, by default is None
points_cmap (str) – GMT color scale to use for coloring points, by default ‘viridis’. If True, will use the last used in PyGMT.
cpt_lims (str or tuple]) – limits to use for color scale max and min, by default is max and min of data.
cmap_region (str or tuple[float, float, float, float]) – region to use to define color scale limits, in format [xmin, xmax, ymin, ymax], by default is region
robust (bool) – use the 2nd and 98th percentile (or those specified with ‘robust_percentiles’) of the data to set color scale limits, by default is False.
robust_percentiles (tuple[float, float]) – percentiles to use for robust colormap limits, by default is (0.02, 0.98).
reverse_cpt (bool) – reverse the color scale, by default is False.
cbar_label (str) – label to add to colorbar.
colorbar (bool) – choose to add a colorbar for the points to the plot, by default is False.
scalebar_font_color (str) – color of the scalebar font, by default is ‘black’.
scale_font_color (str) – deprecated, use scalebar_font_color.
scalebar_length_perc (float) – percentage of the min dimension of the figure region to use for the scalebar, by default is 0.25.
scale_length_perc (float) – deprecated, use scalebar_length_perc.
scalebar_position (str) – position of the scalebar on the figure, by default is ‘n.5/.05’ which is bottom center of the plot.
scale_position (str) – deprecated, use scalebar_position.
coast_pen (str) – GMT pen string to use for the coastlines, by default is None
no_coast (bool) – choose to not plot coastlines, just grounding lines, by default is False
coast_version (str) – version of coastlines to plot, by default depends on the hemisphere
coast_label (str) – label to add to coastlines, by default is None
fault_label (str) – label to add to faults, by default is None
fault_pen (str) – GMT pen string to use for the faults, by default is None
fault_style (str) – GMT style string to use for the faults, by default is None
fault_activity (str) – column name in faults to use for activity, by default is None
fault_motion (str) – column name in faults to use for motion, by default is None
fault_exposure (str) – column name in faults to use for exposure, by default is None
- Returns:
Returns a figure object, which can be passed to the fig kwarg to add subplots or other PyGMT plotting methods.
- Return type:
Example
>>> from polartoolkit import maps, regions ... >>> fig = maps.basemap(region=regions.ross_ice_shelf) ... >>> fig.show()
- Parameters:
kwargs (
Any)
- geoviews_points(points, points_z=None, points_color='red', points_cmap='viridis', **kwargs)[source]#
Add points to a geoviews map instance. :type points:
DataFrame:param points: points to plot on the map, by default None :type points: pandas.DataFrame :type points_z:str|None:param points_z: column name to color the points by, by default None :type points_z: str | None, optional :type points_color:str:param points_color: color for the points, by default “red” :type points_color: str, optional :type points_cmap:str:param points_cmap: colormap to use to color the points based on points_z, by default “viridis” :type points_cmap: str, optional- Returns:
the instance of points
- Return type:
- Parameters:
kwargs (
Any)
- interactive_data(hemisphere=None, coast=True, grid=None, grid_cmap='inferno', points=None, points_z=None, points_color='red', points_cmap='viridis', **kwargs)[source]#
plot points or grids on an interactive map using GeoViews
- Parameters:
hemisphere (str, optional) – set whether to plot in “north” hemisphere (EPSG:3413) or “south” hemisphere (EPSG:3031)
coast (bool, optional) – choose whether to plot coastline data, by default True
grid (xarray.DataArray, optional) – display a grid on the map, by default None
grid_cmap (str, optional) – colormap to use for the grid, by default ‘inferno’
points (pandas.DataFrame, optional) – points to display on the map, must have columns ‘x’ and ‘y’, by default None
points_z (str, optional) – name of column to color points by, by default None
points_color (str, optional) – if no points_z supplied, color to use for all points, by default ‘red’
points_cmap (str, optional) – colormap to use for the points, by default ‘viridis’
- Returns:
holoview/geoviews map instance
- Return type:
Example
>>> from polartoolkit import regions, utils, maps ... >>> bedmap2_bed = fetch.bedmap2(layer='bed', region=regions.ross_ice_shelf) >>> GHF_point_data = fetch.ghf(version='burton-johnson-2020', points=True) ... >>> image = maps.interactive_data( ... hemisphere="south", ... grid = bedmap2_bed, ... points = GHF_point_data[['x','y','GHF']], ... points_z = 'GHF', ... ) >>> image
- Parameters:
kwargs (
Any)
- interactive_map(hemisphere=None, center_yx=None, zoom=None, display_xy=True, points=None, basemap_type=None, **kwargs)[source]#
Plot an interactive map with satellite imagery. Clicking gives the cursor location in a Polar Stereographic projection [x,y]. Requires ipyleaflet
- Parameters:
hemisphere (str, optional) – choose between plotting in the “north” or “south” hemispheres
center_yx (tuple, optional) – choose center coordinates in EPSG3031 [y,x], by default [0,0]
zoom (float, optional) – choose zoom level, by default None
display_xy (bool, optional) – choose if you want clicks to show the xy location, by default True
show (bool, optional) – choose whether to display the map, by default True
points (pandas.DataFrame, optional) – choose to plot points supplied as columns ‘x’, ‘y’, or ‘easting’, ‘northing’, in EPSG:3031 in a dataframe
basemap_type (str, optional) – choose what basemap to plot, options are ‘BlueMarble’, ‘Imagery’, ‘Basemap’, and “IceVelocity”, by default ‘BlueMarble’ for northern hemisphere and ‘Imagery’ for southern hemisphere.
kwargs (
Any)
- Returns:
interactive map
- Return type:
- plot_3d(grids, cmaps, exaggeration, drapegrids=None, view=(170, 30), vlims=None, region=None, hemisphere=None, shp_mask=None, polygon_mask=None, colorbar=True, cbar_perspective=True, **kwargs)[source]#
create a 3D perspective plot of a list of grids
- Parameters:
grids (list or xarray.DataArray) – xarray DataArrays to be plotted in 3D
cmaps (list or str) – list of PyGMT colormap names to use for each grid
exaggeration (list or float) – list of vertical exaggeration factors to use for each grid
view (tuple, optional) – tuple of azimuth and elevation angles for the view, by default [170, 30]
vlims (tuple, optional) – tuple of vertical limits for the plot, by default is z range of grids
region (tuple[float, float, float, float], optional) – region for the figure in format [xmin, xmax, ymin, ymax], by default None
hemisphere (str, optional) – choose between plotting in the “north” or “south” hemispheres, by default None
shp_mask (Union[str or geopandas.GeoDataFrame], optional) – shapefile or geodataframe to clip the grids with, by default None
colorbar (bool, optional) – whether to plot a colorbar, by default True
cbar_perspective (bool, optional) – whether to plot the colorbar in perspective, by default True
kwargs (
Any)
- Returns:
Returns a figure object, which can be used by other PyGMT plotting functions.
- Return type:
- plot_grd(grid, region=None, hemisphere=None, cmap='viridis', coast=False, north_arrow=False, scalebar=False, faults=False, simple_basemap=False, imagery_basemap=False, modis_basemap=False, title=None, inset=False, points=None, gridlines=False, origin_shift='initialize', fig=None, **kwargs)[source]#
Plot a grid (either a filename or a load dataarray) with PyGMT in a polar stereographic projection, and add a range of features such as coastline and grounding lines, inset figure location maps, background imagery, colorbar histogram, scalebars, gridlines and northarrows. Reuse the figure instance to either plot additional features on top, or shift the plot to create subplots. There are many keyword arguments which can either be passed along to the various functions in the maps module, or specified specifically. Kwargs can be passed directly to the following functions: add_colorbar, add_north_arrow, add_scalebar, add_inset, set_cmap. Other kwargs are specified below.
- Parameters:
grid (str or xarray.DataArray) – grid file to plot, either loaded xarray.DataArray or string of the path to a gridded data file, such as a netCDF, geotiff or zarr file.
region (tuple[float, float, float, float], optional) – region for the figure in format [xmin, xmax, ymin, ymax], by default is the extent of the input grid. If provided, the grid will be cut to this region before plotting.
hemisphere (str, optional) – set whether to plot in “north” hemisphere (EPSG:3413) or “south” hemisphere (EPSG:3031), can be set manually, or will read from the environment variable: “POLARTOOLKIT_HEMISPHERE”
cmap (str or bool, optional) – GMT color scale to use, by default ‘viridis’. If True, will use the last use cmap from PyGMT. See available options at https://docs.generic-mapping-tools.org/6.2/cookbook/cpts.html.
coast (bool, optional) – choose whether to plot coastline and grounding line, by default False. Version of shapefiles to plots depends on hemisphere, and can be changed with kwargs coast_version, which defaults to BAS for the northern hemisphere and measures-v2 for the southern.
north_arrow (bool, optional) – choose to add a north arrow to the plot, by default is False.
scalebar (bool, optional) – choose to add a scalebar to the plot, by default is False. See add_scalebar for additional kwargs
faults (bool, optional) – choose to plot faults on the map, by default is False
simple_basemap (bool, optional) – choose to plot a simple basemap with floating ice colored blue and grounded ice colored grey.
simple_basemap_transparency (int, optional) – transparency to use for the simple basemap, by default is 0
simple_basemap_version (str, optional) – version of the simple basemap to plot, by default is None
imagery_basemap (bool, optional) – choose to add a background imagery basemap, by default is False. If true, will use LIMA for southern hemisphere and MODIS MoG for the northern hemisphere.
imagery_transparency (int, optional) – transparency to use for the imagery basemap, by default is 0
modis_basemap (bool, optional) – choose to add a MODIS background imagery basemap, by default is False.
modis_transparency (int, optional) – transparency to use for the MODIS basemap, by default is 0
modis_version (str, optional) – version of the MODIS basemap to plot, by default is None
title (str | None, optional) – title to add to the figure, by default is None
inset (bool, optional) – choose to plot inset map showing figure location, by default is False
points (pandas.DataFrame | None, optional) – points to plot on map, must contain columns ‘x’ and ‘y’ or ‘easting’ and ‘northing’.
gridlines (bool, optional) – choose to plot lat/lon grid lines, by default is False
origin_shift (str, | None, optional) – choose what to do with the plot when creating the figure. By default is ‘initialize’ which will create a new figure instance. To plot additional grids on top of the existing figure provide a figure instance to fig and set origin_shift to None. To create subplots, provide the existing figure instance to fig, and set origin_shift to ‘x’ to add the the new plot to the right of previous plot, ‘y’ to add the new plot above the previous plot, or ‘both’ to add the new plot to the right and above the old plot. By default each of this shifts will be the width/height of the figure instance, this can be changed with kwargs xshift_amount and yshift_amount, which are in multiples of figure width/height.
fig (pygmt.Figure, optional) – supply a figure instance for adding subplots or using other PyGMT plotting methods, by default None
fig_height (int or float) – height in cm for figures, by default is 15cm.
fig_width (int or float) – width in cm for figures, by default is None and is determined by fig_height and the projection.
xshift_amount (int or float) – amount to shift the origin in the x direction in multiples of current figure instance width, by default is 1.
yshift_amount (int or float) – amount to shift the origin in the y direction in multiples of current figure instance height, by default is -1.
frame (str | bool) – GMT frame string to use for the basemap, by default is “nesw+gwhite”
frame_pen (str) – GMT pen string to use for the frame, by default is “auto”
frame_font (str) – GMT font string to use for the frame, by default is “auto”
transparency (int) – transparency to use for the basemap, by default is 0
modis (bool) – set to True if plotting MODIS data to use a nice colorscale.
grd2cpt (bool) – use GMT module grd2cpt to set color scale from grid values, by default is False
cpt_lims (str or tuple]) – limits to use for color scale max and min, by default is max and min of data.
cmap_region (str or tuple[float, float, float, float]) – region to use to define color scale limits, in format [xmin, xmax, ymin, ymax], by default is region
robust (bool) – use the 2nd and 98th percentile (or those specified with ‘robust_percentiles’) of the data to set color scale limits, by default is False.
robust_percentiles (tuple[float, float]) – percentiles to use for robust colormap limits, by default is (0.02, 0.98).
reverse_cpt (bool) – reverse the color scale, by default is False.
shp_mask (geopandas.GeoDataFrame | str) – shapefile to use to mask the grid before extracting limits, by default is None.
colorbar (bool) – choose to add a colorbar to the plot, by default is True.
cbar_label (str) – label to add to colorbar.
shading (str) – GMT shading string to use for the basemap, by default is None
grid_transparency (int) – transparency of the grid, by default is 0
inset_position (str) – position for inset map with PyGMT syntax, by default is “jTL+jTL+o0/0”
title_font (str) – font to use for the title, by default is ‘auto’
show_region (tuple[float, float, float, float]) – show a rectangular region on the map, in the format [xmin, xmax, ymin, ymax].
region_pen (str) – GMT pen string to use for the region box, by default is None
x_spacing (float) – spacing for x gridlines in degrees, by default is None
y_spacing (float) – spacing for y gridlines in degrees, by default is None
points_style (str) – style of points to plot in GMT format, by default is ‘c.2c’.
points_fill (str) – fill color of points, either string of color name or column name to color points by, by default is ‘black’.
points_pen (str) – pen color and width of points, by default is ‘1p,black’ if constant color or None if using a cmap.
points_label (str) – label to add to legend, by default is None
points_cmap (str) – colormap to use for points, by default is None.
scalebar_font_color (str) – color of the scalebar font, by default is ‘black’.
scale_font_color (str) – deprecated, use scalebar_font_color.
scalebar_length_perc (float) – percentage of the min dimension of the figure region to use for the scalebar, by default is 0.25.
scale_length_perc (float) – deprecated, use scalebar_length_perc.
scalebar_position (str) – position of the scalebar on the figure, by default is ‘n.5/.05’ which is bottom center of the plot.
scale_position (str) – deprecated, use scalebar_position.
coast_pen (str) – GMT pen string to use for the coastlines, by default is None
no_coast (bool) – choose to not plot coastlines, just grounding lines, by default is False
coast_version (str) – version of coastlines to plot, by default depends on the hemisphere
coast_label (str) – label to add to coastlines, by default is None
fault_label (str) – label to add to faults, by default is None
fault_pen (str) – GMT pen string to use for the faults, by default is None
fault_style (str) – GMT style string to use for the faults, by default is None
fault_activity (str) – column name in faults to use for activity, by default is None
fault_motion (str) – column name in faults to use for motion, by default is None
fault_exposure (str) – column name in faults to use for exposure, by default is None
- Returns:
Returns a figure object, which can be passed to the fig kwarg to add subplots or other PyGMT plotting methods.
- Return type:
Example
>>> from polartoolkit import maps ... >>> fig = maps.plot_grd('grid1.nc') >>> fig = maps.plot_grd( ... 'grid2.nc', ... origin_shift = 'x', ... fig = fig, ... ) ... >>> fig.show()
- Parameters:
kwargs (
Any)
- set_cmap(cmap, grid=None, points=None, modis=False, grd2cpt=False, cpt_lims=None, cmap_region=None, robust=False, robust_percentiles=(0.02, 0.98), absolute=False, reverse_cpt=False, shp_mask=None, hemisphere=None, colorbar=True, **kwargs)[source]#
Function used to set the PyGMT colormap for a figure.
- Parameters:
cmap (str | bool) – a string of either a PyGMT cpt file (.cpt), or a preset PyGMT color ramp, or alternatively a value of True will use the last used cmap.
grid (str | xarray.DataArray | None, optional) – grid used to determine colormap limits and grd2cpt colormap equalization, by default None
points (pandas.Series | numpy.ndarray | None, optional) – point values to use to determine colormap limits, by default None
modis (bool, optional) – choose appropriate cmap for plotting modis data, by default False
grd2cpt (bool, optional) – equalized the colormap to the grid data values, by default False
cpt_lims (tuple[float, float] | None, optional) – limits to set for the colormap, by default None
cmap_region (tuple[float, float, float, float] | None, optional) – extract colormap limits from a subset of the grid or points, in format [xmin, xmax, ymin, ymax], by default None
robust (bool, optional) – use the 2nd and 98th percentile of the data from the grid or points, by default False
robust_percentiles (tuple[float, float], optional) – percentiles to use for robust colormap limits, by default (0.02, 0.98)
absolute (bool, optional) – use the absolute value of the data from the grid or points, by default False
reverse_cpt (bool, optional) – change the direction of the cmap, by default False
shp_mask (geopandas.GeoDataFrame | str | None, optional) – a shapefile to mask the grid or points by before extracting limits, by default None
hemisphere (str | None, optional) – “north” or “south” hemisphere needed for using shp_mask, by default None
colorbar (bool, optional) – tell subsequent plotting functions whether to add a colorbar, by default True
kwargs (
Any)
- Returns:
a tuple with the pygmt colormap, as a string or boolean, a boolean of whether to plot the colorbar, and a tuple of 2 floats with the cpt limits.
- Return type:
- subplots(grids, hemisphere=None, region=None, dims=None, fig_title=None, fig_x_axis_title=None, fig_y_axis_title=None, fig_title_font='30p,Helvetica-Bold', subplot_labels=True, subplot_labels_loc='TL', row_titles=None, column_titles=None, **kwargs)[source]#
Plot a series of grids as individual suplots. This will automatically configure the layout to be closest to a square. Add any parameters from plot_grd() here as keyword arguments for further customization.
- Parameters:
grids (list) – list of xarray.DataArray’s to be plotted
hemisphere (str, optional) – choose between plotting in the “north” or “south” hemispheres, by default None
region (tuple[float, float, float, float], optional) – choose to subset the grids to a specified region, in format [xmin, xmax, ymin, ymax], by default None
dims (tuple, optional) – customize the subplot dimensions (# rows, # columns), by default will use utils.square_subplots() to make a square(~ish) layout.
fig_title (str, optional) – add a title to the figure, by default None
fig_x_axis_title (str, optional) – add a title to the x axis of the figure, by default None
fig_y_axis_title (str, optional) – add a title to the y axis of the figure, by default None
fig_title_font (str, optional) – font for the figure title, by default “30p,Helvetica-Bold”
subplot_labels (bool, optional) – add subplot labels (a, b, c …), by default True
subplot_labels_loc (str, optional) – location of subplot labels, by default “TL”
row_titles (list, optional) – add titles to the left of each row, by default None
column_titles (list, optional) – add titles above each column, by default None
kwargs (
Any)
- Returns:
Returns a figure object, which can be used by other PyGMT plotting functions.
- Return type:
polartoolkit.profiles module#
- create_profile(method, start=None, stop=None, num=None, shapefile=None, polyline=None, **kwargs)[source]#
Create a pandas DataFrame of points along a line with multiple methods.
- Parameters:
method (str) – Choose sampling method, either “points”, “shapefile”, or “polyline”
start (tuple[float, float], optional) – Coordinates for starting point of profile, by default None
stop (tuple[float, float], optional) – Coordinates for ending point of profile, by default None
num (int, optional) – Number of points to sample at along the line, by default is 1000
shapefile (str, optional) – shapefile file name to create points along, by default None
polyline (pandas.DataFrame, optional) – pandas dataframe with columns x and y as vertices of a polyline, by default None
kwargs (
Any)
- Returns:
Dataframe with ‘easting’, ‘northing’, and ‘dist’ columns for points along line or shapefile path.
- Return type:
- cumulative_dist(df, **kwargs)[source]#
calculate cumulative distance of points along a line.
- Parameters:
df (pandas.DataFrame) – Dataframe containing columns x, y, and rel_dist
kwargs (
Any)
- Returns:
Returns original dataframe with additional column dist
- Return type:
- default_data(region=None, hemisphere=None, verbose='q')[source]#
Fetch default gravity and magnetic datasets.
- Parameters:
- Returns:
Nested dictionary of data and attributes
- Return type:
- default_layers(version, hemisphere=None, reference=None, region=None, spacing=None, verbose='e')[source]#
Fetch default ice surface, ice base, and bed layers.
- Parameters:
version (str) – choose between ‘bedmap2’, ‘bedmap3’, and ‘bedmachine’ layers for Antarctica, and just ‘bedmachine’ Greenland
hemisphere (str, optional) – choose between plotting in the “north” or “south” hemispheres, by default None
reference (str, optional) – choose between ‘ellipsoid’, ‘eigen-6c4’ or ‘eigen-gl04c’ (only for bedmap), for an elevation reference frame, by default None
region (tuple[float], optional) – region to subset grids by, in format [xmin, xmax, ymin, ymax], by default None
spacing (float, optional) – grid spacing to resample the grids to, by default None
verbose (str, optional) – verbosity level for fetch calls, by default “e” for errors
- Returns:
Nested dictionary of earth layers and attributes
- Return type:
- draw_lines(**kwargs)[source]#
Plot an interactive map, and use the “Draw a Polyline” button to create vertices of a line. Vertices will be returned as the output of the function.
- fill_nans(df)[source]#
Fill NaN’s in sampled layer with values from above layer.
- Parameters:
df (pandas.DataFrame) – First 3 columns as they are assumed to by x, y, dist.
- Returns:
Dataframe with NaN’s of lower layers filled
- Return type:
- make_data_dict(names, grids, colors, axes=None)[source]#
Create nested dictionary of data and attributes
- Parameters:
grids (list[str or xarray.DataArray]) – files or xarray.DataArray’s
axes (list[int]) – y axes to use for each data. By default all data are on axis 0. Only 0 and 1 are used, if you supply values > 1, they will use the same axis as 1.
- Returns:
Nested dictionaries of grids and attributes
- Return type:
- plot_data(method, data_dict=None, add_map=False, fig_height=9, fig_width=14, hemisphere=None, **kwargs)[source]#
Show sampled data on a cross section, with an optional location map.
- Parameters:
method (str) – Choose sampling method, either “points”, “shapefile”, or “polyline”
data_dict (dict, optional) – nested dictionary of data to include in option graph, construct with profiles.make_data_dict, by default is gravity and magnetic anomalies.
add_map (bool) – Choose whether to add a location map, by default is False.
fig_height (float, optional) – Set the height of the figure (excluding the map) in cm, by default is 9.
fig_width (float, optional) – Set the width of the figure (excluding the map) in cm, by default is 14.
hemisphere (str, optional) – choose between plotting in the “north” or “south” hemispheres, by default None
kwargs (
Any)
- Keyword Arguments:
num (int) – Number of points to sample at along a line.
max_dist (int) – Clip all distances greater than.
min_dist (int) – Clip all distances less than.
map_background (str or xarray.DataArray) – Change the map background by passing a filename string or grid, by default is imagery.
map_cmap (str) – Change the map colorscale by passing a valid GMT cmap string, by default is ‘viridis’.
map_buffer (float) – Change map zoom as relative percentage of profile length (0-1), by default is 0.3.
data_buffer (float) – Change vertical white space within data graph (0-1), by default is 0.1.
data_legend_loc (str) – Change the legend location with a GMT position string, by default is “JBR+jBL+o0c”.
inset (bool) – choose to plot inset map showing figure location, by default is True
inset_position (str) – position for inset map with PyGMT syntax, by default is “jTL+jTL+o0/0”
save (bool) – Choose to save the image, by default is False.
path (str) – Filename for saving image, by default is None.
- Return type:
- Returns:
fig (pygmt.Figure) – a PyGMT figure object with the profile data plotted.
df_data (pandas.DataFrame) – DataFrame with sampled data along the cross-section, if data_dict is None, this will be an empty DataFrame.
- plot_profile(method, layers_dict=None, data_dict=None, add_map=False, layers_version=None, fig_height=9, fig_width=14, hemisphere=None, **kwargs)[source]#
Show sampled layers and/or data on a cross section, with an optional location map.
- Parameters:
method (str) – Choose sampling method, either “points”, “shapefile”, or “polyline”
layers_dict (dict, optional) – nested dictionary of layers to include in cross-section, construct with profiles.make_data_dict, by default is created from Bedmap2, Bedmap3, or Bedmachine data, as chosen from layers_version.
data_dict (dict, optional) – nested dictionary of data to include in option graph, construct with profiles.make_data_dict, by default is gravity and magnetic anomalies.
add_map (bool) – Choose whether to add a location map, by default is False.
layers_version (str, optional) – choose between using ‘bedmap2’, ‘bedmap3’ or ‘bedmachine’ layers, the default for Antarctica is Bedmap3 and for Greenland is BedMachine.
fig_height (float, optional) – Set the height of the figure (excluding the map) in cm, by default is 9.
fig_width (float, optional) – Set the width of the figure (excluding the map) in cm, by default is 14.
hemisphere (str, optional) – choose between plotting in the “north” or “south” hemispheres, by default None
kwargs (
Any)
- Keyword Arguments:
default_layers_spacing (float) – Spacing to use for layers grid, by default, if profile is longer than 2000 km, will use 5 km for faster plotting, or else it will default to the grids’ native resolution.
default_layers_reference (str) – Vertical reference frame to use for elevation grids, by default uses defaults from fetch functions for layers_version.
fillnans (bool) – Choose whether to fill nans in layers, defaults to True.
num (int) – Number of points to sample at along a line.
max_dist (int) – Clip all distances greater than.
min_dist (int) – Clip all distances less than.
map_background (str or xarray.DataArray) – Change the map background by passing a filename string or grid, by default is imagery.
map_cmap (str) – Change the map colorscale by passing a valid GMT cmap string, by default is ‘viridis’.
map_buffer (float) – Change map zoom as relative percentage of profile length (0-1), by default is 0.3.
layer_buffer (float) – Change vertical white space within cross-section (0-1), by default is 0.1.
data_buffer (float) – Change vertical white space within data graph (0-1), by default is 0.1.
layers_legend_loc (str) – Change the legend location with a GMT position string, by default is “JBR+jBL+o0c”.
data_legend_loc (str) – Change the legend location with a GMT position string, by default is “JBR+jBL+o0c”.
layers_legend_columns (int) – Change the number of columns in the legend, by default is 1.
inset (bool) – choose to plot inset map showing figure location, by default is True
inset_position (str) – position for inset map with PyGMT syntax, by default is “jTL+jTL+o0/0”
save (bool) – Choose to save the image, by default is False.
path (str) – Filename for saving image, by default is None.
- Return type:
- Returns:
fig (pygmt.Figure) – a PyGMT figure object with the cross-section and data plotted.
df_layers (pandas.DataFrame) – DataFrame with sampled layers along the cross-section.
df_data (pandas.DataFrame) – DataFrame with sampled data along the cross-section, if data_dict is None, this will be an empty DataFrame.
- relative_dist(df, reverse=False)[source]#
calculate distance between x,y points in a dataframe, relative to the previous row.
- Parameters:
df (pandas.DataFrame) – Dataframe containing columns x and y in meters.
reverse (bool, optional,) – choose whether to reverse the profile, by default is False
- Returns:
Returns original dataframe with additional column rel_dist
- Return type:
- sample_grids(df, grid, sampled_name, **kwargs)[source]#
Sample data at every point along a line
- Parameters:
df (pandas.DataFrame) – Dataframe containing columns ‘easting’, ‘northing’, or columns with names defined by kwarg “coord_names”.
grid (str or xarray.DataArray) – Grid to sample, either file name or xarray.DataArray
sampled_name (str,) – Name for sampled column
kwargs (
Any)
- Returns:
Dataframe with new column (sampled_name) of sample values from (grid)
- Return type:
- shorten(df, max_dist=None, min_dist=None)[source]#
Shorten a dataframe at either end based on distance column.
- Parameters:
df (pandas.DataFrame) – Dataframe to shorten and recalculate distance, must contain ‘easting’, ‘northing’, ‘dist’
max_dist (float, optional) – remove rows with dist>max_dist, by default None
min_dist (float, optional) – remove rows with dist<min_dist, by default None
- Returns:
Shortened dataframe
- Return type:
polartoolkit.regions module#
Bounding regions for commonly plotted polar regions. In stereographic projections. The format is (xmin, xmax, ymin, ymax), in meters.
- alter_region(starting_region, zoom=0, n_shift=0, w_shift=0)[source]#
Change a bounding region by shifting the box east/west or north/south, or zooming in or out.
- Parameters:
starting_region (tuple[float, float, float, float]) – Initial region in meters in format [xmin, xmax, ymin, ymax]
zoom (float, optional) – zoom in or out, in meters, by default 0
n_shift (float, optional) – shift north, or south if negative, in meters, by default 0
w_shift (float, optional) – shift west, or east if negative, in meters, by default 0
- Returns:
Returns the altered region
- Return type:
- combine_regions(region1, region2)[source]#
Get the bounding region of 2 regions.
- Parameters:
- Returns:
Bounding region of the 2 supplied regions.
- Return type:
- draw_region(**kwargs)[source]#
Plot an interactive map, and use the “Draw a Rectangle” button to draw a rectangle and get the bounding region. Vertices will be returned as the output of the function.
Example
>>> from polartoolkit import regions, utils ... >>> polygon = regions.draw_region() >>> region = utils.polygon_to_region(polygon, hemisphere="north")
- Parameters:
kwargs (
Any)
polartoolkit.utils module#
- alter_region(starting_region, **kwargs)[source]#
deprecated function, use regions.alter_region instead
Deprecated since version 0.4.0: This will be removed in 2.0.0. alter_region has been moved to the regions module, use that instead
- block_reduce(df, reduction, input_coord_names=('x', 'y'), input_data_names=None, **kwargs)[source]#
perform a block reduction of a dataframe.
- Parameters:
df (pandas.DataFrame) – data to block reduce
reduction (Callable) – function to use in reduction, e.g. np.mean
input_coord_names (tuple[str, str], optional) – strings of coordinate column names, by default (“x”, “y”) or (“easting”, “northing”)
input_data_names (Any | None, optional) – strings of data column names, by default None
kwargs (
Any)
- Returns:
a block-reduced dataframe
- Return type:
- change_reg(grid)[source]#
Use GMT grdedit to change the registration type in the metadata.
- Parameters:
grid (xarray.DataArray) – input grid to change the reg for.
- Returns:
returns a xarray.DataArray with switched reg type.
- Return type:
- dd2dms(dd)[source]#
Convert decimal degrees to minutes, seconds. Modified from https://stackoverflow.com/a/10286690/18686384
- default_hemisphere(hemisphere)[source]#
Returns the default hemisphere set in the users environment variables or raises a error.
- epsg3031_to_latlon(df, reg=False, input_coord_names=None, output_coord_names=('lon', 'lat'))[source]#
Convert coordinates from EPSG:3031 Antarctic Polar Stereographic in meters to EPSG:4326 WGS84 in decimal degrees.
- Parameters:
df (pandas.DataFrame or tuple[Any]) – input dataframe with easting and northing columns, or tuple [x,y]
reg (bool, optional) – if true, returns a GMT formatted region string, by default False
input_coord_names (tuple | None, optional) – set names for input coordinate columns, by default (“x”, “y”) or (“easting”, “northing”)
output_coord_names (tuple | None, optional) – set names for output coordinate columns, by default (“lon”, “lat”)
- Returns:
Updated dataframe with new latitude and longitude columns, numpy.ndarray in format [xmin, xmax, ymin, ymax], or tuple in format [lat, lon]
- Return type:
pandas.DataFrame or tuple[Any]
- epsg3413_to_latlon(df, reg=False, input_coord_names=None, output_coord_names=('lon', 'lat'))[source]#
Convert coordinates from EPSG:3413 North Polar Stereographic in meters to EPSG:4326 WGS84 in decimal degrees.
- Parameters:
df (pandas.DataFrame or tuple[Any]) – input dataframe with easting and northing columns, or tuple [x,y]
reg (bool, optional) – if true, returns a GMT formatted region string, by default False
input_coord_names (tuple | None, optional) – set names for input coordinate columns, by default (“x”, “y”) or (“easting”, “northing”)
output_coord_names (tuple | None, optional) – set names for output coordinate columns, by default (“lon”, “lat”)
- Returns:
Updated dataframe with new latitude and longitude columns, numpy.ndarray in format [xmin, xmax, ymin, ymax], or tuple in format [lat, lon]
- Return type:
pandas.DataFrame or tuple[Any]
- filter_grid(grid, filter_width=None, filt_type='lowpass', pad_width_factor=3, pad_mode='linear_ramp', pad_constant=None, pad_end_values=None)[source]#
Apply a spatial filter to a grid.
- Parameters:
grid (xarray.DataArray) – grid to filter the values of
filter_width (float | None, optional) – width of the filter in meters for high and low pass filtering, by default None
filt_type (str, optional) – type of filter to use from ‘lowpass’, ‘highpass’ ‘up_deriv’, ‘easting_deriv’, ‘northing_deriv’, or ‘total_gradient’ by default “lowpass”
pad_width_factor (int, optional) – factor of grid width to pad the grid by, by default 3, which equates to a pad with a width of 1/3 of the grid width.
pad_mode (str, optional) – mode of padding, can be “linear”, by default “linear_ramp”
pad_constant (float | None, optional) – constant value to use for padding, by default None
pad_end_values (float | None, optional) – value to use for end of padding if pad_mode is “linear_ramp”, by default None
- Returns:
a filtered grid
- Return type:
- get_combined_min_max(values, shapefile=None, robust=False, region=None, hemisphere=None, absolute=False, robust_percentiles=(0.02, 0.98))[source]#
Get a grids max and min values.
- Parameters:
values (tuple[xarray.DataArray | pandas.Series | numpy.ndarray]) – values to get min and max for
shapefile (Union[str or geopandas.GeoDataFrame], optional) – path or loaded shapefile to use for a mask, by default None
robust (bool, optional) – choose whether to return the 2nd and 98th percentile values, instead of the min/max
region (tuple[float, float, float, float], optional) – give a subset region to get min and max values from, in format [xmin, xmax, ymin, ymax], by default None
hemisphere (str, optional) – set whether to lat lon projection is for “north” hemisphere (EPSG:3413) or “south” hemisphere (EPSG:3031)
absolute (bool, optional) – choose whether to return the absolute min and max values, by default False
robust_percentiles (tuple[float, float], optional) – percentiles to use for robust min and max values, by default (0.02, 0.98)
- Returns:
returns the min and max values.
- Return type:
- get_fig_height()[source]#
Get the height of the current PyGMT figure instance.
- Returns:
height of the figure
- Return type:
- get_fig_width()[source]#
Get the width of the current PyGMT figure instance.
- Returns:
width of the figure
- Return type:
- get_grid_info(grid, print_info=False)[source]#
Returns information of the specified grid.
- Parameters:
grid (str or xarray.DataArray) – Input grid to get info from. Filename string or loaded grid.
print_info (bool, optional) – If true, prints out the grid info, by default False
- Returns:
(string of grid spacing, array with the region boundary, data min, data max, grid registration)
- Return type:
- get_grid_region(grid)[source]#
Returns the region of the specified grid.
- Parameters:
grid (str or xarray.DataArray) – Input grid to get region from. Filename string or loaded grid.
- Returns:
array with the region boundary in the format (xmin, xmax, ymin, ymax)
- Return type:
- get_grid_registration(grid)[source]#
Returns the registration of the specified grid.
- Parameters:
grid (str or xarray.DataArray) – Input grid to get registration from. Filename string or loaded grid.
- Returns:
“g” for gridline or “p” for pixel registration.
- Return type:
str | None
- get_grid_spacing(grid)[source]#
Returns the spacing of the specified grid.
- Parameters:
grid (str or xarray.DataArray) – Input grid to get spacing from. Filename string or loaded grid.
- Returns:
Spacing of the grid or None if it can’t be extracted.
- Return type:
float | None
- get_min_max(values, shapefile=None, robust=False, region=None, hemisphere=None, absolute=False, robust_percentiles=(0.02, 0.98))[source]#
Get a grids max and min values.
- Parameters:
values (xarray.DataArray or pandas.Series or numpy.ndarray) – values to find min or max for
shapefile (Union[str or geopandas.GeoDataFrame], optional) – path or loaded shapefile to use for a mask, by default None
robust (bool, optional) – choose whether to return the 2nd and 98th percentile values, instead of the min/max
region (tuple[float, float, float, float], optional) – give a subset region to get min and max values from, in format [xmin, xmax, ymin, ymax], by default None
hemisphere (str, optional) – set whether to lat lon projection is for “north” hemisphere (EPSG:3413) or “south” hemisphere (EPSG:3031)
absolute (bool, optional) – return the absolute min and max values, by default False
robust_percentiles (tuple[float, float], optional) – decimal percentiles to use for robust min and max, by default (0.02, 0.98)
- Returns:
returns the min and max values.
- Return type:
- gmt_str_to_list(region)[source]#
convert a tuple of floats representing the boundaries of a region into a GMT-style region string
- grd_blend(grid1, grid2)[source]#
Use GMT grdblend to blend 2 grids into 1.
- Parameters:
grid1 (xarray.DataArray) – input grid to change the reg for.
grid2 (xarray.DataArray) – input grid to change the reg for.
- Returns:
returns a blended grid.
- Return type:
- grd_compare(da1, da2, plot=True, plot_type=None, robust=False, **kwargs)[source]#
Find the difference between 2 grids and plot the results, if necessary resample and cut grids to match
- Parameters:
da1 (xarray.DataArray or str) – first grid, loaded grid of filename
da2 (xarray.DataArray or str) – second grid, loaded grid of filename
plot (bool, optional) – plot the results, by default True
plot_type (Any or None, optional) – this argument has been deprecated and will default to ‘pygmt’
robust (bool, optional) – use xarray robust color lims instead of min and max, by default is False.
kwargs (
Any)
- Keyword Arguments:
shp_mask (str) – shapefile filename to use to mask the grids for setting the color range.
robust (bool) – use xarray robust color lims instead of min and max, by default is False.
region (tuple[float, float, float, float]) – choose a specific region to compare, in format [xmin, xmax, ymin, ymax].
rmse_in_title (bool) – add the RMSE to the title, by default is True.
cpt_lims (tuple[float, float]) – set the colorbar limits for the two grids.
diff_lims (tuple[float, float]) – set the colorbar limits for the difference grid.
- Returns:
three xarray.DataArrays: (diff, resampled grid1, resampled grid2)
- Return type:
- grd_trend(da, coords=('x', 'y', 'z'), deg=1, plot=False, **kwargs)[source]#
Fit an arbitrary order trend to a grid and use it to detrend.
- Parameters:
- Returns:
returns xarray.DataArrays of the fitted surface, and the detrended grid.
- Return type:
- latlon_to_epsg3031(df, reg=False, input_coord_names=None, output_coord_names=('easting', 'northing'))[source]#
Convert coordinates from EPSG:4326 WGS84 in decimal degrees to EPSG:3031 Antarctic Polar Stereographic in meters.
- Parameters:
df (pandas.DataFrame or numpy.ndarray[Any, Any]) – input dataframe with latitude and longitude columns
reg (bool, optional) – if true, returns a GMT formatted region string, by default False
input_coord_names (tuple | None, optional) – set names for input coordinate columns, by default (“lon”, “lat”)
output_coord_names (tuple | None, optional) – set names for output coordinate columns, by default (“easting”, “northing”)
- Returns:
Updated dataframe with new easting and northing columns or numpy.ndarray in format [xmin, xmax, ymin, ymax]
- Return type:
- latlon_to_epsg3413(df, reg=False, input_coord_names=None, output_coord_names=('easting', 'northing'))[source]#
Convert coordinates from EPSG:4326 WGS84 in decimal degrees to EPSG:3413 North Polar Stereographic in meters.
- Parameters:
df (pandas.DataFrame or numpy.ndarray[Any, Any]) – input dataframe with latitude and longitude columns
reg (bool, optional) – if true, returns a GMT formatted region string, by default False
input_coord_names (tuple | None, optional) – set names for input coordinate columns, by default (“lon”, “lat”)
output_coord_names (tuple | None, optional) – set names for output coordinate columns, by default (“easting”, “northing”)
- Returns:
Updated dataframe with new easting and northing columns or numpy.ndarray in format [xmin, xmax, ymin, ymax]
- Return type:
- make_grid(region, spacing, value, name)[source]#
Create a grid with 1 variable by defining a region, spacing, name and constant value
- Parameters:
- Returns:
Returns a xarray.DataArray with 1 variable of constant value.
- Return type:
- mask_from_polygon(polygon, hemisphere=None, invert=False, drop_nans=False, grid=None, region=None, spacing=None, **kwargs)[source]#
convert the output of regions.draw_region to a mask or use it to mask a grid
- Parameters:
polygon (list) – list of polygon vertices
hemisphere (str, optional) – choose between the “north” or “south” hemispheres
invert (bool, optional) – reverse the sense of masking, by default False
drop_nans (bool, optional) – drop nans after masking, by default False
grid (Union[str, xarray.DataArray], optional) – grid to mask, by default None
region (tuple[float, float, float, float], optional) – region to create a grid if none is supplied, in format [xmin, xmax, ymin, ymax], by default None
spacing (int, optional) – spacing to create a grid if none is supplied, by default None
kwargs (
Any)
- Returns:
masked grid or mask grid with 1’s inside the mask.
- Return type:
- mask_from_shp(shapefile, hemisphere=None, invert=True, grid=None, xr_grid=None, grid_file=None, region=None, spacing=None, masked=False, pixel_register=True, input_coord_names=('easting', 'northign'))[source]#
Create a mask or a masked grid from area inside or outside of a closed shapefile.
- Parameters:
shapefile (str or geopandas.GeoDataFrame) – either path to .shp filename, must by in same directory as accompanying files : .shx, .prj, .dbf, should be a closed polygon file, or shapefile which as already been loaded into a geodataframe.
hemisphere (str, optional) – choose “north” for EPSG:3413 or “south” for EPSG:3031
invert (bool, optional) – choose whether to mask data outside the shape (False) or inside the shape (True), by default True (masks inside of shape)
grid (xarray.DataArray or str, optional) – _xarray.DataArray or path to a .nc file; to use to define region, or to mask, by default None
xr_grid (xarray.DataArray, optional) – deprecated, use grid instead, by default None
grid_file (str, optional) – deprecated, use grid instead, by default None
region (str or tuple[float, float, float, float], optional) – bounding region in format [xmin, xmax, ymin, ymax] in meters to create a dummy grid if none are supplied, by default None
spacing (str or int, optional) – grid spacing in meters to create a dummy grid if none are supplied, by default None
masked (bool, optional) – choose whether to return the masked grid (True) or the mask itself (False), by default False
pixel_register (bool, optional) – choose whether the grid is pixel registered (True) or grid registered (False), by default True
input_coord_names (tuple[str, str], optional) – set names for input coordinate columns, by default (“easting”, “northing”)
- Returns:
Returns either a masked grid, or the mask grid itself.
- Return type:
- nearest_grid_fill(grid, method='verde', crs=None)[source]#
fill missing values in a grid with the nearest value.
- Parameters:
grid (xarray.DataArray) – grid with missing values
method (str, optional) – choose method of filling, by default “verde”
crs (str | None, optional) – if method is ‘rioxarray’, provide the crs of the grid, in format ‘epsg:xxxx’, by default None
- Returns:
filled grid
- Return type:
- points_inside_region(df, region, names=('x', 'y'), reverse=False)[source]#
return a subset of a dataframe which is within a region
- Parameters:
df (pandas.DataFrame) – dataframe with coordinate columns to use for defining if within region
region (tuple[float, float, float, float]) – bounding region in format [xmin, xmax, ymin, ymax] for bounds of new subset dataframe
names (tuple[str, str], optional) – column names to use for x and y coordinates, by default (“x”, “y”) or (“easting”, “northing”)
reverse (bool, optional) – if True, will return points outside the region, by default False
- Returns:
returns a subset dataframe
- Return type:
- points_inside_shp(points, shapefile, crs=None, coord_names=None, hemisphere=None)[source]#
Add a column to a dataframe indicating whether each point is inside a shapefile.
- Parameters:
points (pandas.DataFrame | geopandas.GeoDataFrame) – dataframe with coordinate columns specified by coord_names to use for defining if within shapefile
shapefile (geopandas.GeoDataFrame) – shapefile to use for defining if point are within it or not
crs (str | None, optional) – if points is not a geodataframe, crs to use to convert into a geodataframe, by default None
coord_names (tuple[str, str] | None, optional) – names of coordinate columns, by default ‘x’ and ‘y’ or ‘easting’ and ‘northing’
hemisphere (str | None, optional) – hemisphere to use for automatically detecting crs, by default None
- Returns:
Dataframe with a new column ‘inside’ which is True if the point is inside the shapefile
- Return type:
- polygon_to_region(polygon, hemisphere=None)[source]#
convert the output of regions.draw_region to bounding region in EPSG:3031 for the south hemisphere and EPSG:3413 for the north hemisphere.
- random_color()[source]#
generate a random color in format R/G/B
- Returns:
returns a random color string, for example ‘95/226/100’
- Return type:
- region_ll_to_xy(region, hemisphere=None)[source]#
Convert region in format [lon_min, lon_max, lat_min, lat_max] to projected meters in the north or south polar stereographic projections.
- Parameters:
- Returns:
region boundaries in format [x_min, x_max, y_min, y_max]
- Return type:
- region_to_bounding_box(region)[source]#
Convert region in format [xmin, xmax, ymin, ymax] to bounding box format used for icepyx: [ lower left longitude, lower left latitude, upper right longitude, upper right latitude ] Same format as [xmin, ymin, xmax, ymax], used for bbox parameter of geopandas.read_file
- region_to_df(region, coord_names=('easting', 'northing'), reverse=False)[source]#
Convert region bounds in format [xmin, xmax, ymin, ymax] to pandas dataframe with coordinates of region corners, or reverse this if reverse is True.
- Parameters:
region (tuple[Any, Any, Any, Any] | pandas.DataFrame) – bounding region in format [xmin, xmax, ymin, ymax] or, if reverse is True, a DataFrame with coordinate columns with names set by cood_names
coord_names (tuple[str, str], optional) – names of input or output coordinate columns, by default (“easting”, “northing”)
reverse (bool, optional) – If True, convert from df to region tuple, else, convert from region tuple to df, by default False
- Returns:
Dataframe with easting and northing columns, and a row for each corner of the region, or, if reverse is True, an array in the format [xmin, xmax, ymin, ymax].
- Return type:
- region_xy_to_ll(region, hemisphere=None, dms=False)[source]#
Convert region in format [xmin, xmax, ymin, ymax] in projected meters to lat / lon
- Parameters:
- Returns:
region boundaries in format [lon_min, lon_max, lat_min, lat_max]
- Return type:
- reproject(df, input_crs, output_crs, input_coord_names=None, output_coord_names=None, reg=False)[source]#
Convert coordinates from input CRS to output CRS. Coordinates can be supplied as a dataframe with coordinate columns set by input_coord_names, or as a tuple of a list of x coordinates and a list of y coordinates.
- Parameters:
df (pandas.DataFrame or tuple[Any]) – input dataframe with easting/longitude and northing/latitude columns, or tuple [x,y]
input_crs (str) – input CRS in EPSG format, e.g. “epsg:4326”
output_crs (str) – output CRS in EPSG format, e.g. “epsg:3413”
reg (bool, optional) – if true, returns a GMT formatted region string, by default False
input_coord_names (tuple, optional) – set names for input coordinate columns, by default “x”/”y” or “easting”/”northing” if input_crs is “epsg:3413” or “epsg:3031”, or if input_crs is “epsg_4326”, “lon”/”lat”
output_coord_names (tuple, optional) – set names for output coordinate columns, by default “x”/”y” if output_crs is “epsg:3413” or “epsg:3031”, or if output_crs is “epsg_4326”, “lon”/”lat”.
- Returns:
Updated dataframe with new latitude and longitude columns, numpy.ndarray in format [xmin, xmax, ymin, ymax], or tuple in format [lat, lon]
- Return type:
pandas.DataFrame or tuple[Any]
- rmse(data, as_median=False)[source]#
function to give the root mean/median squared error (RMSE) of data
- Parameters:
data (numpy.ndarray[Any, Any]) – input data
as_median (bool, optional) – choose to give root median squared error instead, by default False
- Returns:
RMSE value
- Return type:
- set_proj(region, hemisphere=None, fig_height=None, fig_width=None)[source]#
Gives GMT format projection string from region and figure height or width. Inspired from mrsiegfried/Venturelli2020-GRL.
- Parameters:
region (tuple[float, float, float, float]) – region boundaries in format [xmin, xmax, ymin, ymax] in projected meters
hemisphere (str, optional) – set whether to lat lon projection is for “north” hemisphere (EPSG:3413) or “south” hemisphere (EPSG:3031)
fig_height (float | None) – desired figure height in cm, by default is None
fig_width (float | None) – instead of using figure height, set the projection based on figure width in cm, by default is None
- Returns:
returns a tuple of the following variables: proj, proj_latlon, fig_width, fig_height
- Return type:
- shapes_to_df(shapes, hemisphere=None)[source]#
convert the output of regions.draw_region and profiles.draw_lines to a dataframe of easting and northing points
- Parameters:
- Returns:
Dataframe with easting, northing, and shape_num.
- Return type:
- square_subplots(n)[source]#
From matplotlib/grid-strategy Calculate the number of rows and columns based on the total number of items (n) to make an arrangement as close to square as looks good.