pycontrails.datalib.ch_aviation

Support for reading and parsing the ch-aviation fleet database.

Classes

AircraftChAviation(tail_number, ...)	Registered aircraft properties from ch-aviation database.
AirlineAircraftLookUp(aircraft_type_icao, ...)	Estimated engine properties from airline-aircraft look-up tables.
ChAviation([params])	Support for querying the ch-aviation fleet database.
ChAviationParams([copy_source, ...])	Parameters for ChAviation model.

class pycontrails.datalib.ch_aviation.AircraftChAviation(tail_number, icao_address, msn, country_of_registration, aircraft_type_icao, aircraft_type_iata, aircraft_family, aircraft_subfamily, manufacturer, engine_subtype, engine_uid, engine_manufacturer, n_engines, mtow_kg, operator_name, operator_icao, operator_iata, operator_type, aircraft_role, aircraft_market_group, n_seats, status, first_flight_date, delivery_date, cumulative_reported_hours, cumulative_reported_cycles, cumulative_reported_hours_ttm, cumulative_reported_cycles_ttm, cumulative_stats_as_of_date, average_annual_hours, average_daily_hours, average_daily_hours_ttm, average_annual_cycles, average_stats_as_of_date)

Bases: object

Registered aircraft properties from ch-aviation database.

aircraft_age_yrs(date)

Estimate aircraft age in years at the provided date.

Parameters:

date (pandas.Timestamp) – Date of interest

Returns:

float – Aircraft age in years at the provided date

aircraft_family

Aircraft family

aircraft_market_group

Aircraft market group

aircraft_role

Registered aircraft usage, i.e., passenger/military

aircraft_subfamily

Aircraft model

aircraft_type_iata

IATA aircraft type designator

aircraft_type_icao

ICAO aircraft type designator

average_annual_cycles

Average annual utilization cycles

average_annual_hours

Average annual utilization hours

average_daily_hours

Average daily utilization hours

average_daily_hours_ttm

Average daily utilization hours, trailing twelve months

average_stats_as_of_date

Average statistics as of date

country_of_registration

Country of registration

cumulative_reported_cycles

Cumulative reported cycles

cumulative_reported_cycles_ttm

Cumulative reported cycles, trailing twelve months

cumulative_reported_hours

Cumulative reported hours

cumulative_reported_hours_ttm

Cumulative reported hours, trailing twelve months

cumulative_stats_as_of_date

Cumulative statistics as of date

delivery_date

Delivery date

engine_manufacturer

Engine manufacturer

engine_subtype

Engine model

engine_uid

Engine unique identification number from the ICAO Aircraft Emissions Databank

first_flight_date

First flight date

icao_address

ICAO 24-bit address

manufacturer

Aircraft manufacturer

msn

Manufacturer Serial Number, MSN

mtow_kg

Maximum take-off weight (MTOW), [\(kg\)]

n_engines

Number of engines

n_seats

Number of seats

operator_iata

Operator IATA code

operator_icao

Operator ICAO code

operator_name

Operator name

operator_type

Operator type

status

Aircraft status

tail_number

Aircraft tail number

class pycontrails.datalib.ch_aviation.AirlineAircraftLookUp(aircraft_type_icao, engine_subtype, engine_uid, operator_name, operator_iata)

Bases: object

Estimated engine properties from airline-aircraft look-up tables.

aircraft_type_icao

ICAO aircraft type designator

engine_subtype

Engine model

engine_uid

Engine unique identification number from the ICAO Aircraft Emissions Databank

operator_iata

Operator IATA code

operator_name

Operator name

class pycontrails.datalib.ch_aviation.ChAviation(params=None, **params_kwargs)

Bases: Model

Support for querying the ch-aviation fleet database.

This model requires access to private ch-aviation fleet data, which is not included in the pycontrails distribution.

Data file paths can be specified via ChAviationParams:

• fleet_database_path: Path to the fleet database CSV file.

• airline_engine_lookup_path: Path to the airline-aircraft engine look-up table CSV file.

If paths are not provided, this interface looks for data files in a directory specified by the CH_AVIATION_ROOT_PATH environment variable. If not set, the default root path is ch-aviation/ as a sibling directory to the pycontrails repository root.

aircraft_by_icao_address

Lookup dictionary of the form {icao_address: AircraftChAviation}

aircraft_by_tail_number

Lookup dictionary of the form {tail_number: AircraftChAviation}

airline_engines

Lookup dictionary of the form {(airline_iata, aircraft_type_icao): AirlineAircraftLookUp}

default_params

alias of ChAviationParams

downselect_met()

Downselect met domain to the max/min bounds of source.

Override this method if special handling is needed in met down-selection.

• source must be defined before calling downselect_met().

• This method copies and re-assigns met using met.copy() to avoid side-effects.

Raises:

• ValueError – Raised if source is not defined. Raised if source is not a GeoVectorDataset.

• TypeError – Raised if met is not a MetDataset.

classmethod ecmwf_met_variables()

Return an ECMWF-specific list of required meteorology variables.

Returns:

tuple[MetVariable] – List of ECMWF-specific variants of required variables

eval(source=None, **params)

Extract specific aircraft properties for flight from ch-aviation database.

The source Flight must contain one of the following variables:

• tail_number (mandatory),

• icao_address (optional), or

• airline_iata and aircraft_type (optional)

The following properties are added to the source attributes if the tail_number or icao_address are available in the fleet database:

• msn

• country_of_registration

• atyp_icao_ch_a

• atyp_iata_ch_a

• atyp_name_ch_a

• atyp_manufacturer

• engine_name

• engine_uid

• engine_manufacturer

• n_engines_ch_a

• amass_mtow

• operator_name

• operator_icao

• operator_iata

• operator_type

• aircraft_role

• aircraft_market_group

• n_seats

• status

• first_flight_date

• delivery_date

• aircraft_age_yrs (if source is non-empty)

• cumulative_reported_hours

• cumulative_reported_hours_ttm

• cumulative_reported_cycles

• cumulative_reported_cycles_ttm

• cumulative_stats_as_of_date

• average_annual_hours

• average_daily_hours

• average_daily_hours_ttm

• average_annual_cycles

• average_stats_as_of_date

The following properties are added to the source attributes if the tail_number and icao_address are not included in ch-aviation, but airline_iata and aircraft_type are available:

• engine_name

• engine_uid

• operator_name

• operator_iata

Parameters:

source (Flight) – Flight to evaluate

Returns:

Flight – Flight with attached aircraft properties in Flight.attrs

classmethod generic_met_variables()

Return a model-agnostic list of required meteorology variables.

Returns:

tuple[MetVariable] – List of model-agnostic variants of required variables

get_data_param(other, key, default=<object object>, *, set_attr=True)

Get data from other source-compatible object with default set by model parameter key.

Retrieves data with the following hierarchy:

1. other.data[key]. Returns np.ndarray | xr.DataArray.

2. other.attrs[key]

3. params[key]

4. default

In case 3., the value of params[key] is attached to other.attrs[key] unless set_attr is set to False.

Parameters:

• key (str) – Key to retrieve

• default (Any, optional) – Default value if key is not found.

• set_attr (bool, optional) – If True (default), set source.attrs[key] to params[key] if found. This allows for better post model evaluation tracking.

Returns:

Any – Value(s) found for key in other data, other attrs, or model params

Raises:

KeyError – Raises KeyError if key is not found in any location and default is not provided.

See also

get_source_param, pycontrails.core.vector.GeoVectorDataset.get_data_or_attr

get_source_param(key, default=<object object>, *, set_attr=True)

Get source data with default set by parameter key.

Retrieves data with the following hierarchy:

1. source.data[key]. Returns np.ndarray | xr.DataArray.

2. source.attrs[key]

3. params[key]

4. default

In case 3., the value of params[key] is attached to source.attrs[key] unless set_attr is set to False.

Parameters:

• key (str) – Key to retrieve

• default (Any, optional) – Default value if key is not found.

• set_attr (bool, optional) – If True (default), set source.attrs[key] to params[key] if found. This allows for better post model evaluation tracking.

Returns:

Any – Value(s) found for key in source data, source attrs, or model params

Raises:

KeyError – Raises KeyError if key is not found in any location and default is not provided.

See also

get_data_param, pycontrails.core.vector.GeoVectorDataset.get_data_or_attr

classmethod gfs_met_variables()

Return a GFS-specific list of required meteorology variables.

Returns:

tuple[MetVariable] – List of GFS-specific variants of required variables

property hash

Generate a unique hash for model instance.

Returns:

str – Unique hash for model instance (sha1)

property interp_kwargs

Shortcut to create interpolation arguments from params.

The output of this is useful for passing to interpolate_met().

Returns:

dict[str, Any] – Dictionary with keys

• ”method”

• ”bounds_error”

• ”fill_value”

• ”localize”

• ”use_indices”

• ”q_method”

as determined by params.

long_name = 'ch-aviation fleet database'

met

Meteorology data

met_required = False

Require meteorology is not None on __init__()

met_variables

Required meteorology pressure level variables. Each element in the list is a MetVariable or a tuple[MetVariable]. If element is a tuple[MetVariable], the variable depends on the data source and the tuple must include entries for a model-agnostic variable, an ECMWF-specific variable, and a GFS-specific variable. Only one of the three variable in the tuple is required for model evaluation.

name = 'ch-aviation'

optional_met_variables

Optional meteorology variables

params

Instantiated model parameters, in dictionary form

processed_met_variables

Set of required parameters if processing already complete on met input.

registered_aircraft_properties(tail_number, icao_address=None)

Get registered aircraft properties from ch-aviation fleet database.

Parameters:

• tail_number (str) – Aircraft tail number

• icao_address (str) – ICAO 24-bit address (Hexcode)

Returns:

AircraftChAviation | None – Registered aircraft properties. If tail_number and icao_address are not available in the ch-aviation fleet database, None is returned.

require_met()

Ensure that met is a MetDataset.

Returns:

MetDataset – Returns reference to met. This is helpful for type narrowing met when meteorology is required.

Raises:

ValueError – Raises when met is None.

require_source_type(type_)

Ensure that source is type_.

Returns:

_Source – Returns reference to source. This is helpful for type narrowing source to specific type(s).

Raises:

ValueError – Raises when source is not _type_.

set_source(source=None)

Attach original or copy of input source to source.

Parameters:

source (MetDataset | GeoVectorDataset | Flight | Iterable[Flight] | None) – Parameter source passed in eval(). If None, an empty MetDataset with coordinates like met is set to source.

See also

eval

set_source_met(optional=False, variable=None)

Ensure or interpolate each required met_variables on source .

For each variable in met_variables, check source for data variable with the same name.

For GeoVectorDataset sources, try to interpolate met if variable does not exist.

For MetDataset sources, try to get data from met if variable does not exist.

Parameters:

• optional (bool, optional) – Include optional_met_variables

• variable (MetVariable | Sequence[MetVariable] | None, optional) – MetVariable to set, from met_variables. If None, set all variables in met_variables and optional_met_variables if optional is True.

Raises:

• ValueError – Variable does not exist and source is a MetDataset.

• KeyError – Variable not found in source or met.

source

Data evaluated in model

transfer_met_source_attrs(source=None)

Transfer met source metadata from met to source.

update_params(params=None, **params_kwargs)

Update model parameters on params.

Parameters:

• params (dict[str, Any], optional) – Model parameters to update, as dictionary. Defaults to {}

• **params_kwargs (Any) – Override keys in params with keyword arguments.

class pycontrails.datalib.ch_aviation.ChAviationParams(copy_source=True, interpolation_method='linear', interpolation_bounds_error=False, interpolation_fill_value=nan, interpolation_localize=False, interpolation_use_indices=False, interpolation_q_method=None, verify_met=True, downselect_met=True, met_longitude_buffer=(0.0, 0.0), met_latitude_buffer=(0.0, 0.0), met_level_buffer=(0.0, 0.0), met_time_buffer=(np.timedelta64(0, 'h'), np.timedelta64(0, 'h')), fleet_database_path=None, airline_engine_lookup_path=None)

Bases: ModelParams

Parameters for ChAviation model.

airline_engine_lookup_path = None

Path to airline-aircraft engine look-up table CSV file.

as_dict()

Convert object to dictionary.

We use this method instead of dataclasses.asdict to use a shallow/unrecursive copy. This will return values as Any instead of dict.

Returns:

dict[str, Any] – Dictionary version of self.

copy_source = True

Copy input source data on eval

downselect_met = True

Downselect input MetDataset` to region around source.

fleet_database_path = None

Path to ch-aviation fleet database CSV file.

interpolation_bounds_error = False

If True, points lying outside interpolation will raise an error

interpolation_fill_value = nan

Used for outside interpolation value if interpolation_bounds_error is False

interpolation_localize = False

Experimental. See pycontrails.core.interpolation.

interpolation_method = 'linear'

Interpolation method. Supported methods include “linear”, “nearest”, “slinear”, “cubic”, and “quintic”. See scipy.interpolate.RegularGridInterpolator for the description of each method. Not all methods are supported by all met grids. For example, the “cubic” method requires at least 4 points per dimension.

interpolation_q_method = None

Experimental. Alternative interpolation method to account for specific humidity lapse rate bias. Must be one of None, "cubic-spline", or "log-q-log-p". If None, no special interpolation is used for specific humidity. The "cubic-spline" method applies a custom stretching of the met interpolation table to account for the specific humidity lapse rate bias. The "log-q-log-p" method interpolates in the log of specific humidity and pressure, then converts back to specific humidity. Only used by models calling to interpolate_met().

interpolation_use_indices = False

Experimental. See pycontrails.core.interpolation.

met_latitude_buffer = (0.0, 0.0)

Met latitude buffer for input to Flight.downselect_met(), in WGS84 coordinates. Only applies when downselect_met is True.

met_level_buffer = (0.0, 0.0)

Met level buffer for input to Flight.downselect_met(), in [\(hPa\)]. Only applies when downselect_met is True.

met_longitude_buffer = (0.0, 0.0)

Met longitude buffer for input to Flight.downselect_met(), in WGS84 coordinates. Only applies when downselect_met is True.

met_time_buffer = (np.timedelta64(0,'h'), np.timedelta64(0,'h'))

Met time buffer for input to Flight.downselect_met() Only applies when downselect_met is True.

verify_met = True

Call _verify_met() on model instantiation.