satpy.dataset package¶
Submodules¶
satpy.dataset.anc_vars module¶
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.
-
get_key
(match_key, num_results=1, best=True, **dfilter)[source]¶ Get multiple fully-specified keys that match the provided query.
- Parameters
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.
-
-
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.
- Parameters
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.
- Parameters
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_dict
(keyvals)[source]¶ Convert a dictionary’s values to the types defined in this object’s id_keys.
-
classmethod
from_dataarray
(array, default_keys={'name': {'required': True}, 'resolution': {'transitive': True}})[source]¶ Get the DataID using the dataarray attributes.
-
property
id_keys
¶ Get the id_keys.
-
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.
-
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.
-
sort_dataids
(dataids)[source]¶ 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:
Central wavelength is nearest to the key wavelength if specified.
Least modified dataset if modifiers is None in key. Otherwise, the modifiers are ignored.
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.
Best resolution (smallest number) if resolution is None in key. Otherwise, the resolution is ignored.
-
-
class
satpy.dataset.dataid.
ModifierTuple
(iterable=(), /)[source]¶ Bases:
tuple
A tuple holder for modifiers.
-
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)
-
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.
-
satpy.dataset.dataid.
wlklass
¶ alias of
satpy.dataset.dataid.WavelengthRange
satpy.dataset.metadata module¶
-
satpy.dataset.metadata.
average_datetimes
(datetime_list)[source]¶ Average a series of datetime objects.
Note
This function assumes all datetime objects are naive and in the same time zone (UTC).
- Parameters
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.
- Parameters
*metadata_objects – MetadataObject or dict objects to combine
average_times (bool) – Average any keys with ‘time’ in the name
- Returns
the combined metadata
- Return type
dict