satpy.scene module

Scene object to hold satellite data.

exception satpy.scene.DelayedGeneration[source]

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)[source]

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

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

Create an aggregated version of the Scene.

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

  • func (string) – Function to apply on each aggregation window. One of ‘mean’, ‘sum’, ‘min’, ‘max’, ‘median’, ‘argmin’, ‘argmax’, ‘prod’, ‘std’, ‘var’. ‘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()[source]

Get all IDs for configured composites.

all_composite_names()[source]

Get all names for all configured composites.

all_dataset_ids(reader_name=None, composites=False)[source]

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)[source]

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()[source]

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()[source]

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

available_composite_names()[source]

Names of all configured composites known to this Scene.

available_dataset_ids(reader_name=None, composites=False)[source]

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)[source]

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

coarsest_area(datasets=None)[source]

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.

copy(datasets=None)[source]

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)[source]

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.

finest_area(datasets=None)[source]

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(generate, unload)[source]

See what we can generate and do it.

get(key, default=None)[source]

Return value from DatasetDict with optional default.

images()[source]

Generate images for all the datasets from the scene.

iter_by_area()[source]

Generate datasets grouped by Area.

Returns

generator of (area_obj, list of dataset objects)

keys(**kwargs)[source]

Get DataID keys for the underlying data container.

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

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 (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.

  • 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)[source]

Get highest resolution area for the provided datasets. Deprecated.

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)[source]

Get lowest resolution area for the provided datasets. Deprecated.

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.

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

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)[source]

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 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 Writers for more information.

Returns

Value returned depends on compute. If compute is True then the return value is the result of computing a Delayed object or running dask.array.store(). If compute is False then the returned value is either a 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)[source]

Save all the datasets present in a scene to disk using writer.

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

  • compute (bool) – If True (default), compute all of the saves to disk. If False then the return value is either a 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 Writers 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 Delayed compute, typically this is None. If compute is False then the result is either a 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.

show(dataset_id, overlay=None)[source]

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)[source]

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 file.

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

Convert satpy Scene to geoviews.

Parameters
  • 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 – boolean, optional, default False

Returns: geoviews object

to_xarray_dataset(datasets=None)[source]

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)[source]

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()[source]

Get values for the underlying data container.

property wishlist

Return a copy of the wishlist.