JSONFormatter#

class impactshpc.src.core.JSONFormatter(uncertainty_format: UncertaintyFormat = UncertaintyFormat.STANDARD_DEVIATION)

Bases: Formatter[dict, str]

Methods Summary

format_extracted_important_values(name, ...)

Format extracted values which are the ReplicableValue instances with the Replicable.important boolean set to true.

format_operation(formula, name, value, min, ...)

Format an Operation instance.

format_result(result, extracted_important_values)

Format the final result.

format_sourced_value(name, value, min, max, ...)

Format a SourcedValue instance.

Methods Documentation

format_extracted_important_values(name: str | None, value: Quantity, min: Quantity, max: Quantity, standard_deviation: Quantity, source: str, explaination: str | None, warnings: List[str], ontology: Ontology | None) → dict#

Format extracted values which are the ReplicableValue instances with the Replicable.important boolean set to true. These values are extracted and can be used to format the final result in format_result().

Parameters:

  • name (str | None) – Name of the SourcedValue, if any. It is unique.

  • value (Quantity) – The central value, with units.

  • min (Quantity) – Minimum plausible value.

  • max (Quantity) – Maximum plausible value.

  • standard_deviation (Quantity) – Standard deviation (uncertainty) of the value.

  • source (str) – The source (quote, link, etc.) of the value.

  • warnings (List[str]) – List of warnings or notes about the value.

  • explanation (str | None) – Optional explanation or description.

  • ontology (str | None) – Optional ontology tag for semantic annotation.

Returns:

Formatted extracted important source value.

Return type:

T

format_operation(formula: str, name: str | None, value: Quantity, min: Quantity, max: Quantity, standard_deviation: Quantity, operator: str, operands: list[dict], isInfix: bool, explaination: str | None, warnings: List[str], ontology: Ontology | None, recursion_level: int, already_seen: bool, important: bool) → dict#

Format an Operation instance. This method must be implemented.

Parameters:

  • formula (str) – A string representing the formula that the Operation represents, returned by Operation._as_formula().

  • name (str | None) – Name of the SourcedValue, if any. It is unique.

  • value (Quantity) – The central value, with units.

  • min (Quantity) – Minimum plausible value.

  • max (Quantity) – Maximum plausible value.

  • standard_deviation (Quantity) – Standard deviation (uncertainty) of the value.

  • operator (str) – The operator of this operation.

  • operands (list[T]) – List of the operands used in this operation, already formatted.

  • isInfix (bool) – True if the operation is infix (i.e., it’s a binary operation and the operator is placed between the operands, like A + B). False if the operation is prefix (i.e., the operation can have any number of parameters and is written as a function, like ln(a)).

  • warnings (List[str]) – List of warnings or notes about the value.

  • explanation (str | None) – Optional explanation or description.

  • ontology (str | None) – Optional ontology tag for semantic annotation.

  • recursion_level (int) – Recursion level is the depth of this value in the tree represented by the ReplicableValue on which we called ReplicableValue.explain().

  • already_seen (bool) – Whether the value has already been formatted in a previously traversed branch of the tree represented by the ReplicableValue on which we called ReplicableValue.explain(). The Operation._explain_rec() method uses Depth-First Search and respects the order of the Operation.operands list.

  • important (bool) – True if the value is an important intermediate result. If true, it will be extracted and passed to format_result() in the list of extracted important values.

Returns:

The formatted Operation.

Return type:

T

format_result(result: dict, extracted_important_values: List[dict]) → str#

Format the final result. Does nothing by default, but can be overridden to process or modify the final result before ReplicableValue.explain() returns it.

For example, TextFormatter overrides format_result() in order to add the extracted important values at the beginning of the explanation. JSONFormatter override format_result() to use json.dumps() on the final dict returned by format_operation() and format_sourced_value()

Parameters:

  • result (T) – The formatted result of ReplicableValue._explain_rec().

  • extracted_important_values (list[T]) – The extracted important values. These can be used to add a quick recap of the important results at the beginning of the explanation.

Returns:

By default, returns the result parameter as is. Can be overridden to modify the final result before ReplicableValue.explain() returns it.

Return type:

T

format_sourced_value(name: str | None, value: Quantity, min: Quantity, max: Quantity, standard_deviation: Quantity, source: str, explaination: str | None, warnings: List[str], ontology: Ontology | None, recursion_level: int, already_seen: bool, important: bool) → dict#

Format a SourcedValue instance. This method must be implemented.

name#

Name of the SourcedValue, if any.

Type:

str | None

value#

The central value, with units.

Type:

Quantity

min#

Minimum plausible value.

Type:

Quantity

max#

Maximum plausible value.

Type:

Quantity

standard_deviation#

Standard deviation (uncertainty) of the value.

Type:

Quantity

source#

The source (quote, link, etc.) of the value.

Type:

str

warnings#

List of warnings or notes about the value.

Type:

List[str]

explanation#

Optional explanation or description.

Type:

str | None

ontology#

Optional ontology tag for semantic annotation.

Type:

str | None

recursion_level#

Recursion level is the depth of this value in the tree represented by the ReplicableValue on which we called ReplicableValue.explain().

Type:

int

already_seen#

Whether the value has already been formatted in a previously traversed branch of the tree represented by the ReplicableValue on which we called ReplicableValue.explain(). The Operation._explain_rec() method uses Depth-First Search and respects the order of the Operation.operands list.

Type:

bool

important#

True if the value is an important intermediate result. If true, it will be extracted and passed to format_result() in the list of extracted important values.

Type:

bool

Returns:

The formatted SourcedValue.

Return type:

T

format_extracted_important_values(name: str | None, value: Quantity, min: Quantity, max: Quantity, standard_deviation: Quantity, source: str, explaination: str | None, warnings: List[str], ontology: Ontology | None) → dict

Format extracted values which are the ReplicableValue instances with the Replicable.important boolean set to true. These values are extracted and can be used to format the final result in format_result().

Parameters:

  • name (str | None) – Name of the SourcedValue, if any. It is unique.

  • value (Quantity) – The central value, with units.

  • min (Quantity) – Minimum plausible value.

  • max (Quantity) – Maximum plausible value.

  • standard_deviation (Quantity) – Standard deviation (uncertainty) of the value.

  • source (str) – The source (quote, link, etc.) of the value.

  • warnings (List[str]) – List of warnings or notes about the value.

  • explanation (str | None) – Optional explanation or description.

  • ontology (str | None) – Optional ontology tag for semantic annotation.

Returns:

Formatted extracted important source value.

Return type:

T

format_operation(formula: str, name: str | None, value: Quantity, min: Quantity, max: Quantity, standard_deviation: Quantity, operator: str, operands: list[dict], isInfix: bool, explaination: str | None, warnings: List[str], ontology: Ontology | None, recursion_level: int, already_seen: bool, important: bool) → dict

Format an Operation instance. This method must be implemented.

Parameters:

  • formula (str) – A string representing the formula that the Operation represents, returned by Operation._as_formula().

  • name (str | None) – Name of the SourcedValue, if any. It is unique.

  • value (Quantity) – The central value, with units.

  • min (Quantity) – Minimum plausible value.

  • max (Quantity) – Maximum plausible value.

  • standard_deviation (Quantity) – Standard deviation (uncertainty) of the value.

  • operator (str) – The operator of this operation.

  • operands (list[T]) – List of the operands used in this operation, already formatted.

  • isInfix (bool) – True if the operation is infix (i.e., it’s a binary operation and the operator is placed between the operands, like A + B). False if the operation is prefix (i.e., the operation can have any number of parameters and is written as a function, like ln(a)).

  • warnings (List[str]) – List of warnings or notes about the value.

  • explanation (str | None) – Optional explanation or description.

  • ontology (str | None) – Optional ontology tag for semantic annotation.

  • recursion_level (int) – Recursion level is the depth of this value in the tree represented by the ReplicableValue on which we called ReplicableValue.explain().

  • already_seen (bool) – Whether the value has already been formatted in a previously traversed branch of the tree represented by the ReplicableValue on which we called ReplicableValue.explain(). The Operation._explain_rec() method uses Depth-First Search and respects the order of the Operation.operands list.

  • important (bool) – True if the value is an important intermediate result. If true, it will be extracted and passed to format_result() in the list of extracted important values.

Returns:

The formatted Operation.

Return type:

T

format_result(result: dict, extracted_important_values: List[dict]) → str

Format the final result. Does nothing by default, but can be overridden to process or modify the final result before ReplicableValue.explain() returns it.

For example, TextFormatter overrides format_result() in order to add the extracted important values at the beginning of the explanation. JSONFormatter override format_result() to use json.dumps() on the final dict returned by format_operation() and format_sourced_value()

Parameters:

  • result (T) – The formatted result of ReplicableValue._explain_rec().

  • extracted_important_values (list[T]) – The extracted important values. These can be used to add a quick recap of the important results at the beginning of the explanation.

Returns:

By default, returns the result parameter as is. Can be overridden to modify the final result before ReplicableValue.explain() returns it.

Return type:

T

format_sourced_value(name: str | None, value: Quantity, min: Quantity, max: Quantity, standard_deviation: Quantity, source: str, explaination: str | None, warnings: List[str], ontology: Ontology | None, recursion_level: int, already_seen: bool, important: bool) → dict

Format a SourcedValue instance. This method must be implemented.

name

Name of the SourcedValue, if any.

Type:

str | None

value

The central value, with units.

Type:

Quantity

min

Minimum plausible value.

Type:

Quantity

max

Maximum plausible value.

Type:

Quantity

standard_deviation

Standard deviation (uncertainty) of the value.

Type:

Quantity

source

The source (quote, link, etc.) of the value.

Type:

str

warnings

List of warnings or notes about the value.

Type:

List[str]

explanation

Optional explanation or description.

Type:

str | None

ontology

Optional ontology tag for semantic annotation.

Type:

str | None

recursion_level

Recursion level is the depth of this value in the tree represented by the ReplicableValue on which we called ReplicableValue.explain().

Type:

int

already_seen

Whether the value has already been formatted in a previously traversed branch of the tree represented by the ReplicableValue on which we called ReplicableValue.explain(). The Operation._explain_rec() method uses Depth-First Search and respects the order of the Operation.operands list.

Type:

bool

important

True if the value is an important intermediate result. If true, it will be extracted and passed to format_result() in the list of extracted important values.

Type:

bool

Returns:

The formatted SourcedValue.

Return type:

T