Calculation Requirement¶

Overview¶

The CalculationRequirement class is an abstract base class that defines the interface for all calculation requirements. It is designed to retrieve all necessary data for a calculation, ensuring that the data exists in the database. It does not validate the correctness of the data, only its existence.

Usage¶

The calculation requirements will be used throughout all feature calculations with some variations, but as a general rule, this is what is done:

Instantiate the requirement with the necessary arguments.
Check if the requirement is met with the check method.
Get the data with the get_data method.
Use the data to calculate the feature by getting it from the data attribute of the requirement.

Subclass implementation¶

Subclasses of CalculationRequirement must implement the following methods:

__init__: The constructor of the class. It should override the constructor of the superclass, adding any necessary arguments for the specific requirement. Regardless of that, the constructor should always call the superclass constructor with the super().__init__(optional) method in the first line to make sure the superclass is correctly initialized.
__repr__: This method should return a string representation of the requirement. This is useful for debugging and logging purposes.
check: This method should check if the data required for the calculation is available in the database. It should return a boolean value indicating if the requirement is met or not and also should set self._checked to True to indicate that the requirement has been checked. In case the requirement is not met, the method should raise a ValueError with a message explaining the issue. It's important to note that in most cases this should not get the data, but only check if it exists (for example, if the requirement is a feature, we check if it exists for the desired object but we dont need to get the values of the feature as this will be done by the get_data method).
get_data: This method should return the data required for the calculation. It should only run if the requirement has been checked and the check has passed. After actually getting the data, it should set self._data to the data retrieved and return it.

For examples on how to implement a subclass of CalculationRequirement, please go to the next sections of this documentation.

Class Definition¶

`CalculationRequirement(optional=False)` ¶

Abstract class for all calculation requirements.

The subclasses of CalculationRequirement will get all the necessary data for a calculation, checking if they exists in the database and in some cases, also if they are valid.

In subclasses this constructor should be called with super().init(optional=optional).

Parameters:

optional ¶
(bool, default: False ) –

Defines if the requirement is optional. If optional is True, the requirement is only validated to check if it could exist, not if it is actually present. By default False

Source code in echo_energycalc/calculation_requirements_core.py

def __init__(self, optional: bool = False) -> None:
    """
    Constructor of the CalculationRequirement class.

    The subclasses of CalculationRequirement will get all the necessary data for a calculation, checking if they exists in the database and in some cases, also if they are valid.

    In subclasses this constructor should be called with super().__init__(optional=optional).

    Parameters
    ----------
    optional : bool, optional
        Defines if the requirement is optional.
        If optional is True, the requirement is only validated to check if it could exist, not if it is actually present.
        By default False
    """
    # attribute used to store the connection to performance database
    self._perfdb = PerfDB(application_name=self.__class__.__name__)

    # attribute used to store the connection to bazefield database
    self._baze = Baze(application_name=self.__class__.__name__)

    # attribute that defines if the requirement is optional
    self._optional: bool = optional

    # attribute used to check if the requirement has been checked
    self._checked: bool = False

    # attribute used to store the data required for the calculation
    self._data: Any | None = None

`checked` `property` ¶

Attribute that defines if the requirement has been checked. It's value will start as False and will be set to True after the check method is called.

Returns:

bool –

True if the requirement has been checked.

`data` `property` ¶

Attribute used to store the data required for the calculation.

Initially it is None and will be set with the data acquired by the get_data method. The data type will depend on the subclass implementation, but usually it will be a pandas DataFrame or a dictionary.

Returns:

Any | None –

Returns the data required for the calculation.

`optional` `property` ¶

Attribute that defines if the requirement is optional.

If optional is True, the requirement is only validated to check if it could exist, not if it is actually present. This is useful for requirements that are not necessary for all calculations, but are useful for some of them.

Returns:

bool –

True if the requirement is optional.

`check()` `abstractmethod` ¶

Method used to check if the requirement is met. In other words, this method should check if the data required for the calculation is available in the database or any other source.

The method should raise an error if the requirement is not met and the calculation cannot be performed or return True if the requirement is met.

At the end of the method, the attribute self._checked should be set to True.

Returns:

bool –

Returns True if the requirement is met.

Source code in echo_energycalc/calculation_requirements_core.py

@abstractmethod
def check(self) -> bool:
    """
    Method used to check if the requirement is met. In other words, this method should check if the data required for the calculation is available in the database or any other source.

    The method should raise an error if the requirement is not met and the calculation cannot be performed or return True if the requirement is met.

    At the end of the method, the attribute self._checked should be set to True.

    Returns
    -------
    bool
        Returns True if the requirement is met.
    """
    raise NotImplementedError("This method must be implemented by a subclass")

`get_data(**kwargs)` `abstractmethod` ¶

Method used to get the data required for the calculation.

The method should first check if the requirement has been checked. If not, it should check before getting the data.

At the end of the method, the attribute self._data should be set with the data queried from performance_db or any other source.

Returns:

Any –

Returns the data required for the calculation.

Source code in echo_energycalc/calculation_requirements_core.py

@abstractmethod
def get_data(self, **kwargs) -> Any:
    """
    Method used to get the data required for the calculation.

    The method should first check if the requirement has been checked. If not, it should check before getting the data.

    At the end of the method, the attribute self._data should be set with the data queried from performance_db or any other source.

    Returns
    -------
    Any
        Returns the data required for the calculation.
    """
    raise NotImplementedError("This method must be implemented by a subclass")

Calculation Requirement¶

Overview¶

Usage¶

Subclass implementation¶

Class Definition¶

CalculationRequirement(optional=False) ¶

optional ¶

checked property ¶

data property ¶

optional property ¶

check() abstractmethod ¶

get_data(**kwargs) abstractmethod ¶

`CalculationRequirement(optional=False)` ¶

`optional` ¶

`checked` `property` ¶

`data` `property` ¶

`optional` `property` ¶

`check()` `abstractmethod` ¶

`get_data(**kwargs)` `abstractmethod` ¶