satpy.readers.utils module

Helper functions for satpy readers.

class satpy.readers.utils.CalibrationCoefficientPicker(coefs, calib_wishlist, default='nominal', fallback=None)

Bases: object

Helper for choosing coefficients out of multiple options.

Example: Three sets of coefficients are available (nominal, meirink, gsics). A user wants to calibrate

• channel 1 with “meirink”

• channels 2/3 with “gsics”

• channel 4 with custom coefficients

• remaining channels with nominal coefficients

1. Users provide a wishlist via reader_kwargs

calib_wishlist = {
    "ch1": "meirink",
    ("ch2", "ch3"): "gsics"
    "ch4": {"mygain": 123},
}
# Also possible: Same mode for all channels via
# calib_wishlist = "gsics"

2. Readers provide a dictionary with all available coefficients

coefs = {
    "nominal": {
        "ch1": 1.0,
        "ch2": 2.0,
        "ch3": 3.0,
        "ch4": 4.0,
        "ch5": 5.0,
    },
    "meirink": {
        "ch1": 1.1,
    },
    "gsics": {
        "ch2": 2.2,
        # ch3 coefficients are missing
    }
}

3. Raders make queries to get the desired coefficients:

>>> from satpy.readers.utils import CalibrationCoefficientPicker
>>> picker = CalibrationCoefficientPicker(coefs, calib_wishlist)
>>> picker.get_coefs("ch1")
{"coefs": 1.0, "mode": "meirink"}
>>> picker.get_coefs("ch2")
{"coefs": 2.2, "mode": "gsics"}
>>> picker.get_coefs("ch3")
KeyError: 'No gsics calibration coefficients for ch3'
>>> picker.get_coefs("ch4")
{"coefs": {"mygain": 123}, "mode": "external"}
>>> picker.get_coefs("ch5")
{"coefs": 5.0, "mode": "nominal"}

4. Fallback to nominal coefficients for ch3:

>>> picker = CalibrationCoefficientPicker(coefs, calib_wishlist, fallback="nominal")
>>> picker.get_coefs("ch3")
WARNING No gsics calibration coefficients for ch3. Falling back to nominal.
{"coefs": 3.0, "mode": "nominal"}

Initialize the coefficient picker.

Parameters:

• coefs (dict) – One set of calibration coefficients for each calibration mode. The actual coefficients can be of any type (reader-specific).

• calib_wishlist (str or dict) – Desired calibration coefficients. Use a dictionary to specify channel-specific coefficients. Use a string to specify one mode for all channels.

• default (str) – Default coefficients to be used if nothing was specified in the calib_wishlist. Default: “nominal”.

• fallback (str) – Fallback coefficients if the desired coefficients are not available for some channel. By default, an exception is raised if coefficients are missing.

get_coefs(channel)

Get calibration coefficients for the given channel.

Parameters:

channel (str) – Channel name

Returns:

Calibration coefficients and mode (for transparency, in case

the picked coefficients differ from the wishlist).

Return type:

dict

class satpy.readers.utils._CalibrationCoefficientParser(coefs, default='nominal')

Bases: object

Parse user-defined calibration coefficients.

Initialize the parser.

_flatten_multi_channel_keys(calib_wishlist)

_get_coefs(mode_or_coefs, channel)

_get_coefs_by_mode(mode, channel)

_get_coefs_set(mode)

_is_mode(mode_or_coefs)

_is_multi_channel(key)

_parse_dict(calib_wishlist)

_replace_calib_mode_with_actual_coefs(calib_wishlist)

get_calib_mode(calib_wishlist, channel)

Get desired calibration mode for the given channel.

parse(calib_wishlist)

Parse user’s calibration wishlist.

satpy.readers.utils._get_geostationary_height(geos_area)

satpy.readers.utils._get_geostationary_reference_longitude(geos_area)

satpy.readers.utils._get_geostationary_semi_axes(geos_area)

satpy.readers.utils._lonlat_from_geos_angle(x, y, geos_area)

Get lons and lats from x, y in projection coordinates.

satpy.readers.utils._make_coefs(coefs, mode)

satpy.readers.utils._unzip_FSFile(filename: FSFile, prefix=None)

Open and Unzip remote FSFile ending with ‘bz2’.

Parameters:

• filename – The FSFile to unzip.

• prefix (str, optional) – If file is one of many segments of data, prefix random filename

• number. (for correct sorting. This is normally the segment)

Returns:

Temporary filename path for decompressed file or None.

satpy.readers.utils._unzip_local_file(filename: str, prefix=None)

Unzip the file ending with ‘bz2’. Initially with pbzip2 if installed or bz2.

Parameters:

• filename – The file to unzip.

• prefix (str, optional) – If file is one of many segments of data, prefix random filename

• number. (for correct sorting. This is normally the segment)

Returns:

Temporary filename path for decompressed file or None.

satpy.readers.utils._unzip_with_bz2(filename, tmpfilepath)

satpy.readers.utils._unzip_with_pbzip(filename, tmpfilepath, fdn)

satpy.readers.utils._write_uncompressed_file(content, fdn, filename, tmpfilepath)

satpy.readers.utils.apply_earthsun_distance_correction(reflectance, utc_date=None)

Correct reflectance data to account for changing Earth-Sun distance.

satpy.readers.utils.apply_rad_correction(data, slope, offset)

Apply GSICS-like correction factors to radiance data.

satpy.readers.utils.bbox(img)

Find the bounding box around nonzero elements in the given array.

Copied from https://stackoverflow.com/a/31402351/5703449 .

Returns:

rowmin, rowmax, colmin, colmax

satpy.readers.utils.fromfile(filename, dtype, count=1, offset=0)

Read the numpy array from a (remote or local) file using a buffer.

Note

This function relies on the generic_open() context manager to read a file remotely.

Parameters:

• filename – Either the name of the file to read or a satpy.readers.FSFile object.

• dtype – The data type of the numpy array

• count (Optional, default 1) – Number of items to read

• offset (Optional, default 0) – Starting point for reading the buffer from

Returns:

The content of the filename as a numpy array with the given data type.

satpy.readers.utils.generic_open(filename, *args, **kwargs)

Context manager for opening either a regular file or a bzip2 file.

Returns a file-like object.

satpy.readers.utils.get_array_date(scn_data, utc_date=None)

Get start time from a channel data array.

satpy.readers.utils.get_earth_radius(lon, lat, a, b)

Compute radius of the earth ellipsoid at the given longitude and latitude.

Parameters:

• lon – Geodetic longitude (degrees)

• lat – Geodetic latitude (degrees)

• a – Semi-major axis of the ellipsoid (meters)

• b – Semi-minor axis of the ellipsoid (meters)

Returns:

Earth Radius (meters)

satpy.readers.utils.get_geostationary_angle_extent(geos_area)

Get the max earth (vs space) viewing angles in x and y.

satpy.readers.utils.get_geostationary_bounding_box(geos_area, nb_points=50)

Get the bbox in lon/lats of the valid pixels inside geos_area.

Parameters:

• geos_area – The geostationary area to analyse.

• nb_points – Number of points on the polygon

satpy.readers.utils.get_geostationary_mask(area, chunks=None)

Compute a mask of the earth’s shape as seen by a geostationary satellite.

Parameters:

• area (pyresample.geometry.AreaDefinition) – Corresponding area definition

• chunks (int or tuple) – Chunk size for the 2D array that is generated.

Returns:

Boolean mask, True inside the earth’s shape, False outside.

satpy.readers.utils.get_sub_area(area, xslice, yslice)

Apply slices to the area_extent and size of the area.

satpy.readers.utils.get_user_calibration_factors(band_name, correction_dict)

Retrieve radiance correction factors from user-supplied dict.

satpy.readers.utils.np2str(value)

Convert an numpy.string_ to str.

Parameters:

value (ndarray) – scalar or 1-element numpy array to convert

Raises:

ValueError – if value is array larger than 1-element, or it is not of type numpy.string_ or it is not a numpy array

satpy.readers.utils.reduce_mda(mda, max_size=100)

Recursively remove arrays with more than max_size elements from the given metadata dictionary.

satpy.readers.utils.remove_earthsun_distance_correction(reflectance, utc_date=None)

Remove the sun-earth distance correction.

satpy.readers.utils.unzip_context(filename)

Context manager for decompressing a .bz2 file on the fly.

Uses unzip_file. Removes the uncompressed file on exit of the context manager.

Returns: the filename of the uncompressed file or of the original file if it was not compressed.

satpy.readers.utils.unzip_file(filename: str | FSFile, prefix=None)

Unzip the local/remote file ending with ‘bz2’.

Parameters:

• filename – The local/remote file to unzip.

• prefix (str, optional) – If file is one of many segments of data, prefix random filename

• number. (for correct sorting. This is normally the segment)

Returns:

Temporary filename path for decompressed file or None.