Reading

Satpy supports reading and loading data from many input file formats and schemes through the concept of readers. Each reader supports a specific type of input data. The Scene object provides a simple interface around all the complexity of these various formats through its load method. The following sections describe the different way data can be loaded, requested, or added to a Scene object.

Available Readers

For readers currently available in Satpy see Reader Table. Additionally to get a list of available readers you can use the available_readers function. By default, it returns the names of available readers. To return additional reader information use available_readers(as_dict=True):

>>> from satpy import available_readers
>>> available_readers()

Reader Table

Satpy Readers

Description	Reader name	Status	fsspec support
GOES-R ABI imager Level 1b data in netcdf format	abi_l1b	Nominal	true
SCMI ABI L1B in netCDF4 format	abi_l1b_scmi	Beta	false
GOES-R ABI Level 2 products in netCDF4 format	abi_l2_nc	Beta	true
NOAA Level 2 ACSPO SST data in netCDF4 format	acspo	Nominal	false
FY-4A AGRI Level 1 HDF5 format	agri_fy4a_l1	Beta	false
FY-4B AGRI Level 1 data HDF5 format	agri_fy4b_l1	Nominal	true
Himawari (8 + 9) AHI Level 1 (HRIT)	ahi_hrit	Nominal	false
Himawari (8 + 9) AHI Level 1b (HSD)	ahi_hsd	Nominal	false
Himawari (8 + 9) AHI Level 1b (gridded)	ahi_l1b_gridded_bin	Nominal	false
Himawari-8/9 AHI Level 2 products in netCDF4 format from NOAA enterprise	ahi_l2_nc	Beta	true
GEO-KOMPSAT-2 AMI Level 1b	ami_l1b	Beta	true
GCOM-W1 AMSR2 data in HDF5 format	amsr2_l1b	Nominal	false
GCOM-W1 AMSR2 Level 2 (HDF5)	amsr2_l2	Beta	false
GCOM-W1 AMSR2 Level 2 GAASP (NetCDF4)	amsr2_l2_gaasp	Beta	false
AAPP L1C AMSU-B format	amsub_l1c_aapp	Beta	false
METOP ASCAT Level 2 SOILMOISTURE BUFR	ascat_l2_soilmoisture_bufr	Defunct	false
S-NPP and JPSS-1 ATMS L1B (NetCDF4)	atms_l1b_nc	Beta	false
S-NPP and JPSS ATMS SDR (hdf5)	atms_sdr_hdf5	Beta	false
NOAA 15 to 19, Metop A to C AVHRR data in AAPP format	avhrr_l1b_aapp	Nominal	false
Metop A to C AVHRR in native level 1 format	avhrr_l1b_eps	Nominal	false
Tiros-N, NOAA 7 to 19 AVHRR data in GAC and LAC format	avhrr_l1b_gaclac	Nominal	false
NOAA 15 to 19 AVHRR data in raw HRPT format	avhrr_l1b_hrpt	Alpha	false
EUMETCSAT GAC FDR NetCDF4	avhrr_l1c_eum_gac_fdr_nc	Defunct	false
AWS1 MWR L1B Radiance (NetCDF4)	aws1_mwr_l1b_nc	Beta	false
AWS1 MWR L1C Radiance (NetCDF4)	aws1_mwr_l1c_nc	Beta	false
Callipso Caliop Level 2 Cloud Layer data (v3) in EOS-hdf4 format	caliop_l2_cloud	Alpha	false
CAMEL emissivity level 3 data in netCDF4 format.	camel_l3_nc	Nominal	false
The Clouds from AVHRR Extended (CLAVR-x)	clavrx	Nominal	false
CMSAF CLAAS-2 data for SEVIRI-derived cloud products	cmsaf-claas2_l2_nc	Beta	false
Electro-L N2 MSU-GS data in HRIT format	electrol_hrit	Nominal	false
DSCOVR EPIC L1b hdf5	epic_l1b_h5	Beta	false
EPS-Sterna MWR L1B Radiance (NetCDF4)	eps_sterna_mwr_l1b_nc	Beta	false
MTG FCI Level-1c NetCDF	fci_l1c_nc	Beta for full-disc and RSS FDHSI, HRFI, African dissemination format, special scans, IDPF-I and IQT-I processing facilities.	true
MTGi Level 2 products in BUFR format	fci_l2_bufr	Alpha	false
MTG FCI L2 data in GRIB2 format	fci_l2_grib	Nominal	false
MTG FCI L2 data in netCDF4 format	fci_l2_nc	Alpha	false
FY-3A MERSI-1 L1B data in HDF5 format	fy3a_mersi1_l1b	Beta	false
FY-3B MERSI-1 L1B data in HDF5 format	fy3b_mersi1_l1b	Beta	false
FY-3C MERSI-1 L1B data in HDF5 format	fy3c_mersi1_l1b	Beta	false
Generic Images e.g. GeoTIFF	generic_image	Nominal	true
GEOstationary Cloud Algorithm Test-bed	geocat	Nominal	false
Meteosat Second Generation Geostationary Earth Radiation Budget L2 High-Resolution	gerb_l2_hr_h5	Beta	false
FY-4A GHI Level 1 HDF5 format	ghi_l1	Nominal	false
Sentinel-3 SLSTR SST data in netCDF4 format	ghrsst_l2	Beta	false
Vaisala GLD360 UALF2	gld360_ualf2		false
GOES-R GLM Level 2	glm_l2	Beta	false
GMS-5 VISSR Level 1b	gms5-vissr_l1b	Alpha	true
GK-2B GOCI-II Level 2 products in netCDF4 format from NOSC	goci2_l2_nc	Beta	true
GOES Imager Level 1 (HRIT)	goes-imager_hrit	Nominal	false
GOES Imager Level 1 (netCDF)	goes-imager_nc	Beta	false
GPM IMERG level 3 precipitation data in HDF5 format	gpm_imerg	Nominal	false
GRIB2 format	grib	Beta	false
Hydrology SAF products in GRIB format	hsaf_grib	Beta, only h03, h03b, h05 and h05b currently supported	false
Hydrology SAF products in HDF5 format	hsaf_h5	Beta, only h10 currently supported	false
HY-2B Scatterometer level 2b data in HDF5 format from both EUMETSAT and NSOAS	hy2_scat_l2b_h5	Beta	false
IASI Level 2 data in HDF5 format	iasi_l2	Alpha	false
IASI All Sky Temperature and Humidity Profiles - Climate Data Record Release 1.1 - Metop-A and -B	iasi_l2_cdr_nc	Alpha	True
METOP IASI Level 2 SO2 in BUFR format	iasi_l2_so2_bufr	Beta	false
IASI-NG Level-2 NetCDF Reader	iasi_ng_l2_nc	Alpha	false
EPS-SG ICI L1B Radiance (NetCDF4)	ici_l1b_nc	Beta	false
Insat 3d IMG L1B HDF5	insat3d_img_l1b_h5	Beta, navigation still off	false
MTSAT-1R JAMI Level 1 data in JMA HRIT format	jami_hrit	Beta	false
LI Level-2 NetCDF Reader	li_l2_nc	Beta	false
AAPP MAIA VIIRS and AVHRR products in HDF5 format	maia	Nominal	false
MODIS Level 3 (mcd12Q1) data in HDF-EOS format	mcd12q1	Beta	false
Sentinel 3 MERIS NetCDF format	meris_nc_sen3	Beta	false
MERSI-2 L1B data in HDF5 format	mersi2_l1b	Beta	false
MERSI-3 L1B data in HDF5 format	mersi3_l1b	Beta	false
FY-3E MERSI Low Light Level 1B	mersi_ll_l1b	Nominal	true
MERSI-RM L1B data in HDF5 format	mersi_rm_l1b	Beta	false
AAPP L1C in MHS format	mhs_l1c_aapp	Nominal	false
MIMIC Total Precipitable Water Product Reader in netCDF format	mimicTPW2_comp	Beta	false
MiRS Level 2 Precipitation and Surface Swath Product Reader in netCDF4 format	mirs	Beta	false
Terra and Aqua MODIS data in EOS-hdf4 level-1 format as produced by IMAPP and IPOPP or downloaded from LAADS	modis_l1b	Nominal	false
Terra and Aqua MODIS Level 2 (mod35) data in HDF-EOS format	modis_l2	Beta	false
MODIS Level 3 (mcd43) data in HDF-EOS format	modis_l3	Beta	false
Multispectral Imager for EarthCARE	msi_l1c_earthcare	Nominal	true
Sentinel-2 A and B MSI L1C data in SAFE format	msi_safe	Nominal	false
Sentinel-2 A and B MSI L2A data in SAFE format	msi_safe_l2a	Nominal	false
Arctica-M (N1) MSU-GS/A data in HDF5 format	msu_gsa_l1b	Beta	false
MTSAT-2 Imager Level 1 data in JMA HRIT format	mtsat2-imager_hrit	Beta	false
ISCCP NG Level 1g NetCDF4	multiple_sensors_isccpng_l1g_nc		false
MFG (Meteosat 2 to 7) MVIRI data in netCDF format (FIDUCEO FCDR)	mviri_l1b_fiduceo_nc	Beta	false
EPS-SG MWI L1B Radiance (NetCDF4)	mwi_l1b_nc	Beta	false
EPS-SG MWS L1B Radiance (NetCDF4)	mws_l1b_nc	Beta	false
NUCAPS EDR Retrieval data in NetCDF4 format	nucaps	Nominal	false
NWCSAF GEO 2016 products in netCDF4 format (limited to SEVIRI)	nwcsaf-geo	Alpha	false
NWCSAF GEO 2013 products in HDF5 format (limited to SEVIRI)	nwcsaf-msg2013-hdf5	Defunct	false
NWCSAF PPS 2014, 2018 products in netCDF4 format	nwcsaf-pps_nc	Alpha, only standard swath based ouput supported (remapped netCDF and CPP products not supported yet)	false
Ocean color CCI Level 3S data reader	oceancolorcci_l3_nc	Nominal	false
PACE OCI L2 Biogeochemical in NetCDF format	oci_l2_bgc	Beta	false
Sentinel-3 A and B OLCI Level 1B data in netCDF4 format	olci_l1b	Nominal	true
Sentinel-3 A and B OLCI Level 2 data in netCDF4 format	olci_l2	Nominal	true
Landsat-8/9 OLI/TIRS L1 data in GeoTIFF format.	oli_tirs_l1_tif	Beta	false
OMPS EDR data in HDF5 format	omps_edr	Beta	false
OSI-SAF data in netCDF4 format	osisaf_nc	Beta	true
PACE OCI Level 1B data in netCDF4 format	pace_oci_l1b_nc	Nominal	true
SAR Level 2 OCN data in SAFE format	safe_sar_l2_ocn	Defunct	false
Sentinel-1 A and B SAR-C data in SAFE format	sar-c_safe	Nominal	false
Reader for CF conform netCDF files written with Satpy	satpy_cf_nc	Nominal	false
Scatsat-1 Level 2b Wind field data in HDF5 format	scatsat1_l2b	defunct	false
SEADAS L2 Chlorphyll A product in HDF4 format	seadas_l2	Beta	false
MSG SEVIRI Level 1b (HRIT)	seviri_l1b_hrit	Nominal	true
MSG SEVIRI Level 1b in HDF format from ICARE (Lille)	seviri_l1b_icare	Defunct	false
MSG (Meteosat 8 to 11) SEVIRI data in native format	seviri_l1b_native	Nominal	true
MSG SEVIRI Level 1b NetCDF4	seviri_l1b_nc	Beta, HRV channel not supported	true
MSG (Meteosat 8 to 11) Level 2 products in BUFR format	seviri_l2_bufr	Alpha	false
MSG (Meteosat 8 to 11) SEVIRI Level 2 products in GRIB2 format	seviri_l2_grib	Nominal	false
GCOM-C SGLI Level 1B HDF5 format	sgli_l1b	Beta	false
Sentinel-3 A and B SLSTR data in netCDF4 format	slstr_l1b	Alpha	false
SMOS level 2 wind data in NetCDF4 format	smos_l2_wind	Beta	false
TROPOMI Level 2 data in NetCDF4 format	tropomi_l2	Beta	false
EPS-SG Visual Infrafred Imager (VII) Level 1B Radiance data in netCDF4 format	vii_l1b_nc	Beta	false
EPS-SG Visual Infrared Imager (VII) Level 2 data in netCDF4 format	vii_l2_nc	Beta	false
JPSS VIIRS SDR data in HDF5 Compact format	viirs_compact	Nominal	false
JPSS VIIRS EDR NetCDF format	viirs_edr	Beta	false
VIIRS EDR Active Fires data in netCDF4 & CSV .txt format	viirs_edr_active_fires	Beta	false
VIIRS EDR Flood data in HDF4 format	viirs_edr_flood	Beta	false
JPSS VIIRS Level 1b data in netCDF4 format	viirs_l1b	Nominal	false
SNPP VIIRS Level 2 data in netCDF4 format	viirs_l2	Alpha	false
JPSS VIIRS data in HDF5 SDR format	viirs_sdr	Nominal	false
VIIRS Global Area Coverage from VIIRS Reflected Solar Band and Thermal Emission Band data for both Moserate resolution and Imager resolution channels.	viirs_vgac_l1c_nc		false
VIRR data in HDF5 format	virr_l1b	Beta	false

Note

Status description:

Defunct

Most likely the reader is not functional. If it is there is a good chance of bugs and/or performance problems (e.g. not ported to dask/xarray yet). Future development is unclear. Users are encouraged to contribute (see section How to contribute and/or get help on Slack or by opening a Github issue).

Alpha

This denotes early development status. Reader is functional and implements some or all of the nominal features. There might be bugs. Exactness of results is not guaranteed. Use at your own risk.

Beta

This denotes final developement status. Reader is functional and implements all nominal features. Results should be dependable but there might be bugs. Users are actively encouraged to test and report bugs.

Nominal

This denotes a finished status. Reader is functional and most likely no new features will be introduced. It has been tested and there are no known bugs.

Documentation for specific readers

For reader-specific documentation see Specific Readers and Formats

Filter loaded files

Coming soon…

Load data

Datasets in Satpy are identified by certain pieces of metadata set during data loading. These include name, wavelength, calibration, resolution, polarization, and modifiers. Normally, once a Scene is created requesting datasets by name or wavelength is all that is needed:

>>> from satpy import Scene
>>> scn = Scene(reader="seviri_l1b_hrit", filenames=filenames)
>>> scn.load([0.6, 0.8, 10.8])
>>> scn.load(['IR_120', 'IR_134'])

However, in many cases datasets are available in multiple spatial resolutions, multiple calibrations (brightness_temperature, reflectance, radiance, etc), multiple polarizations, or have corrections or other modifiers already applied to them. By default Satpy will provide the version of the dataset with the highest resolution and the highest level of calibration (brightness temperature or reflectance over radiance). It is also possible to request one of these exact versions of a dataset by using the DataQuery class:

>>> from satpy import DataQuery
>>> my_channel_id = DataQuery(name='IR_016', calibration='radiance')
>>> scn.load([my_channel_id])
>>> print(scn['IR_016'])

Or request multiple datasets at a specific calibration, resolution, or polarization:

>>> scn.load([0.6, 0.8], resolution=1000)

Or multiple calibrations:

>>> scn.load([0.6, 10.8], calibration=['brightness_temperature', 'radiance'])

In the above case Satpy will load whatever dataset is available and matches the specified parameters. So the above load call would load the 0.6 (a visible/reflectance band) radiance data and 10.8 (an IR band) brightness temperature data.

For geostationary satellites that have the individual channel data separated to several files (segments) the missing segments are padded by default to full disk area. This is made to simplify caching of resampling look-up tables (see Resampling for more information). To disable this, the user can pass pad_data keyword argument when loading datasets:

>>> scn.load([0.6, 10.8], pad_data=False)

For geostationary products, where the imagery is stored in the files in an unconventional orientation (e.g. MSG SEVIRI L1.5 data are stored with the southwest corner in the upper right), the keyword argument upper_right_corner can be passed into the load call to automatically flip the datasets to the wished orientation. Accepted argument values are 'NE', 'NW', 'SE', 'SW', and 'native'. By default, no flipping is applied (corresponding to upper_right_corner='native') and the data are delivered in the original format. To get the data in the common upright orientation, load the datasets using e.g.:

>>> scn.load(['VIS008'], upper_right_corner='NE')

Note

If a dataset could not be loaded there is no exception raised. You must check the scn.missing_datasets property for any DataID that could not be loaded.

Available datasets

To find out what datasets are available from a reader from the files that were provided to the Scene use available_dataset_ids():

>>> scn.available_dataset_ids()

Or available_dataset_names() for just the string names of Datasets:

>>> scn.available_dataset_names()

Load remote data

Starting with Satpy version 0.25.1 with supported readers it is possible to load data from remote file systems like s3fs or fsspec. For example:

>>> from satpy import Scene
>>> from satpy.readers.core.remote import FSFile
>>> import fsspec

>>> filename = 'noaa-goes16/ABI-L1b-RadC/2019/001/17/*_G16_s20190011702186*'

>>> the_files = fsspec.open_files("simplecache::s3://" + filename, s3={'anon': True})

>>> fs_files = [FSFile(open_file) for open_file in the_files]

>>> scn = Scene(filenames=fs_files, reader='abi_l1b')
>>> scn.load(['true_color_raw'])

Check the list of Reader Table to see which reader supports remote files. For the usage of fsspec and advanced features like caching files locally see the fsspec Documentation .

Search for local/remote files

Satpy provides a utility find_files_and_readers() for searching for files in a base directory matching various search parameters. This function discovers files based on filename patterns. It returns a dictionary mapping reader name to a list of filenames supported. This dictionary can be passed directly to the Scene initialization.

>>> from satpy import find_files_and_readers, Scene
>>> from datetime import datetime
>>> my_files = find_files_and_readers(base_dir='/data/viirs_sdrs',
...                                   reader='viirs_sdr',
...                                   start_time=datetime(2017, 5, 1, 18, 1, 0),
...                                   end_time=datetime(2017, 5, 1, 18, 30, 0))
>>> scn = Scene(filenames=my_files)

See the find_files_and_readers() documentation for more information on the possible parameters as well as for searching on remote file systems.

Metadata

The datasets held by a scene also provide vital metadata such as dataset name, units, observation time etc. The following attributes are standardized across all readers:

• name, and other identifying metadata keys: See Satpy internal workings: having a look under the hood.

• start_time: Left boundary of the time interval covered by the dataset. For more information see the Time Metadata section below.

• end_time: Right boundary of the time interval covered by the dataset. For more information see the Time Metadata section below.

• area: AreaDefinition or SwathDefinition if data is geolocated. Areas are used for gridded projected data and Swaths when data must be described by individual longitude/latitude coordinates. See the Coordinates section below.

• sensor: The name of the sensor that recorded the data. For full support through Satpy this should be all lowercase. If the dataset is the result of observations from multiple sensors a set object can be used to specify more than one sensor name.

• reader: The name of the Satpy reader that produced the dataset.

• orbital_parameters: Dictionary of orbital parameters describing the satellite’s position. See the Orbital Parameters section below for more information.

• time_parameters: Dictionary of additional time parameters describing the time ranges related to the requests or schedules for when observations should happen and when they actually do. See Time Metadata below for details.

• raw_metadata: Raw, unprocessed metadata from the reader.

• rows_per_scan: Optional integer indicating how many rows of data represent a single scan of the instrument. This is primarily used by some resampling algorithms (ex. EWA) to produce better results and only makes sense for swath-based (usually polar-orbiting) instruments. For example, MODIS 1km data has 10 rows of data per scan. If an instrument does not have multiple rows per scan this should usually be set to 0 rather than 1 to indicate that the entire swath should be treated as a whole.

Note that the above attributes are not necessarily available for each dataset.

Time Metadata

In addition to the generic start_time and end_time pieces of metadata there are other time fields that may be provided if the reader supports them. These items are stored in a time_parameters sub-dictionary and they include values like:

• observation_start_time: The point in time when a sensor began recording for the current data.

• observation_end_time: Same as observation_start_time, but when data has stopped being recorded.

• nominal_start_time: The “human friendly” time describing the start of the data observation interval or repeat cycle. This time is often on a round minute (seconds=0). Along with the nominal end time, these times define the regular interval of the data collection. For example, GOES-16 ABI full disk images are collected every 10 minutes (in the common configuration) so nominal_start_time and nominal_end_time would be 10 minutes apart regardless of when the instrument recorded data inside that interval. This time may also be referred to as the repeat cycle, repeat slot, or time slot.

• nominal_end_time: Same as nominal_start_time, but the end of the interval.

In general, start_time and end_time will be set to the “nominal” time by the reader. This ensures that other Satpy components get a consistent time for calculations (ex. generation of solar zenith angles) and can be reused between bands.

See the Coordinates section below for more information on time information that may show up as a per-element/row “coordinate” on the DataArray (ex. acquisition time) instead of as metadata.

Orbital Parameters

Orbital parameters describe the position of the satellite. As such they typically come in a few “flavors” for the common types of orbits a satellite may have.

For geostationary satellites it is described using the following scalar attributes:

• satellite_actual_longitude/latitude/altitude: Current position of the satellite at the time of observation in geodetic coordinates (i.e. altitude is relative and normal to the surface of the ellipsoid). The longitude and latitude are given in degrees, the altitude in meters.

• satellite_nominal_longitude/latitude/altitude: Center of the station keeping box (a confined area in which the satellite is actively maintained in using maneuvers). Inbetween major maneuvers, when the satellite is permanently moved, the nominal position is constant. The longitude and latitude are given in degrees, the altitude in meters.

• nadir_longitude/latitude: Intersection of the instrument’s Nadir with the surface of the earth. May differ from the actual satellite position, if the instrument is pointing slightly off the axis (satellite, earth-center). If available, this should be used to compute viewing angles etc. Otherwise, use the actual satellite position. The values are given in degrees.

• projection_longitude/latitude/altitude: Projection center of the re-projected data. This should be used to compute lat/lon coordinates. Note that the projection center can differ considerably from the actual satellite position. For example MSG-1 was at times positioned at 3.4 degrees west, while the image data was re-projected to 0 degrees. The longitude and latitude are given in degrees, the altitude in meters.

  Note

  For use in pyorbital, the altitude has to be converted to kilometers, see for example pyorbital.orbital.get_observer_look().

For polar orbiting satellites the readers usually provide coordinates and viewing angles of the swath as ancillary datasets. Additional metadata related to the satellite position includes:

• tle: Two-Line Element (TLE) set used to compute the satellite’s orbit

• start_direction: The direction of satellite movement (ascending or descending) at the start of the granule.

• end_direction: The direction of satellite movement (ascending or descending) at the end of the granule.

• start_orbit: The orbit number at the start of the granule.

• end_orbit: The orbit number at the end of the granule. Typically, this is the same as start_orbit.

Coordinates

Each DataArray produced by Satpy has several Xarray coordinate variables added to them.

• x and y: Projection coordinates for gridded and projected data. By default y and x are the preferred dimensions for all 2D data, but these coordinates are only added for gridded (non-swath) data. For 1D data only the y dimension may be specified.

• crs: A CRS object defined the Coordinate Reference System for the data. Requires pyproj 2.0 or later to be installed. This is stored as a scalar array by Xarray so it must be accessed by doing crs = my_data_arr.attrs['crs'].item(). For swath data this defaults to a longlat CRS using the WGS84 datum.

• longitude: Array of longitude coordinates for swath data.

• latitude: Array of latitude coordinates for swath data.

Readers are free to define any coordinates in addition to the ones above that are automatically added. Other possible coordinates you may see:

• acq_time: Instrument data acquisition time per scan or row of data.

Adding a Reader to Satpy

This is described in the developer guide, see Adding a Custom Reader to Satpy.