satpy.dataset package


satpy.dataset.anc_vars module


Walk through datasets and their ancillary data.

Yields datasets and their parent.

satpy.dataset.anc_vars.replace_anc(dataset, parent_dataset)[source]

Replace dataset the parent_dataset’s ancillary_variables field.

satpy.dataset.data_dict module

Classes and functions related to a dictionary with DataID keys.

class satpy.dataset.data_dict.DatasetDict[source]

Bases: dict

Special dictionary object that can handle dict operations based on dataset name, wavelength, or DataID.

Note: Internal dictionary keys are DataID objects.


Check contains when we know the exact DataID.

get(key, default=None)[source]

Get value with optional default.

get_key(match_key, num_results=1, best=True, **dfilter)[source]

Get multiple fully-specified keys that match the provided query.

  • key (DataID) – DataID of query parameters to use for searching. Any parameter that is None is considered a wild card and any match is accepted. Can also be a string representing the dataset name or a number representing the dataset wavelength.

  • num_results (int) – Number of results to return. If 0 return all, if 1 return only that element, otherwise return a list of matching keys.

  • **dfilter (dict) – See get_key function for more information.


Get Node when we know the exact DataID.

keys(names=False, wavelengths=False)[source]

Give currently contained keys.

exception satpy.dataset.data_dict.TooManyResults[source]

Bases: KeyError

Special exception when one key maps to multiple items in the container.

satpy.dataset.data_dict.get_best_dataset_key(key, choices)[source]

Choose the “best” DataID from choices based on key.

To see how the keys are sorted, refer to :meth:satpy.datasets.DataQuery.sort_dataids.

This function assumes choices has already been filtered to only include datasets that match the provided key.

  • key (DataQuery) – Query parameters to sort choices by.

  • choices (iterable) – DataID objects to sort through to determine the best dataset.

Returns: List of best DataID`s from `choices. If there is more

than one element this function could not choose between the available datasets.

satpy.dataset.data_dict.get_key(key, key_container, num_results=1, best=True, query=None, **kwargs)[source]

Get the fully-specified key best matching the provided key.

Only the best match is returned if best is True (default). See get_best_dataset_key for more information on how this is determined.

query is provided as a convenience to filter by multiple parameters at once without having to filter by multiple key inputs.

  • key (DataID) – DataID of query parameters to use for searching. Any parameter that is None is considered a wild card and any match is accepted.

  • key_container (dict or set) – Container of DataID objects that uses hashing to quickly access items.

  • num_results (int) – Number of results to return. Use 0 for all matching results. If 1 then the single matching key is returned instead of a list of length 1. (default: 1)

  • best (bool) – Sort results to get “best” result first (default: True). See get_best_dataset_key for details.

  • query (DataQuery) –

    filter for the key which can contain for example: resolution (float, int, or list): Resolution of the dataset in

    dataset units (typically meters). This can also be a list of these numbers.

    calibration (str or list): Dataset calibration

    (ex.’reflectance’). This can also be a list of these strings.

    polarization (str or list): Dataset polarization

    (ex.’V’). This can also be a list of these strings.

    level (number or list): Dataset level (ex. 100). This can also be a

    list of these numbers.

    modifiers (list): Modifiers applied to the dataset. Unlike

    resolution and calibration this is the exact desired list of modifiers for one dataset, not a list of possible modifiers.

Returns (list or DataID): Matching key(s)

Raises: KeyError if no matching results or if more than one result is

found when num_results is 1.

satpy.dataset.dataid module

Dataset identifying objects.

class satpy.dataset.dataid.DataID(id_keys, **keyval_dict)[source]

Bases: dict

Identifier for all DataArray objects.

DataID is a dict that holds identifying and classifying information about a DataArray.

Init the DataID.

The id_keys dictionary has to be formed as described in satpy_internals. The other keyword arguments are values to be assigned to the keys. Note that None isn’t a valid value and will simply be ignored.

clear(*args, **kws)

Raise and error.


Convert a dictionary’s values to the types defined in this object’s id_keys.


Remove the required fields from query.


Create a query with one less modifier.

static fix_id_keys(id_keys)[source]

Flesh out enums in the id keys as gotten from a config.

classmethod from_dataarray(array, default_keys={'name': {'required': True}, 'resolution': {'transitive': True}})[source]

Get the DataID using the dataarray attributes.


Create a DataID from a dictionary.

property id_keys

Get the id_keys.


Check if this is modified.

classmethod new_id_from_dataarray(array, default_keys={'name': {'required': True}, 'resolution': {'transitive': True}})[source]

Create a new DataID from a dataarray’s attributes.

pop(*args, **kws)

Raise and error.

popitem(*args, **kws)

Raise and error.

setdefault(*args, **kws)

Raise and error.


Convert the ID to a dict.

update(*args, **kws)

Raise and error.

class satpy.dataset.dataid.DataQuery(**kwargs)[source]

Bases: object

The data query object.

A DataQuery can be used in Satpy to query for a Dataset. This way a fully qualified DataID can be found even if some of the DataID elements are unknown. In this case a * signifies something that is unknown or not applicable to the requested Dataset.

Initialize the query.


Create a query with one less modifier.


Filter DataIDs based on this query.

classmethod from_dict(the_dict)[source]

Convert a dict to an ID.

get(key, default=None)[source]

Get an item.


Check if this is modified.


Get the items of this query.


Sort the DataIDs based on this query.

Returns the sorted dataids and the list of distances.

The sorting is performed based on the types of the keys to search on (as they are defined in the DataIDs from dataids). If that type defines a distance method, then it is used to find how ‘far’ the DataID is from the current query. If the type is a number, a simple subtraction is performed. For other types, the distance is 0 if the values are identical, np.inf otherwise.

For example, with the default DataID, we use the following criteria:

  1. Central wavelength is nearest to the key wavelength if specified.

  2. Least modified dataset if modifiers is None in key. Otherwise, the modifiers are ignored.

  3. Highest calibration if calibration is None in key. Calibration priority is the order of the calibration list defined as reflectance, brightness temperature, radiance counts if not overridden in the reader configuration.

  4. Best resolution (smallest number) if resolution is None in key. Otherwise, the resolution is ignored.

sort_dataids_with_preference(all_ids, preference)[source]

Sort all_ids given a sorting preference (DataQuery or None).


Convert the ID to a dict.

class satpy.dataset.dataid.ModifierTuple(iterable=(), /)[source]

Bases: tuple

A tuple holder for modifiers.

classmethod convert(modifiers)[source]

Convert modifiers to this type if possible.

class satpy.dataset.dataid.ValueList(value)[source]

Bases: enum.IntEnum

A static value list.

classmethod convert(value)[source]

Convert value to an instance of this class.

class satpy.dataset.dataid.WavelengthRange(min, central, max, unit='µm')[source]

Bases: satpy.dataset.dataid.WavelengthRange

A named tuple for wavelength ranges.

The elements of the range are min, central and max values, and optionally a unit (defaults to µm). No clever unit conversion is done here, it’s just used for checking that two ranges are comparable.

Create new instance of WavelengthRange(min, central, max, unit)

classmethod convert(wl)[source]

Convert wl to this type if possible.


Get the distance from value.

satpy.dataset.dataid.create_filtered_query(dataset_key, filter_query)[source]

Create a DataQuery matching dataset_key and filter_query.

If a property is specified in both dataset_key and filter_query, the former has priority.

satpy.dataset.dataid.default_co_keys_config = {'name': {'required': True}, 'resolution': {'transitive': True}}

Default ID keys for coordinate DataArrays.

satpy.dataset.dataid.default_id_keys_config = {'calibration': {'enum': ['reflectance', 'brightness_temperature', 'radiance', 'counts'], 'transitive': True}, 'modifiers': {'default': (), 'type': <class 'satpy.dataset.dataid.ModifierTuple'>}, 'name': {'required': True}, 'resolution': {'transitive': False}, 'wavelength': {'type': <class 'satpy.dataset.dataid.WavelengthRange'>}}

Default ID keys DataArrays.

satpy.dataset.dataid.get_keys_from_config(common_id_keys, config)[source]

Gather keys for a new DataID from the ones available in configured dataset.

satpy.dataset.dataid.minimal_default_keys_config = {'name': {'required': True}, 'resolution': {'transitive': True}}

Minimal ID keys for DataArrays, for example composites.


alias of satpy.dataset.dataid.WavelengthRange

satpy.dataset.metadata module


Average a series of datetime objects.


This function assumes all datetime objects are naive and in the same time zone (UTC).


datetime_list (iterable) – Datetime objects to average

Returns: Average datetime as a datetime object

satpy.dataset.metadata.combine_metadata(*metadata_objects, average_times=True)[source]

Combine the metadata of two or more Datasets.

If the values corresponding to any keys are not equal or do not exist in all provided dictionaries then they are not included in the returned dictionary. By default any keys with the word ‘time’ in them and consisting of datetime objects will be averaged. This is to handle cases where data were observed at almost the same time but not exactly. In the interest of time, lazy arrays are compared by object identity rather than by their contents.

  • *metadata_objects – MetadataObject or dict objects to combine

  • average_times (bool) – Average any keys with ‘time’ in the name


the combined metadata

Return type


Module contents