NetCDF

static from_file.NetCDF(path_or_dataset, parameter=None, coords=None, data_crs_key=None, data_crs=None, sel=None, isel=None, plot_crs=None, shape=None, classify_specs=None, val_transform=None, coastline=False, mask_and_scale=False, fill_values='mask', extent=None, **kwargs)

Convenience function to initialize a new Maps-object from a NetCDF file.

If no explicit shape is provided, EOmaps will try several attempts to plot the data (fastest first).

fist, shading as a raster is used: m.set_shape.shade_raster
if it fails, shading with points is used: m.set_shape.shade_raster
if it fails, ordinary ellipse-plot is created: m.set_shape.ellipses

This function is (in principal) a shortcut for:

>>> m = Maps(crs=...)
>>> m.set_data(**m.read_file.NetCDF(...))
>>> m.set_classify_specs(...)
>>> m.plot_map(**kwargs)

Parameters:

path_or_dataset (str, pathlib.Path or xar.Dataset) –
- If str or pathlib.Path: The path to the file.
- If xar.Dataset: The xarray.Dataset instance to use
parameter (str, optional) – The name of the variable to use as parameter. If None, the first variable of the NetCDF file will be used. The default is None.
coords (tuple of str) – The names of the variables to use as x- and y- coordinates. (e.g. (‘lat’, ‘lon’)) The default is None in which case the coordinate-dimensions defined in the NetCDF will be used.
data_crs_key (str, optional) –
The attribute-name that holds the crs-information.

By default the following options are tried: - <crs_key> = “spatial_ref”, “crs”, “crs_wkt”
- crs = file.attrs.<crs_key>
data_crs (None, optional) – Optional way to specify the crs of the data explicitly. (“data_crs_key” will be ignored if “data_crs” is provided!)
sel (dict, optional) –
A dictionary of keyword-arguments passed to xarray.Dataset.sel() (see https://xarray.pydata.org/en/stable/generated/xarray.Dataset.sel.html)
```
>>> sel = dict(altitude=100, time=pd.Date)
```
The default is None.
isel (dict, optional) – A dictionary of keyword-arguments passed to xarray.Dataset.isel(). (see https://xarray.pydata.org/en/stable/generated/xarray.Dataset.isel.html) The default is {“band” : 0} (if sel is None).
plot_crs (any, optional) – The plot-crs. A crs-identifier usable with cartopy. The default is None, in which case the crs of the GeoTIFF is used if possible, else epsg=4326.
shape (str, dict or None, optional) –
- if str: The name of the shape to use, e.g. one of: [‘geod_circles’, ‘ellipses’, ‘rectangles’, ‘voronoi_diagram’, ‘delaunay_triangulation’, ‘shade_points’, ‘shade_raster’]
- if dict: a dictionary with parameters passed to the selected shape. The dict MUST contain a key “shape” that holds the name of the shape!
```
>>> dict(shape="rectangles", radius=1, radius_crs=.5)
```
classify_specs (dict, optional) – A dict of keyword-arguments passed to m.set_classify_specs(). The default is None.
val_transform (None or callable) –
A function that is used to transform the data-values. (e.g. to apply scaling etc.)
```
>>> def val_transform(a):
>>>     return a / 10
```
coastline (bool) – Indicator if a coastline should be added or not. The default is False
mask_and_scale (bool) –
Indicator if the data should be masked and scaled with respect to the file-attributes _FillValue, scale_factor and add_offset.
- If False: the data will only be scaled “on demand”, avoiding costly initialization of very large float-arrays. Masking will still be applied in case a _FillValue attribute has been found. (a masked-array is returned to avoid dtype conversions) The encoding is accessible via m.data_specs.encoding
- If True: all data will be masked and scaled after reading. For more details see xarray.open_dataset.
NOTE: using mask_and_scale=True results in a conversion of the data-values to floats!! For very large datasets this can cause a huge increase in memory-usage! EOmaps handles the scaling internally to show correct values for callbacks and colorbars, even if mask_and_scale=False!

The default is False.
fill_values (str ("mask", "keep")) –
Indicator how to treat fill-values to avoid performance issues for extremely large (integer encoded) datasets.

Only relevant for integer-encoded data if “mask_and_scale” is False and a “_FillValue” is provided in the metadata.
- If “mask”, a “numpy.masked_array” is used to incorporate fill-value masking while maintaining integer dtype. NOTE that this can lead to performance issues for very large datasets due to the increased memory usage (and reduced performance) of masked_arrays.
- If “keep”, no masking with respect to fill-values is performed and a normal “numpy.array” is returned that still contains fill_values.
  
  The fill-value is accessible via m.data_specs.encoding[“_FillValue”]
  
  To adjust the color of fill_values in the plot without explicit masking, set the “over” and “unuder” colors of the used colorbar:
  - plt.cm.viridis.with_extremes(over=… under=…)
  - cmap.set_over(…), cmap.set_under(…))
  (fill-values are excluded when evaluating data-limits)
extent (tuple or string) –
Set the extent of the map prior to plotting (can provide great speedups if only a subset of the dataset is shown!)
- If a tuple is provided, it is used to set the plot-extent before plotting via m.set_extent(extent)
  - (x0, x1, y0, y1) : provide the extent in lat/lon (epsg 4326)
  - ((x0, x1, y0, y1), crs) : provide the extent in the given crs
- If a string is provided, it is used to attempt to set the plot-extent before plotting via m.set_extent_to_location(extent)
The default is None
kwargs – Keyword-arguments passed to m.plot_map()

Returns:

m – The created Maps object.

Return type:

eomaps.Maps

Examples

# to just read the data use one of the following:

>>> from eomaps import Maps
>>> path = r"C:/folder/file.nc"
>>> m = Maps.from_file.NetCDF(path)

# to select specific datasets from the file, use sel or isel:

>>> from datetime import datetime, timedelta
>>> sel = dict(date=datetime(2021,1,1),
>>>            tolerance=timedelta(10),
>>>            method="nearest")
>>> m = Maps.from_file.NetCDF(path, sel=sel)

# you can also use already opened filehandles:

>>> file = xar.open_dataset(path)
>>> m = Maps.from_file.NetCDF(file)

>>> with xar.open_dataset(path) as file:
>>>     m = Maps.from_file.NetCDF(file)