model.adoptiondata

'Adoption' is the amount or degree of use of a solution over time (typically increasing, sometimes decreasing). Adoption may be global or specific to a particular reagon. The units of adoption are defined by the solution that uses it (and are sometimes shared across multiple solutions, e.g. TeraWatts for energy).

There are multiple ways of representing adoption: AdoptionData (this module), CustomAdoption, and pure functions Linear or S-Curve. The HelperTables module mediates between the different options to provide the final adoption data for a solution/scenario.

AdoptionData represents adoption as a statistical combination, interpolation and/or extrapolation of some number of published studies (the 'source data', also called 'Existing Prognostications'). That is, the data from the existing study or studies is represented in data files, then the adoption is configured by how to aggregate that data.

Data sources are represented in a multi-level hierarchy, organized by region and by an assessment of whether the study is baseline (representing no change), conservative (representing modest change), or ambitious (most change). For example:

{
    'Ambitious Cases': {'Study Name A': 'filename A', 'Study Name B': 'filename B', ...},
    'Baseline Cases': {'Study Name C': 'filename C', 'Study Name D': 'filename D', ...},
    'Conservative Cases': {'Study Name E': 'filename E', 'Study Name F': 'filename F', ...}
}

Regional is somewhat awkwardly added in parallel to these, so you actually get data structures like this:

{
    'Ambitious Cases': { ... },
    'Baseline Cases': { ... },
    'Conservative Cases': { ... },
    'Region: OECD90': {
        'Ambitious Cases: { ... },
        ...
    },
    'Region: India': {
        'Ambitious Cases: { ... },
        ...
    },
    ....
}

These structures are serialized as JSON in a file named 'ad_sources.json' in the 'ad' subdirectory of solutions that use AdoptionData representations.

The configuration is represented by an multi-dimensional array of parameters which have the following meanings:

  • trend: Which fitting curve to use to interpolate/extrapolate missing data. Choices are linear, 2nd order polynomial, 3rd order polynomial, or exponential.
  • growth: Whether a lower, medium or higher estimate of growth should be used.
  • low_sd_mult: Values below mean(data) - low_sd_mult*(stdev(data)) are discarded before fitting. (deprecated.)
  • high_sd_mult: Values above mean(data) + high_sd_mult*(stdev(data)) are discarded before fitting. (deprecated.)
def make_adoption_config( adoption_config_array=None, overrides=None) -> pandas.core.frame.DataFrame:

Create an adoption configuration.

The configuration values all have standard defaults, but may be overridden. Overrides, if provided, should be in the form of a list of tuples (param, region, value). An override may be applied to a specific region (if the region value is non-empty), or to all regions (if the region value is None).

Example: this call will create a standard configuration that uses a 2nd degree polynomial fit for all regions, and a high growth adjustment for China and India:

    make_adoption_config(overrides=[
        ('trend',None,'2nd Poly'),
        ('growth','India','High'),
        ('growth','China','High')
    ])
class AdoptionData(model.data_handler.DataHandler):

Adoption of a solution, estimated from existing data (aka 'Existing Prognostications').

AdoptionData( ac, data_sources, adconfig, main_includes_regional=None, groups_include_hundred_percent=True)

Create AdoptionData object from data sources and configuration.

Args
  • ac: advanced controls object.
  • data_sources: a data structure organizing source data, as contained in an ad_sources.json file
  • adconfig: Configuration of statistical analysis, as returned by make_adoption_config.
  • main_includes_regional (boolean): whether the global min/max/sd should include data from the primary regions.
Quirks Parameters

groups_include_hundred_percent (boolean): Some models included the 100% / maximum case as a group when computing S.D., others (Electricity Generation) do not. Defaults to True.

def adoption_sources(self, region):

Return source adoption data for the specified region, as a dataframe with one column per source.

def adoption_data_per_region(self):

Return a dataframe of adoption data, one column per region.

def adoption_min_max_sd(self, region):

Return the min, max, and standard deviation for the adoption data for the specified region.

def adoption_low_med_high(self, region):

Return the selected data sources as Medium, and N stddev away as Low and High.

def adoption_trend(self, region, trend=None):

Adoption prediction via one of several interpolation algorithms in the region.

def adoption_is_single_source(self):

Whether the source data selected is one source or multiple.

def adoption_trend_per_region(self):

Return a dataframe of adoption trends, one column per region.