Utils API

silicone.utils.convert_units_to_MtCO2_equiv(df, metric_name='AR5GWP100')[source]

Converts the units of gases reported in kt into Mt CO2 equivalent per year

Uses GWP100 values from either (by default) AR5 or AR4 IPCC reports.

Parameters

  • df (pyam.IamDataFrame) – The input dataframe whose units need to be converted.

  • metric_name (str) – The name of the conversion metric to use. This will usually be AR<4/5/6>GWP100.

Returns

The input data with units converted.

Return type

pyam.IamDataFrame

silicone.utils.download_or_load_sr15(filename, valid_model_ids='*')[source]

Load SR1.5 data, if it isn’t there, download it

Parameters

  • filename (str) – Filename in which to look for/save the data

  • valid_model_ids (str) – Models to return from data

Returns

The loaded data

Return type

obj: pyam.IamDataFrame

silicone.utils.find_matching_scenarios(options_df, to_compare_df, variable_follower, variable_leaders, classify_scenarios, classify_models=['*'], return_all_info=False, use_change_not_abs=False)[source]

Groups scenarios and models into different classifications and uses those to work out which group contains a trendline most similar to the data. These combinations may group several models/scenarios together by means of wild cards. Most similar means having the smallest total squared distance between the to_compare_df value of variable_follower and the variable_follower values interpolated in options_df at the variable_leaders points in to_compare_df, i.e. assuming errors only exist in variable_follower. In the event of a tie between different scenario/model classifications, it returns the scenario/model combination that occurs earlier in the input lists, looping through scenarios first.

Parameters

  • options_df (pyam.IamDataFrame) – The dataframe containing the data for each scenario and model

  • to_compare_df (pyam.IamDataFrame) – The dataframe we wish to find the scenario group closest to. May contain one or more scenarios, we minimise the least squared errors for all the data colleectively.

  • variable_follower (str) – The variable we want to interpolate and compare to the value in to_compare_df

  • variable_leaders (list[str]) – The variable(s) we want to use to construct the interpolation (e.g. ["Emissions|CO2"]). In the event that there are multiple, we interpolate with each one separately and minimise the sum of the squared errors.

  • classify_scenarios (list[str]) – The names of scenarios or groups of scenarios that are possible matches. This may have “*”s to represent wild cards, hence multiple scenarios will have all their data combined to make the interpolator.

  • classify_models (list[str]) – The names of models or groups of models that are possible matches. This may have “*”s to represent wild cards, hence multiple models will have all their data combined to make the interpolator.

  • return_all_info (bool) – If True, instead of simply returning the strings specifying the closest scenario/model match, we return all scenario/model combinations in order of preference, along with the rms distance, quantifying the closeness.

  • use_change_not_abs (bool) – If True, the code looks for the trend with the closest derivatives rather than the closest absolute value, i.e. closest trend allowing for an offset. This requires data from more than one time.

Returns

  • if return_all_info == False

  • (string, string) – Strings specifying the model (first) and scenario (second) classifications that best match the data.

  • if return_all_info == True

  • dict – Maps the model and scenario classification strings to the measure of closeness.

Raises

ValueError – Not all required timepoints are present in the database we crunched, we have {dates we have} but you passed in {dates we need}.”

silicone.utils.get_sr15_scenarios(output_file, valid_model_ids)[source]

Collects world-level data from the IIASA database for the named models and saves them to a given location.

Parameters

  • output_file (str) – File name and location for data to be saved

  • valid_model_ids (list[str]) – Names of models that are to be fetched.

silicone.utils.return_cases_which_consistently_split(df, aggregate, components, how_close=None, metric_name='AR5GWP100')[source]

Returns model-scenario tuples which correctly split up the to_split into the various components. Components may contain wildcard “*”s to match several variables.

Parameters

  • df (pyam.IamDataFrame) – The input dataframe.

  • aggregate (str) – Name of the variable that should split into the others

  • components (list[str]) – List of the variable names whose sum should equal the to_split value (if expressed in common units).

  • how_close (dict) – This is a dictionary of numpy.isclose options specifying how exact the match must be for the case to be included as passing. By default we specify a relative tolerance of 1% (‘rtol’: 1e-2). The syntax for this can be found in the numpy documentation.

  • metric_name (str) – The name of the conversion metric to use. This will usually be AR<4/5/6>GWP100.

Returns

List of consistent (Model name, scenario name, region name) tuples.

Return type

list[(str, str, str)]