TextFormatter#

class impacthpc.src.core.TextFormatter(uncertainty_format: UncertaintyFormat = UncertaintyFormat.STANDARD_DEVIATION)#

Bases: Formatter[str, str]

Methods Summary

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_operation(formula: str, name: str | None, value: Quantity, min: Quantity, max: Quantity, standard_deviation: Quantity, operator: str, operands: list[str], isInfix: bool, explaination: str | None, warnings: List[str], ontology: Ontology | None, recursion_level: int, already_seen: bool, important: bool) → str#

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: str, extracted_important_values: list[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) → str#

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) → str#

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[str], isInfix: bool, explaination: str | None, warnings: List[str], ontology: Ontology | None, recursion_level: int, already_seen: bool, important: bool) → str#

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: str, extracted_important_values: list[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) → str#

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