:py:mod:`SBTi.target_validation`
================================

.. py:module:: SBTi.target_validation


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   SBTi.target_validation.TargetProtocol




.. py:class:: TargetProtocol(config: Type[SBTi.configs.PortfolioAggregationConfig] = PortfolioAggregationConfig)

   This class validates the targets, to make sure that only active, useful targets are considered. It then combines the targets with company-related data into a dataframe where there's one row for each of the nine possible target types (short, mid, long * S1+S2, S3, S1+S2+S3). This class follows the procedures outlined by the target protocol that is a part of the "Temperature Rating Methodology" (2020), which has been created by CDP Worldwide and WWF International.

   :param config: A Portfolio aggregation config

   .. py:method:: process(self, targets: List[SBTi.interfaces.IDataProviderTarget], companies: List[SBTi.interfaces.IDataProviderCompany]) -> pandas.DataFrame

      Process the targets and companies, validate all targets and return a data frame that combines all targets and company data into a 9-box grid.

      :param targets: A list of targets
      :param companies: A list of companies
      :return: A data frame that combines the processed data


   .. py:method:: validate(self, target: SBTi.interfaces.IDataProviderTarget) -> bool

      Validate a target, meaning it should:

      * Have a valid type
      * Not be finished
      * A valid end year

      :param target: The target to validate
      :return: True if it's a valid target, false if it isn't


   .. py:method:: _split_s1s2s3(self, target: SBTi.interfaces.IDataProviderTarget) -> Tuple[SBTi.interfaces.IDataProviderTarget, Optional[SBTi.interfaces.IDataProviderTarget]]

      If there is a s1s2s3 scope, split it into two targets with s1s2 and s3

      :param target: The input target
      :return The split targets or the original target and None


   .. py:method:: _combine_s1_s2(self, target: SBTi.interfaces.IDataProviderTarget)

      Check if there is an S2 target that matches this target exactly (if this is a S1 target) and combine them into one target.

      :param target: The input target
      :return: The combined target (or the original if no combining was required)


   .. py:method:: _convert_s1_s2(self, target: SBTi.interfaces.IDataProviderTarget)

      Convert a S1 or S2 target into a S1+S2 target.

      :param target: The input target
      :return: The converted target (or the original if no conversion was required)


   .. py:method:: _boundary_coverage(self, target: SBTi.interfaces.IDataProviderTarget) -> SBTi.interfaces.IDataProviderTarget

      Test on boundary coverage:

      Option 1: minimal coverage threshold
      For S1+S2 targets: coverage% must be at or above 95%, for S3 targets coverage must be above 67%

      Option 2: weighted coverage
      Thresholds are still 95% and 67%, target is always valid. Below threshold ambition is scaled.*
      New target ambition = input target ambition * coverage
      *either here or in tem score module

      Option 3: default coverage
      Target is always valid, % uncovered is given default score in temperature score module.

      :param target: The input target
      :return: The original target with a weighted reduction ambition, if so required


   .. py:method:: _time_frame(self, target: SBTi.interfaces.IDataProviderTarget) -> SBTi.interfaces.IDataProviderTarget

      Time frame is forward looking: target year - current year. Less than 5y = short, between 5 and 15 is mid, 15 to 30 is long

      :param target: The input target
      :return: The original target with the time_frame field filled out (if so required)


   .. py:method:: _prepare_target(self, target: SBTi.interfaces.IDataProviderTarget)

      Prepare a target for usage later on in the process.

      :param target:
      :return:


   .. py:method:: prepare_targets(self, targets: List[SBTi.interfaces.IDataProviderTarget])


   .. py:method:: _find_target(self, row: pandas.Series, target_columns: List[str]) -> pandas.Series

      Find the target that corresponds to a given row. If there are multiple targets available, filter them.

      :param row: The row from the data set that should be looked for
      :param target_columns: The columns that need to be returned
      :return: returns records from the input data, which contains company and target information, that meet specific criteria. For example, record of greatest emissions_in_scope


   .. py:method:: group_targets(self)

      Group the targets and create the 9-box grid (short, mid, long * s1s2, s3, s1s2s3).
      Group valid targets by category & filter multiple targets#
      Input: a list of valid targets for each company:
      For each company:

      Group all valid targets based on scope (S1+S2 / S3 / S1+S2+S3) and time frame (short / mid / long-term)
      into 6 categories.

      For each category: if more than 1 target is available, filter based on the following criteria
      -- Highest boundary coverage
      -- Latest base year
      -- Target type: Absolute over intensity
      -- If all else is equal: average the ambition of targets