cti-python-stix2/stix2/confidence/scales.py

# -*- coding: utf-8 -*-

"""Functions to perform conversions between the different Confidence scales.
As specified in STIX™ Version 2.1. Part 1: STIX Core Concepts - Appendix B"""


def none_low_med_high_to_value(scale_value):
    """
    This method will transform a string value from the None / Low / Med /
    High scale to its confidence integer representation.

    The scale for this confidence representation is the following:
    ====================    =====================
    None/ Low/ Med/ High    STIX Confidence Value
    ====================    =====================
    Not Specified           Not Specified
    None                    0
    Low                     15
    Med                     50
    High                    85
    ====================    =====================

    Args:
        scale_value: A string value from the scale. Accepted strings are
            "None", "Low", "Med" and "High". Argument is case sensitive.

    Returns:
        int: The numerical representation corresponding to values in the None /
            Low / Med / High scale.

    Raises:
        ValueError: If `scale_value` is not within the accepted strings.
    """
    if scale_value == "None":
        return 0
    elif scale_value == "Low":
        return 15
    elif scale_value == "Med":
        return 50
    elif scale_value == "High":
        return 85
    else:
        raise ValueError("STIX Confidence value cannot be determined for %s" % scale_value)


def value_to_none_low_medium_high(confidence_value):
    """
    This method will transform an integer value into the None / Low / Med /
    High scale string representation.

    The scale for this confidence representation is the following:
    =============== ====================
    Range of Values None/ Low/ Med/ High
    =============== ====================
    0               None
    1-29            Low
    30-69           Med
    70-100          High
    =============== ====================

    Args:
        confidence_value: An integer value between 0 and 100.

    Returns:
        str: A string corresponding to the None / Low / Med / High scale.

    Raises:
        ValueError: If `confidence_value` is out of bounds.

    """
    if confidence_value == 0:
        return "None"
    elif 29 >= confidence_value >= 1:
        return "Low"
    elif 69 >= confidence_value >= 30:
        return "Med"
    elif 100 >= confidence_value >= 70:
        return "High"
    else:
        raise ValueError("Range of values out of bounds: %s" % confidence_value)


def zero_ten_to_value(scale_value):
    """
    This method will transform a string value from the 0-10 scale to its
    confidence integer representation.

    The scale for this confidence representation is the following:
    ====================    =====================
    0-10 Scale              STIX Confidence Value
    ====================    =====================
    0                       0
    1                       10
    2                       20
    3                       30
    4                       40
    5                       50
    6                       60
    7                       70
    8                       80
    9                       90
    10                      100
    ====================    =====================

    Args:
        scale_value: A string value from the scale. Accepted strings are "0"
            through "10" inclusive.

    Returns:
        int: The numerical representation corresponding to values in the 0-10
            scale.

    Raises:
        ValueError: If `scale_value` is not within the accepted strings.

    """
    if scale_value == "0":
        return 0
    elif scale_value == "1":
        return 10
    elif scale_value == "2":
        return 20
    elif scale_value == "3":
        return 30
    elif scale_value == "4":
        return 40
    elif scale_value == "5":
        return 50
    elif scale_value == "6":
        return 60
    elif scale_value == "7":
        return 70
    elif scale_value == "8":
        return 80
    elif scale_value == "9":
        return 90
    elif scale_value == "10":
        return 100
    else:
        raise ValueError("STIX Confidence value cannot be determined for %s" % scale_value)


def value_to_zero_ten(confidence_value):
    """
    This method will transform an integer value into the 0-10 scale string
    representation.

    The scale for this confidence representation is the following:
    =============== ==========
    Range of Values 0-10 Scale
    =============== ==========
    0-4             0
    5-14            1
    15-24           2
    25-34           3
    35-44           4
    45-54           5
    55-64           6
    65-74           7
    75-84           8
    85-94           9
    95-100          10
    =============== ==========

    Args:
        confidence_value: An integer value between 0 and 100.

    Returns:
        str: A string corresponding to the 0-10 scale.

    Raises:
        ValueError: If `confidence_value` is out of bounds.

    """
    if 4 >= confidence_value >= 0:
        return "0"
    elif 14 >= confidence_value >= 5:
        return "1"
    elif 24 >= confidence_value >= 15:
        return "2"
    elif 34 >= confidence_value >= 25:
        return "3"
    elif 44 >= confidence_value >= 35:
        return "4"
    elif 54 >= confidence_value >= 45:
        return "5"
    elif 64 >= confidence_value >= 55:
        return "6"
    elif 74 >= confidence_value >= 65:
        return "7"
    elif 84 >= confidence_value >= 75:
        return "8"
    elif 94 >= confidence_value >= 85:
        return "9"
    elif 100 >= confidence_value >= 95:
        return "10"
    else:
        raise ValueError("Range of values out of bounds: %s" % confidence_value)


def admiralty_credibility_to_value(scale_value):
    """
    This method will transform a string value from the Admiralty Credibility
    scale to its confidence integer representation.

    The scale for this confidence representation is the following:
    ==============================  =====================
    Admiralty Credibility           STIX Confidence Value
    ==============================  =====================
    6 - Truth cannot be judged      (Not present)
    5 - Improbable                  10
    4 - Doubtful                    30
    3 - Possibly True               50
    2 - Probably True               70
    1 - Confirmed by other sources  90
    ==============================  =====================

    Args:
        scale_value: A string value from the scale. Accepted strings are
            "6 - Truth cannot be judged", "5 - Improbable", "4 - Doubtful",
            "3 - Possibly True", "2 - Probably True" and
            "1 - Confirmed by other sources". Argument is case sensitive.

    Returns:
        int: The numerical representation corresponding to values in the
            Admiralty Credibility scale.

    Raises:
        ValueError: If `scale_value` is not within the accepted strings.

    """
    if scale_value == "6 - Truth cannot be judged":
        raise ValueError("STIX Confidence value cannot be determined for %s" % scale_value)  # TODO: What happens here?
    elif scale_value == "5 - Improbable":
        return 10
    elif scale_value == "4 - Doubtful":
        return 30
    elif scale_value == "3 - Possibly True":
        return 50
    elif scale_value == "2 - Probably True":
        return 70
    elif scale_value == "1 - Confirmed by other sources":
        return 90
    else:
        raise ValueError("STIX Confidence value cannot be determined for %s" % scale_value)


def value_to_admiralty_credibility(confidence_value):
    """
    This method will transform an integer value into the Admiralty Credibility
    scale string representation.

    The scale for this confidence representation is the following:
    =============== ==============================
    Range of Values Admiralty Credibility
    =============== ==============================
    N/A             6 - Truth cannot be judged
    0-19            5 - Improbable
    20-39           4 - Doubtful
    40-59           3 - Possibly True
    60-79           2 - Probably True
    80-100          1 - Confirmed by other sources
    =============== ==============================

    Args:
        confidence_value: An integer value between 0 and 100.

    Returns:
        str: A string corresponding to the Admiralty Credibility scale.

    Raises:
        ValueError: If `confidence_value` is out of bounds.

    """
    # TODO: Case "6 - Truth cannot be judged"
    if 19 >= confidence_value >= 0:
        return "5 - Improbable"
    elif 39 >= confidence_value >= 20:
        return "4 - Doubtful"
    elif 59 >= confidence_value >= 40:
        return "3 - Possibly True"
    elif 79 >= confidence_value >= 60:
        return "2 - Probably True"
    elif 100 >= confidence_value >= 80:
        return "1 - Confirmed by other sources"
    else:
        raise ValueError("Range of values out of bounds: %s" % confidence_value)


def wep_to_value(scale_value):
    """
    This method will transform a string value from the WEP scale to its
    confidence integer representation.

    The scale for this confidence representation is the following:
    ====================================    =====================
    WEP                                     STIX Confidence Value
    ====================================    =====================
    Impossible                              0
    Highly Unlikely/Almost Certainly Not    10
    Unlikely/Probably Not                   20
    Even Chance                             50
    Likely/Probable                         70
    Highly likely/Almost Certain            90
    Certain                                 100
    ====================================    =====================

    Args:
        scale_value: A string value from the scale. Accepted strings are
            "Impossible", "Highly Unlikely/Almost Certainly Not",
            "Unlikely/Probably Not", "Even Chance", "Likely/Probable",
            "Highly likely/Almost Certain" and "Certain". Argument is case
            sensitive.

    Returns:
        int: The numerical representation corresponding to values in the WEP
            scale.

    Raises:
        ValueError: If `scale_value` is not within the accepted strings.

    """
    if scale_value == "Impossible":
        return 0
    elif scale_value == "Highly Unlikely/Almost Certainly Not":
        return 10
    elif scale_value == "Unlikely/Probably Not":
        return 30
    elif scale_value == "Even Chance":
        return 50
    elif scale_value == "Likely/Probable":
        return 70
    elif scale_value == "Highly likely/Almost Certain":
        return 90
    elif scale_value == "Certain":
        return 100
    else:
        raise ValueError("STIX Confidence value cannot be determined for %s" % scale_value)


def value_to_wep(confidence_value):
    """
    This method will transform an integer value into the WEP scale string
    representation.

    The scale for this confidence representation is the following:
    =============== ====================================
    Range of Values WEP
    =============== ====================================
    0               Impossible
    1-19            Highly Unlikely/Almost Certainly Not
    20-39           Unlikely/Probably Not
    40-59           Even Chance
    60-79           Likely/Probable
    80-99           Highly likely/Almost Certain
    100             Certain
    =============== ====================================

    Args:
        confidence_value: An integer value between 0 and 100.

    Returns:
        str: A string corresponding to the WEP scale.

    Raises:
        ValueError: If `confidence_value` is out of bounds.

    """
    if confidence_value == 0:
        return "Impossible"
    elif 19 >= confidence_value >= 1:
        return "Highly Unlikely/Almost Certainly Not"
    elif 39 >= confidence_value >= 20:
        return "Unlikely/Probably Not"
    elif 59 >= confidence_value >= 40:
        return "Even Chance"
    elif 79 >= confidence_value >= 60:
        return "Likely/Probable"
    elif 99 >= confidence_value >= 80:
        return "Highly likely/Almost Certain"
    elif confidence_value == 100:
        return "Certain"
    else:
        raise ValueError("Range of values out of bounds: %s" % confidence_value)


def dni_to_value(scale_value):
    """
    This method will transform a string value from the DNI scale to its
    confidence integer representation.

    The scale for this confidence representation is the following:
    ======================================= =====================
    DNI Scale                               STIX Confidence Value
    ======================================= =====================
    Almost No Chance / Remote               5
    Very Unlikely / Highly Improbable       15
    Unlikely / Improbable                   30
    Roughly Even Change / Roughly Even Odds 50
    Likely / Probable                       70
    Very Likely / Highly Probable           85
    Almost Certain / Nearly Certain         95
    ======================================= =====================

    Args:
        scale_value: A string value from the scale. Accepted strings are
            "Almost No Chance / Remote", "Very Unlikely / Highly Improbable",
            "Unlikely / Improbable", "Roughly Even Change / Roughly Even Odds",
            "Likely / Probable", "Very Likely / Highly Probable" and
            "Almost Certain / Nearly Certain". Argument is case sensitive.

    Returns:
        int: The numerical representation corresponding to values in the DNI
            scale.

    Raises:
        ValueError: If `scale_value` is not within the accepted strings.

    """
    if scale_value == "Almost No Chance / Remote":
        return 5
    elif scale_value == "Very Unlikely / Highly Improbable":
        return 15
    elif scale_value == "Unlikely / Improbable":
        return 30
    elif scale_value == "Roughly Even Change / Roughly Even Odds":
        return 50
    elif scale_value == "Likely / Probable":
        return 70
    elif scale_value == "Very Likely / Highly Probable":
        return 85
    elif scale_value == "Almost Certain / Nearly Certain":
        return 95
    else:
        raise ValueError("STIX Confidence value cannot be determined for %s" % scale_value)


def value_to_dni(confidence_value):
    """
    This method will transform an integer value into the DNI scale string
    representation.

    The scale for this confidence representation is the following:
    =============== =======================================
    Range of Values DNI Scale
    =============== =======================================
    0-9             Almost No Chance / Remote
    10-19           Very Unlikely / Highly Improbable
    20-39           Unlikely / Improbable
    40-59           Roughly Even Change / Roughly Even Odds
    60-79           Likely / Probable
    80-89           Very Likely / Highly Probable
    90-100          Almost Certain / Nearly Certain
    =============== =======================================

    Args:
        confidence_value: An integer value between 0 and 100.

    Returns:
        str: A string corresponding to the DNI scale.

    Raises:
        ValueError: If `confidence_value` is out of bounds.

    """
    if 9 >= confidence_value >= 0:
        return "Almost No Chance / Remote"
    elif 19 >= confidence_value >= 10:
        return "Very Unlikely / Highly Improbable"
    elif 39 >= confidence_value >= 20:
        return "Unlikely / Improbable"
    elif 59 >= confidence_value >= 40:
        return "Roughly Even Change / Roughly Even Odds"
    elif 79 >= confidence_value >= 60:
        return "Likely / Probable"
    elif 89 >= confidence_value >= 80:
        return "Very Likely / Highly Probable"
    elif 100 >= confidence_value >= 90:
        return "Almost Certain / Nearly Certain"
    else:
        raise ValueError("Range of values out of bounds: %s" % confidence_value)