SynSatiPy package

synsatipy Classes

class synsatipy.synsat.SynSat(*args, **kwargs)

Bases: SynSatBase

SynSat class for calculating MSG Synsats.

The is a child class of SynSatBase.

Notes

This class is the main class for calculating MSG Synsats.

Parameters:

• *args (list) – List of arguments passed to the parent class.

• **kwargs (dict) – Additional keyword arguments passed to the parent class.

chunked_run(**kwargs)

Runs a small chunk of the RTTOV workflow.

Parameters:

**kwargs (dict) – Additional keyword arguments.

Return type:

None

extract_output()

Extracts the output data from the RTTOV variables and prepares it for saving.

load(inputfile_or_data, **kwargs)

Load data from file or dataset.

Parameters:

• inputfile_or_data (str or xr.Dataset) – The input file or dataset.

• **kwargs (dict) – Additional keyword arguments.

Return type:

None

run(**kwargs)

Run the complete RTTOV workflow. This is a wrapper for the chunked_run method.

Parameters:

• efficiency_factor (int, optional) – Multiplicative factor for the number of profiles processed per call when chunked processing is enabled (i.e., when ‘chunked’ is in kwargs). The actual number of profiles per chunk is calculated as efficiency_factor * NprofsPerCall. Default is 4.

• **kwargs (dict) – Additional keyword arguments. If ‘chunked’ is included in kwargs, the workflow will process data in chunks using the efficiency_factor parameter.

Return type:

None

save(output_filename)

Save the output data to a netcdf file.

Parameters:

output_filename (str) – The output filename.

Return type:

None

class synsatipy.synsat.SynSatBase(*args, **kwargs)

Bases: ABC, synsat_attributes

Class for calculating MSG Synsats.

The is a child class of pyrttov.Rttov.

Notes

General Notes on the Workflow: 1. Options need to be provided 2. Instrument (MSG-SEVIRI) is loaded 3. Data needs to be read 4. Atlasses are loaded (depend on time coordinate in data) 5. RTTOV is called

load_atlasses(synsat_default_month=8, **kwargs)

Load the emissivity and BRDF atlases.

Parameters:

• synsat_default_month (int) – Month to use for the emissivity and BRDF atlases. (Default value = 8)

• **kwargs (dict) – Additional keyword arguments.

Return type:

None

load_goes_abi(synsat_goes_number=16, **synsat_kwargs)

Loads configuration specific for the GOES-ABI instrument.

Parameters:

• synsat_goes_number (int) – GOES satellite number. (Default value = 16)

• **synsat_kwargs (dict) – Additional keyword arguments.

Return type:

None

load_instrument(**synsat_kwargs)

Loads the specified instrument configuration.

Parameters:

**synsat_kwargs (dict) – Additional keyword arguments including synsat_instrument.

Return type:

None

load_msg_seviri(synsat_msg_number=3, **synsat_kwargs)

Loads configuration specific for the MSG-SEVIRI instrument.

Parameters:

• synsat_msg_number (int) – MSG number. (Default value = 3)

• **synsat_kwargs (dict) – Additional keyword arguments.

Return type:

None

load_mtg_fci(synsat_mtg_number=1, **synsat_kwargs)

Loads configuration specific for the MTG-FCI instrument.

Parameters:

• synsat_mtg_number (int) – MTG satellite number. (Default value = 1)

• **synsat_kwargs (dict) – Additional keyword arguments.

Return type:

None

run_workflow(**kwargs)

Run the full RTTOV workflow. This includes loading the atlasses, running RTTOV and extracting the output.

Parameters:

**kwargs (dict) – Additional keyword arguments

Return type:

None

set_default_options(**synsat_kwargs)

Sets default options for the RTTOV wrapper.

Parameters:

**synsat_kwargs (dict) – Additional keyword arguments.

Return type:

None

class synsatipy.synsat.attributes

Bases: object

class synsatipy.synsat.synsat_attributes

Bases: object

atlas = <synsatipy.synsat.attributes object>

synsat = <synsatipy.synsat.attributes object>

class synsatipy.data_handler.DataHandler(model='auto', return_profile=True, **kwargs)

Bases: object

Handles data operations for different models.

Parameters:

• model (str, optional) – The model to use. Default is “auto”. model can be “era”, “icon”, “nextgems” or “auto”. “auto” will try to autodetect the model based on the filename.

• return_profile (bool, optional) – Whether to return profile data. Default is True.

• **kwargs (dict) – Additional keyword arguments.

data2profile(**kwargs)

Converts data to a profile object.

Parameters:

**kwargs (dict) – Additional keyword arguments.

Returns:

• myProfiles (pyrttov.Profiles) – The profile object.

• Notes

• - The following variables are expected in the input_data

• ——————————————————————

• - p

• - t

• - q

• - lon

• - lat

• - SKT

• - SP

• - T2M

• - clwc

• - ciwc

• - cc

• - The following aspects need to be considered

• ——————————————————————

• - geometry

• - q2m

• - time

open_data(filename, **kwargs)

Opens data from a file.

Parameters:

• filename (str) – The name of the file to open.

• **kwargs (dict) – Additional keyword arguments.

Returns:

data – The opened data.

Return type:

object

stack_data_as_profile(**kwargs)

Stacks input data as profile data.

Parameters:

**kwargs (dict) – Additional keyword arguments. - profile_dimensions : list, optional

synsatipy.data_handler.autodetect_model_by_filename(fname)

Autodetects the model based on the filename.

Parameters:

fname (str) – The filename to check for model keywords.

Returns:

model – The detected model name.

Return type:

str

Raises:

ValueError – If the model cannot be autodetected.

synsatipy.data_handler.dt2cal(dt)

Convert array of datetime64 to a calendar array of year, month, day, hour, minute, seconds, microsecond with these quantites indexed on the last axis.

Parameters:

dt (datetime64 array (...)) – numpy.ndarray of datetimes of arbitrary shape

Returns:

cal – calendar array with last axis representing year, month, day, hour, minute, second, microsecond

Return type:

uint32 array (…, 7)

synsatipy Input modules

synsatipy.input_icon.define_variable_mapping(flavor)

Define the variable mapping for ICON.

Parameters:

flavor (str) – The flavor of the ICON dataset.

Returns:

var_mapping – The variable mapping for ICON.

Return type:

dict

synsatipy.input_icon.icon_name_analyzer(icon_name)

Analyze the ICON name and return the properties.

Parameters:

icon_name (str) – The name of the ICON file.

Returns:

icon_name_props – The properties of the ICON file.

Return type:

dict

Notes

The ICON name assumed to be in the form of {data_type}_{variable_stack}_{domain}_{level_type}_{time_str}_{postproc_suffix}.nc.

synsatipy.input_icon.icon_name_creator(icon_name_props)

Create the ICON name.

Parameters:

icon_name_props (dict) –

The properties of the ICON file. - “flavor” : str

”flavor” of the ICON file. Default is “ifces2”.

Returns:

icon_name – The ICON name.

Return type:

str

Notes

The ICON name assumed to be in the form of {data_type}_{variable_stack}_{domain}_{level_type}_{time_str}_{postproc_suffix}.nc.

synsatipy.input_icon.icon_variable_mapping(dset, flavor='ifces2', always_keep=[])

Rename ICON variables to ERA5 variables.

Parameters:

• dset (xarray.Dataset) – The ICON dataset.

• flavor (str, optional) – The flavor of the ICON dataset. Default is “ifces2”.

• always_keep (list, optional) – List of variables to always keep. Default is [].

Returns:

d_renamed – The renamed ICON dataset.

Return type:

xarray.Dataset

synsatipy.input_icon.open_icon(icon3d_name, qmin=1.1e-09, name_remapping=True, geofile=None, maskfile=None, **kwargs)

Open ICON dataset.

Parameters:

• icon3d_name (str) – The name of the ICON 3D file.

• qmin (float, optional) – Minimum value of qv. Default is 1.1e-9. Values below this threshold are clipped.

• name_remapping (bool, optional) – Whether to remap the variable names. Default is True.

• geofile (str, optional) – The name of the georeference file.

Returns:

icon – The ICON dataset.

Return type:

xarray.Dataset

synsatipy.input_icon.read_georef(geofile, rad2deg=True)

Read the georeference file.

Parameters:

• geofile (str) – The name of the georeference file.

• rad2deg (bool, optional) – Whether to convert the angles to degrees. Default is True.

Returns:

georef – The georeference data containing clat and clon.

Return type:

xarray.Dataset

synsatipy.input_icon.read_mask(maskfile)

Read the mask file.

Parameters:

maskfile (str) – The name of the mask file.

Returns:

mask – The mask data.

Return type:

xarray.Dataset

Input module for ERA data.

synsatipy.input_era.calc_pressure(era)

Calculate pressure from ERA data.

Parameters:

era (xarray.Dataset) – The ERA dataset.

Returns:

p – The calculated pressure.

Return type:

xarray.DataArray

Notes

The pressure is calculated as follows: p = B * ps + A, where p is the pressure, ps is the surface pressure,

synsatipy.input_era.era_name_analyzer(era_name)

Analyze the ERA name and return the properties.

Parameters:

era_name (str) – The name of the ERA file.

Returns:

era_name_props – The properties of the ERA file.

Return type:

dict

Notes

The ERA name assumed to be in the form of {modelname}-{data_type}-{region}-{year}-{month}-{day}.nc.

synsatipy.input_era.era_name_converter(era_name, mode='3d_to_2d')

Convert the ERA name.

Parameters:

• era_name (str) – The name of the ERA file.

• mode (str, optional) – The mode of the conversion. Default is “3d_to_2d”. - “3d_to_2d” : convert 3d to 2d.

Returns:

era_name_converted – The converted ERA name.

Return type:

str

synsatipy.input_era.open_era(era3d_name, add_pressure=True, qmin=1.1e-09, **kwargs)

Open the ERA data.

Parameters:

• era3d_name (str) – The name of the ERA 3D file.

• add_pressure (bool, optional) – Whether to add pressure. Default is True.

• qmin (float, optional) – The minimum value of q. Values below this threshold will be clipped. Default is 1.1e-9.

Returns:

era – The opened ERA dataset.

Return type:

xarray.Dataset

This module provides functions to open the nextGEMS dataset.

synsatipy.input_nextgems.get_index_for_regional_extend(dset, extend)

Get the index for the regional extend.

Parameters:

• dset (xarray.Dataset) – The dataset.

• extend (list) – The extend of the region.

Returns:

regional_index – The index for the region.

Return type:

numpy.ndarray

Notes

The extend is in the form of [lon_min, lon_max, lat_min, lat_max].

synsatipy.input_nextgems.get_index_for_zenith_mask(dset, max_zenith=80, lon0=0.0)

Get the index for the zenith mask.

Parameters:

• dset (xarray.Dataset) – The dataset.

• max_zenith (float, optional) – Maximum zenith angle. Default is 80.

• lon0 (float, optional) – Longitude of the sub-satellite point. Default is 0.0.

Returns:

regional_index – The index for the zenith

Return type:

numpy.ndarray

synsatipy.input_nextgems.input_regional_nextgems(cat_path, mask_type=None, extend=None, time=None, max_zenith=80, lon0=0.0, **kwargs)

Get the regional nextGEMS dataset.

Parameters:

• cat_path (str) – Path to the catalog file.

• mask_type (str, optional) – Type of mask. Types of mask can be “regional” or “zenith”. Default is None.

• extend (list, optional) – Extend of the region. The extend is in the form of [lon_min, lon_max, lat_min, lat_max]. Default is None.

• time (str, optional) – Time of the data. Default is None.

• max_zenith (float, optional) – Maximum zenith angle. Default is 80.

• lon0 (float, optional) – Longitude of the sub-satellite point. Default is 0.0.

• **kwargs (dict) – Additional keyword arguments.

Returns:

dset_reg_sub – The regional dataset

Return type:

xarray.Dataset

synsatipy.input_nextgems.nextgems_variable_mapping(dset)

Rename the variables of the nextGEMS dataset.

Parameters:

dset (xarray.Dataset) – The dataset.

Returns:

d_renamed – The dataset with renamed variables.

Return type:

xarray.Dataset

synsatipy.input_nextgems.open_nextgems(cat_path, name_remapping=True, **kwargs)

Open the nextGEMS dataset.

Parameters:

• cat_path (str) – Path to the catalog file.

• name_remapping (bool, optional) – Whether to remap the variable names. Default is True.

• **kwargs (dict) – Additional keyword arguments.

Returns:

dset – The opened dataset.

Return type:

xarray.Dataset

synsatipy.input_nextgems.open_ngdataset(cat_path, **kwargs)

Open the nextGEMS dataset from the catalog.

Parameters:

• cat_path (str) – Path to the catalog file.

• **kwargs (dict) – Additional keyword arguments.

• zoom (int, optional) – Zoom level. Default is 9.

• simulation_name (str, optional) – Name of the nextGEMS simulation to open. Default is "ngc4008a". The output frequency is selected automatically based on the simulation: "PT15M" for "ngc4008a", and "P1D" for all other simulations.

Returns:

dset – The opened dataset.

Return type:

xarray.Dataset

Notes

The dataset is attached with the coordinates.

synsatipy Output modules

Output module for SynSat data.

synsatipy.output.prepare_global_attrs()

Prepare the global attributes.

Returns:

attrs – The global attributes.

Return type:

dict

Notes

The global attributes are: - author : str

The author of the data.

• contactstr

  The contact email of the author.

• institutionstr

  The institution of the author.

• creation_timestr

  The creation time of the data.

• synsat_versionstr

  The SynSat version.

• synsat_githashstr

  The SynSat git hash.

• licensestr

  The license of the data.

• _local_software_pathstr

  The local software path.

synsatipy Utils modules

Set of tools for IO of either obs or sim.

synsatipy.utils.timetools.convert_time(t, roundTo=60.0)

Utility converts between two time formats A->B or B->A:

Parameters:

t (float or datetime object) – time A = either float as %Y%m%d.%f where %f is fraction of the day B = datetime object

Returns:

tout – time, counterpart to t

Return type:

datetime object or float

synsatipy.utils.timetools.convert_timevec(timevec)

Utility converts between an array of two time formats A->B or B->A:

Parameters:

timevec (list or array) – time list A = either float as %Y%m%d.%f where %f is fraction of the day B = datetime object

Returns:

tout – list of datetime objects or floats time, counterpart to t

Return type:

list

synsatipy.utils.timetools.round2day(t)

Rounds a np.datetime64 object to one day.

Parameters:

t (numpy datetime64 object) – input time

Returns:

tout – rounded output time

Return type:

numpy datetime64 object

synsatipy.utils.timetools.roundTime(dt=None, roundTo=60)

Round a datetime object to any time laps in seconds.

Parameters:

• dt (datetime object, optional, default now) – time to be round

• roundTo (float, optional, default 1 minute) – Closest number of seconds to round to, default 1 minute.

Returns:

• t (datetime object) – rounded time

• Author (Thierry Husson 2012 - Use it as you want but don’t blame me.)

synsatipy.utils.colormaps.enhanced_colormap(vmin=200.0, vmed=240.0, vmax=300.0)

Creates enhanced colormap typical of IR BTs.

Parameters:

• vmin (float, optional) – Minimum value for the colormap. Default is 200.0.

• vmed (float, optional) – Median value for the colormap. At this values shading jumps from color to gray-scale. Default is 240.0.

• vmax (float, optional) – Maximum value for the colormap. Default is 300.0.

Returns:

mymap – The generated colormap.

Return type:

matplotlib.colors.LinearSegmentedColormap

synsatipy.utils.colormaps.enhanced_wv62_cmap(vmin=200.0, vmed1=230.0, vmed2=240.0, vmax=260.0)

Creates enhanced colormap typical of WV62 BTs.

Parameters:

• vmin (float, optional) – Minimum value for the colormap. Default is 200.0.

• vmed1 (float, optional) – First median value for the colormap. At this values shading jumps from color to gray-scale. Default is 230.0.

• vmed2 (float, optional) – Second median value for the colormap. At this values shading jumps from gray-scale to afmhot shadings. Default is 240.0.

• vmax (float, optional) – Maximum value for the colormap. Default is 260.0.

Returns:

mymap – The generated colormap.

Return type:

matplotlib.colors.LinearSegmentedColormap

synsatipy.utils.spacetools.lonlat2azizen(lon, lat, lon0=0.0)

Calculates satellite zenith and azimuth given lon / lat. Assumes sub-satellite longitude at lon0 degree E.

Parameters:

• lon (float or numpy array) – longitude

• lat (float or numpy array) – latitude

• lon0 (float, optional) – longitude of sub-satellite point. The default is 0.0. This is the longitude of the satellite at zenith.

Returns:

• azi (float or numpy array) – satellite azimuth angle

• zen (float or numpy array) – satellite zenith angle