Maps.read_file.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)
On this page
Show Source