satpy.scene module

Scene object to hold satellite data.

exception satpy.scene.DelayedGeneration

Bases: KeyError

Mark that a dataset can’t be generated without further modification.

class satpy.scene.Scene(filenames=None, reader=None, filter_parameters=None, reader_kwargs=None)

Bases: object

The Almighty Scene Class.

Example usage:

from satpy import Scene
from glob import glob

# create readers and open files
scn = Scene(filenames=glob('/path/to/files/*'), reader='viirs_sdr')

# load datasets from input files
scn.load(['I01', 'I02'])

# resample from satellite native geolocation to builtin 'eurol' Area
new_scn = scn.resample('eurol')

# save all resampled datasets to geotiff files in the current directory
new_scn.save_datasets()

Initialize Scene with Reader and Compositor objects.

To load data filenames and preferably reader must be specified:

scn = Scene(filenames=glob('/path/to/viirs/sdr/files/*'), reader='viirs_sdr')

If filenames is provided without reader then the available readers will be searched for a Reader that can support the provided files. This can take a considerable amount of time so it is recommended that reader always be provided. Note without filenames the Scene is created with no Readers available requiring Datasets to be added manually:

scn = Scene()
scn['my_dataset'] = Dataset(my_data_array, **my_info)

Further, notice that it is also possible to load a combination of files or sets of files each requiring their specific reader. For that filenames needs to be a dict (see parameters list below), e.g.:

scn = Scene(filenames={'nwcsaf-pps_nc': glob('/path/to/nwc/saf/pps/files/*'),
                       'modis_l1b': glob('/path/to/modis/lvl1/files/*')})

Parameters:

• filenames (iterable or dict) – A sequence of files that will be used to load data from. A dict object should map reader names to a list of filenames for that reader.

• reader (str or list) – The name of the reader to use for loading the data or a list of names.

• filter_parameters (dict) – Specify loaded file filtering parameters. Shortcut for reader_kwargs[‘filter_parameters’].

• reader_kwargs (dict) –

  Keyword arguments to pass to specific reader instances. Either a single dictionary that will be passed onto to all reader instances, or a dictionary mapping reader names to sub-dictionaries to pass different arguments to different reader instances.

  Keyword arguments for remote file access are also given in this dictionary. See documentation for usage examples.

_check_known_composites(available_only=False)

Create new dependency tree and check what composites we know about.

static _compare_area_defs(compare_func: Callable, area_defs: list[AreaDefinition]) → list[AreaDefinition]

_compare_areas(datasets=None, compare_func=<built-in function max>)

Compare areas for the provided datasets.

Parameters:

• datasets (iterable) – Datasets whose areas will be compared. Can be either xarray.DataArray objects or identifiers to get the DataArrays from the current Scene. Defaults to all datasets. This can also be a series of area objects, typically AreaDefinitions.

• compare_func (callable) – min or max or other function used to compare the dataset’s areas.

static _compare_swath_defs(compare_func: Callable, swath_defs: list[SwathDefinition]) → list[SwathDefinition]

_contained_sensor_names() → set[str]

_copy_datasets_and_wishlist(new_scn, datasets)

_create_reader_instances(filenames=None, reader=None, reader_kwargs=None)

Find readers and return their instances.

_filter_loaded_datasets_from_trunk_nodes(trunk_nodes)

_gather_all_areas(datasets)

Gather all areas from datasets.

They have to be of the same type, and at least one dataset should have an area.

_generate_composite(comp_node: CompositorNode, keepables: set)

Collect all composite prereqs and create the specified composite.

Parameters:

• comp_node – Composite Node to generate a Dataset for

• keepables – set to update if any datasets are needed when generation is continued later. This can happen if generation is delayed to incompatible areas which would require resampling first.

_generate_composites_from_loaded_datasets()

Compute all the composites contained in requirements.

_generate_composites_nodes_from_loaded_datasets(compositor_nodes)

Read (generate) composites.

_get_finalized_destination_area(destination_area, new_scn)

_get_prereq_datasets(comp_id, prereq_nodes, keepables, skip=False)

Get a composite’s prerequisites, generating them if needed.

Parameters:

• comp_id (DataID) – DataID for the composite whose prerequisites are being collected.

• prereq_nodes (sequence of Nodes) – Prerequisites to collect

• keepables (set) – set to update if any prerequisites can’t be loaded at this time (see _generate_composite).

• skip (bool) – If True, consider prerequisites as optional and only log when they are missing. If False, prerequisites are considered required and will raise an exception and log a warning if they can’t be collected. Defaults to False.

Raises:

KeyError – If required (skip=False) prerequisite can’t be collected.

static _get_writer_by_ext(extension)

Find the writer matching the extension.

Defaults to “simple_image”.

Example Mapping:

• geotiff: .tif, .tiff

• cf: .nc

• mitiff: .mitiff

• simple_image: .png, .jpeg, .jpg, …

Parameters:

extension (str) – Filename extension starting with “.” (ex. “.png”).

Returns:

The name of the writer to use for this extension.

Return type:

str

_ipython_key_completions_()

_load_datasets_by_readers(reader_datasets, **kwargs)

_prepare_resampler(source_area, destination_area, resamplers, resample_kwargs)

_read_dataset_nodes_from_storage(reader_nodes, **kwargs)

Read the given dataset nodes from storage.

_read_datasets_from_storage(**kwargs)

Load datasets from the necessary reader.

Parameters:

**kwargs – Keyword arguments to pass to the reader’s load method.

Returns:

DatasetDict of loaded datasets

_reader_times(time_prop_name)

_reduce_data(dataset, source_area, destination_area, reduce_data, reductions, resample_kwargs)

_remove_failed_datasets(keepables)

Remove the datasets that we couldn’t create.

_resampled_scene(new_scn, destination_area, reduce_data=True, **resample_kwargs)

Resample datasets to the destination area.

If data reduction is enabled, some local caching is perfomed in order to avoid recomputation of area intersections.

static _slice_area_from_bbox(src_area, dst_area, ll_bbox=None, xy_bbox=None)

Slice the provided area using the bounds provided.

_slice_data(source_area, slices, dataset)

Slice the data to reduce it.

_slice_datasets(dataset_ids, slice_key, new_area, area_only=True)

Slice scene in-place for the datasets specified.

_sort_dataset_nodes_by_reader(reader_nodes)

_update_dependency_tree(needed_datasets, query)

aggregate(dataset_ids=None, boundary='trim', side='left', func='mean', **dim_kwargs)

Create an aggregated version of the Scene.

Parameters:

• dataset_ids (iterable) – DataIDs to include in the returned Scene. Defaults to all datasets.

• func (string, callable) – Function to apply on each aggregation window. One of ‘mean’, ‘sum’, ‘min’, ‘max’, ‘median’, ‘argmin’, ‘argmax’, ‘prod’, ‘std’, ‘var’ strings or a custom function. ‘mean’ is the default.

• boundary – See xarray.DataArray.coarsen(), ‘trim’ by default.

• side – See xarray.DataArray.coarsen(), ‘left’ by default.

• dim_kwargs – the size of the windows to aggregate.

Returns:

A new aggregated scene

See also

xarray.DataArray.coarsen

Example

scn.aggregate(func=’min’, x=2, y=2) will apply the min function across a window of size 2 pixels.

all_composite_ids()

Get all IDs for configured composites.

all_composite_names()

Get all names for all configured composites.

all_dataset_ids(reader_name=None, composites=False)

Get IDs of all datasets from loaded readers or reader_name if specified.

Excludes composites unless composites=True is passed.

Parameters:

• reader_name (str, optional) – Name of reader for which to return dataset IDs. If not passed, return dataset IDs for all readers.

• composites (bool, optional) – If True, return dataset IDs including composites. If False (default), return only non-composite dataset IDs.

Returns: list of all dataset IDs

all_dataset_names(reader_name=None, composites=False)

Get all known dataset names configured for the loaded readers.

Note that some readers dynamically determine what datasets are known by reading the contents of the files they are provided. This means that the list of datasets returned by this method may change depending on what files are provided even if a product/dataset is a “standard” product for a particular reader.

Excludes composites unless composites=True is passed.

Parameters:

• reader_name (str, optional) – Name of reader for which to return dataset IDs. If not passed, return dataset names for all readers.

• composites (bool, optional) – If True, return dataset IDs including composites. If False (default), return only non-composite dataset names.

Returns: list of all dataset names

all_modifier_names()

Get names of configured modifier objects.

property all_same_area

All contained data arrays are on the same area.

property all_same_proj

All contained data array are in the same projection.

available_composite_ids()

Get IDs of composites that can be generated from the available datasets.

available_composite_names()

Names of all configured composites known to this Scene.

available_dataset_ids(reader_name=None, composites=False)

Get DataIDs of loadable datasets.

This can be for all readers loaded by this Scene or just for reader_name if specified.

Available dataset names are determined by what each individual reader can load. This is normally determined by what files are needed to load a dataset and what files have been provided to the scene/reader. Some readers dynamically determine what is available based on the contents of the files provided.

By default, only returns non-composite dataset IDs. To include composite dataset IDs, pass composites=True.

Parameters:

• reader_name (str, optional) – Name of reader for which to return dataset IDs. If not passed, return dataset IDs for all readers.

• composites (bool, optional) – If True, return dataset IDs including composites. If False (default), return only non-composite dataset IDs.

Returns: list of available dataset IDs

available_dataset_names(reader_name=None, composites=False)

Get the list of the names of the available datasets.

By default, this only shows names of datasets directly defined in (one of the) readers. Names of composites are not returned unless the argument composites=True is passed.

Parameters:

• reader_name (str, optional) – Name of reader for which to return dataset IDs. If not passed, return dataset names for all readers.

• composites (bool, optional) – If True, return dataset IDs including composites. If False (default), return only non-composite dataset names.

Returns: list of available dataset names

chunk(**kwargs)

Call chunk on all Scene data arrays.

See xarray.DataArray.chunk() for more details.

coarsest_area(datasets=None)

Get lowest resolution area for the provided datasets.

Parameters:

datasets (iterable) – Datasets whose areas will be compared. Can be either xarray.DataArray objects or identifiers to get the DataArrays from the current Scene. Defaults to all datasets.

compute(**kwargs)

Call compute on all Scene data arrays.

See xarray.DataArray.compute() for more details. Note that this will convert the contents of the DataArray to numpy arrays which may not work with all parts of Satpy which may expect dask arrays.

copy(datasets=None)

Create a copy of the Scene including dependency information.

Parameters:

datasets (list, tuple) – DataID objects for the datasets to include in the new Scene object.

crop(area=None, ll_bbox=None, xy_bbox=None, dataset_ids=None)

Crop Scene to a specific Area boundary or bounding box.

Parameters:

• area (AreaDefinition) – Area to crop the current Scene to

• ll_bbox (tuple, list) – 4-element tuple where values are in lon/lat degrees. Elements are (xmin, ymin, xmax, ymax) where X is longitude and Y is latitude.

• xy_bbox (tuple, list) – Same as ll_bbox but elements are in projection units.

• dataset_ids (iterable) – DataIDs to include in the returned Scene. Defaults to all datasets.

This method will attempt to intelligently slice the data to preserve relationships between datasets. For example, if we are cropping two DataArrays of 500m and 1000m pixel resolution then this method will assume that exactly 4 pixels of the 500m array cover the same geographic area as a single 1000m pixel. It handles these cases based on the shapes of the input arrays and adjusting slicing indexes accordingly. This method will have trouble handling cases where data arrays seem related but don’t cover the same geographic area or if the coarsest resolution data is not related to the other arrays which are related.

It can be useful to follow cropping with a call to the native resampler to resolve all datasets to the same resolution and compute any composites that could not be generated previously:

>>> cropped_scn = scn.crop(ll_bbox=(-105., 40., -95., 50.))
>>> remapped_scn = cropped_scn.resample(resampler='native')

Note

The resample method automatically crops input data before resampling to save time/memory.

property end_time

Return the end time of the file.

If no data is currently contained in the Scene then loaded readers will be consulted. If no readers are loaded then the Scene.start_time is returned.

finest_area(datasets=None)

Get highest resolution area for the provided datasets.

Parameters:

datasets (iterable) – Datasets whose areas will be compared. Can be either xarray.DataArray objects or identifiers to get the DataArrays from the current Scene. Defaults to all datasets.

generate_possible_composites(unload)

See which composites can be generated and generate them.

Parameters:

unload (bool) – if the dependencies of the composites should be unloaded after successful generation.

get(key, default=None)

Return value from DatasetDict with optional default.

images()

Generate images for all the datasets from the scene.

iter_by_area()

Generate datasets grouped by Area.

Returns:

generator of (area_obj, list of dataset objects)

keys(**kwargs)

Get DataID keys for the underlying data container.

load(wishlist, calibration='*', resolution='*', polarization='*', level='*', modifiers='*', generate=True, unload=True, **kwargs)

Read and generate requested datasets.

When the wishlist contains DataQuery objects they can either be fully-specified DataQuery objects with every parameter specified or they can not provide certain parameters and the “best” parameter will be chosen. For example, if a dataset is available in multiple resolutions and no resolution is specified in the wishlist’s DataQuery then the highest (the smallest number) resolution will be chosen.

Loaded DataArray objects are created and stored in the Scene object.

Parameters:

• wishlist (iterable) – List of names (str), wavelengths (float), DataQuery objects or DataID of the requested datasets to load. See available_dataset_ids() for what datasets are available.

• calibration (list | str) – Calibration levels to limit available datasets. This is a shortcut to having to list each DataQuery/DataID in wishlist.

• resolution (list | float) – Resolution to limit available datasets. This is a shortcut similar to calibration.

• polarization (list | str) – Polarization (‘V’, ‘H’) to limit available datasets. This is a shortcut similar to calibration.

• modifiers (tuple | str) – Modifiers that should be applied to the loaded datasets. This is a shortcut similar to calibration, but only represents a single set of modifiers as a tuple. For example, specifying modifiers=('sunz_corrected', 'rayleigh_corrected') will attempt to apply both of these modifiers to all loaded datasets in the specified order (‘sunz_corrected’ first).

• level (list | str) – Pressure level to limit available datasets. Pressure should be in hPa or mb. If an altitude is used it should be specified in inverse meters (1/m). The units of this parameter ultimately depend on the reader.

• generate (bool) – Generate composites from the loaded datasets (default: True)

• unload (bool) – Unload datasets that were required to generate the requested datasets (composite dependencies) but are no longer needed.

max_area(datasets=None)

Get highest resolution area for the provided datasets. Deprecated.

Deprecated. Use finest_area() instead.

Parameters:

datasets (iterable) – Datasets whose areas will be compared. Can be either xarray.DataArray objects or identifiers to get the DataArrays from the current Scene. Defaults to all datasets.

min_area(datasets=None)

Get lowest resolution area for the provided datasets. Deprecated.

Deprecated. Use coarsest_area() instead.

Parameters:

datasets (iterable) – Datasets whose areas will be compared. Can be either xarray.DataArray objects or identifiers to get the DataArrays from the current Scene. Defaults to all datasets.

property missing_datasets

Set of DataIDs that have not been successfully loaded.

persist(**kwargs)

Call persist on all Scene data arrays.

See xarray.DataArray.persist() for more details.

resample(destination=None, datasets=None, generate=True, unload=True, resampler=None, reduce_data=True, **resample_kwargs)

Resample datasets and return a new scene.

Parameters:

• destination (AreaDefinition, GridDefinition) – area definition to resample to. If not specified then the area returned by Scene.finest_area() will be used.

• datasets (list) – Limit datasets to resample to these specified data arrays. By default all currently loaded datasets are resampled.

• generate (bool) – Generate any requested composites that could not be previously due to incompatible areas (default: True).

• unload (bool) – Remove any datasets no longer needed after requested composites have been generated (default: True).

• resampler (str) – Name of resampling method to use. By default, this is a nearest neighbor KDTree-based resampling (‘nearest’). Other possible values include ‘native’, ‘ewa’, etc. See the resample documentation for more information.

• reduce_data (bool) – Reduce data by matching the input and output areas and slicing the data arrays (default: True)

• resample_kwargs – Remaining keyword arguments to pass to individual resampler classes. See the individual resampler class documentation here for available arguments.

save_dataset(dataset_id, filename=None, writer=None, overlay=None, decorate=None, compute=True, **kwargs)

Save the dataset_id to file using writer.

Parameters:

• dataset_id (str or Number or DataID or DataQuery) – Identifier for the dataset to save to disk.

• filename (str) – Optionally specify the filename to save this dataset to. It may include string formatting patterns that will be filled in by dataset attributes.

• writer (str) – Name of writer to use when writing data to disk. Default to "geotiff". If not provided, but filename is provided then the filename’s extension is used to determine the best writer to use.

• overlay (dict) – See satpy.writers.add_overlay(). Only valid for “image” writers like geotiff or simple_image.

• decorate (dict) – See satpy.writers.add_decorate(). Only valid for “image” writers like geotiff or simple_image.

• compute (bool) – If True (default), compute all of the saves to disk. If False then the return value is either a Dask Delayed object or two lists to be passed to a dask.array.store call. See return values below for more details.

• kwargs – Additional writer arguments. See Writing for more information.

Returns:

Value returned depends on compute. If compute is True then the return value is the result of computing a Dask Delayed object or running dask.array.store(). If compute is False then the returned value is either a Dask Delayed object that can be computed using delayed.compute() or a tuple of (source, target) that should be passed to dask.array.store(). If target is provided the the caller is responsible for calling target.close() if the target has this method.

save_datasets(writer=None, filename=None, datasets=None, compute=True, **kwargs)

Save requested datasets present in a scene to disk using writer.

Note that dependency datasets (those loaded solely to create another and not requested explicitly) that may be contained in this Scene will not be saved by default. The default datasets are those explicitly requested through .load and exist in the Scene currently. Specify dependency datasets using the datasets keyword argument.

Parameters:

• writer (str) – Name of writer to use when writing data to disk. Default to "geotiff". If not provided, but filename is provided then the filename’s extension is used to determine the best writer to use.

• filename (str) – Optionally specify the filename to save this dataset to. It may include string formatting patterns that will be filled in by dataset attributes.

• datasets (iterable) – Limit written products to these datasets. Elements can be string name, a wavelength as a number, a DataID, or DataQuery object.

• compute (bool) – If True (default), compute all of the saves to disk. If False then the return value is either a Dask Delayed object or two lists to be passed to a dask.array.store call. See return values below for more details.

• kwargs – Additional writer arguments. See Writing for more information.

Returns:

Value returned depends on compute keyword argument. If compute is True the value is the result of a either a dask.array.store operation or a Dask Delayed compute, typically this is None. If compute is False then the result is either a Dask Delayed object that can be computed with delayed.compute() or a two element tuple of sources and targets to be passed to dask.array.store(). If targets is provided then it is the caller’s responsibility to close any objects that have a “close” method.

property sensor_names: set[str]

Return sensor names for the data currently contained in this Scene.

Sensor information is collected from data contained in the Scene whether loaded from a reader or generated as a composite with load() or added manually using scn["name"] = data_arr). Sensor information is also collected from any loaded readers. In some rare cases this may mean that the reader includes sensor information for data that isn’t actually loaded or even available.

show(dataset_id, overlay=None)

Show the dataset on screen as an image.

Show dataset on screen as an image, possibly with an overlay.

Parameters:

• dataset_id (DataID, DataQuery or str) – Either a DataID, a DataQuery or a string, that refers to a data array that has been previously loaded using Scene.load.

• overlay (dict, optional) – Add an overlay before showing the image. The keys/values for this dictionary are as the arguments for add_overlay(). The dictionary should contain at least the key "coast_dir", which should refer to a top-level directory containing shapefiles. See the pycoast package documentation for coastline shapefile installation instructions.

slice(key)

Slice Scene by dataset index.

Note

DataArrays that do not have an area attribute will not be sliced.

property start_time

Return the start time of the contained data.

If no data is currently contained in the Scene then loaded readers will be consulted.

to_geoviews(gvtype=None, datasets=None, kdims=None, vdims=None, dynamic=False)

Convert satpy Scene to geoviews.

Parameters:

• scn (satpy.Scene) – Satpy Scene.

• gvtype (gv plot type) – One of gv.Image, gv.LineContours, gv.FilledContours, gv.Points Default to geoviews.Image. See Geoviews documentation for details.

• datasets (list) – Limit included products to these datasets

• kdims (list of str) – Key dimensions. See geoviews documentation for more information.

• vdims (list of str, optional) – Value dimensions. See geoviews documentation for more information. If not given defaults to first data variable

• dynamic (bool, optional) – Load and compute data on-the-fly during visualization. Default is False. See https://holoviews.org/user_guide/Gridded_Datasets.html#working-with-xarray-data-types for more information. Has no effect when data to be visualized only has 2 dimensions (y/x or longitude/latitude) and doesn’t require grouping via the Holoviews groupby function.

Returns: geoviews object

to_hvplot(datasets=None, *args, **kwargs)

Convert satpy Scene to Hvplot. The method could not be used with composites of swath data.

Parameters:

• scn (satpy.Scene) – Satpy Scene.

• datasets (list) – Limit included products to these datasets.

• args – Arguments coming from hvplot

• kwargs – hvplot options dictionary.

Returns:

hvplot object that contains within it the plots of datasets list. As default it contains all Scene datasets plots and a plot title is shown.

Example usage:

scene_list = ['ash','IR_108']
scn = Scene()
scn.load(scene_list)
scn = scn.resample('eurol')
plot = scn.to_hvplot(datasets=scene_list)
plot.ash+plot.IR_108

to_xarray(datasets=None, header_attrs=None, exclude_attrs=None, flatten_attrs=False, pretty=True, include_lonlats=True, epoch=None, include_orig_name=True, numeric_name_prefix='CHANNEL_')

Merge all xr.DataArray(s) of a satpy.Scene to a CF-compliant xarray object.

If all Scene DataArrays are on the same area, it returns an xr.Dataset. If Scene DataArrays are on different areas, currently it fails, although in future we might return a DataTree object, grouped by area.

Parameters:

• (iterable) (datasets) – List of Satpy Scene datasets to include in the output xr.Dataset. Elements can be string name, a wavelength as a number, a DataID, or DataQuery object. If None (the default), it include all loaded Scene datasets.

• header_attrs – Global attributes of the output xr.Dataset.

• (str) (numeric_name_prefix) – Reference time for encoding the time coordinates (if available). Example format: “seconds since 1970-01-01 00:00:00”. If None, the default reference time is defined using “from satpy.cf.coords import EPOCH”

• (bool) (pretty) – If True, flatten dict-type attributes.

• (list) (exclude_attrs) – List of xr.DataArray attribute names to be excluded.

• (bool) – If True, it includes ‘latitude’ and ‘longitude’ coordinates. If the ‘area’ attribute is a SwathDefinition, it always includes latitude and longitude coordinates.

• (bool) – Don’t modify coordinate names, if possible. Makes the file prettier, but possibly less consistent.

• (bool). (include_orig_name) – Include the original dataset name as a variable attribute in the xr.Dataset.

• (str) – Prefix to add the each variable with name starting with a digit. Use ‘’ or None to leave this out.

• Returns

• -------

• ds – A CF-compliant xr.Dataset

• xr.Dataset – A CF-compliant xr.Dataset

to_xarray_dataset(datasets=None)

Merge all xr.DataArrays of a scene to a xr.DataSet.

Parameters:

datasets (list) – List of products to include in the xarray.Dataset

Returns: xarray.Dataset

unload(keepables=None)

Unload all unneeded datasets.

Datasets are considered unneeded if they weren’t directly requested or added to the Scene by the user or they are no longer needed to generate composites that have yet to be generated.

Parameters:

keepables (iterable) – DataIDs to keep whether they are needed or not.

values()

Get values for the underlying data container.

property wishlist

Return a copy of the wishlist.

satpy.scene._aggregate_data_array(data_array, func, **coarsen_kwargs)

Aggregate xr.DataArray.

satpy.scene._get_area_resolution(area)

Attempt to retrieve resolution from AreaDefinition.