NetCDF

static read_file.NetCDF(path_or_dataset, parameter=None, coords=None, crs_key=None, data_crs=None, sel=None, isel=None, set_data=None, mask_and_scale=False, fill_values='mask')

Read all relevant information necessary to add a NetCDF to the map.

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) – 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.

• 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. (“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) 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).

• set_data (None or eomaps.Maps) – Indicator if the dataset should be returned None or assigned to the provided Maps-object (e.g. by using m.set_data(…)). The default is None.

• 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)

Returns:

A dict that contains the data required for plotting.

Return type:

dict (if set_data is False) or None (if set_data is True)

Examples

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

>>> path = r"C:/folder/file.tiff"
>>> data = m.read_file.NetCDF(path)

>>> file = xar.open_dataset(path)
>>> data = m.read_file.NetCDF(file)

>>> with xar.open_dataset(path) as file:
>>>     data = m.read_file.NetCDF(file)

# to assign the data directly to the Maps-object, use set_data=<Maps object>:

>>> m.read_file.NetCDF(path, set_data=m)