Skip to content

Model input and output schemas

Modules:

Name Description
input_profile
output_profile

Classes:

Name Description
InputProfile

Class containing the temperature and load profiles for the thermal model Model().
OutputProfile

Class containing the output data for the hot-spot and top-oil temperature calculations.

InputProfile

Bases: BaseModel

Class containing the temperature and load profiles for the thermal model Model().

This class is also capable of converting the results to a single dataframe with the timestamp as the index for convenience.

Attributes:

Name Type Description
datetime_index NDArray[datetime64]

The datetime index for the profiles.
load_profile NDArray[float64]

The load profile for the transformer.
ambient_temperature_profile NDArray[float64]

The ambient temperature profile for the transformer.

Methods:

Name Description
create

Create an InputProfile from datetime index, load profile, and ambient temperature profile.
from_dataframe

Create an InputProfile from a dataframe.

create classmethod 

create(
    datetime_index: Collection[datetime],
    load_profile: Collection[float],
    ambient_temperature_profile: Collection[float],
) -> Self

Create an InputProfile from datetime index, load profile, and ambient temperature profile.

Parameters:

Name Type Description Default
datetime_index Collection[datetime]

The datetime index for the profiles.

 required
load_profile Collection[float]

The load profile for the transformer.

 required
ambient_temperature_profile Collection[float]

The ambient temperature profile for the transformer.

 required

Returns:

Type Description
Self

An InputProfile object.
Creating an InputProfile from collections. 
>>> from datetime import datetime
>>> from transformer_thermal_model.schemas import InputProfile

>>> datetime_index = [
...     datetime(2023, 1, 1, 0, 0),
...     datetime(2023, 1, 1, 1, 0),
...     datetime(2023, 1, 1, 2, 0),
... ]
>>> load_profile = [0.8, 0.9, 1.0]
>>> ambient_temperature_profile = [25.0, 24.5, 24.0]
>>> input_profile = InputProfile.create(
...     datetime_index=datetime_index,
...     load_profile=load_profile,
...     ambient_temperature_profile=ambient_temperature_profile,
... )
>>> input_profile
InputProfile(datetime_index=array(['2023-01-01T00:00:00.000000',
'2023-01-01T01:00:00.000000', '2023-01-01T02:00:00.000000'],
dtype='datetime64[us]'), load_profile=array([0.8, 0.9, 1. ]),
ambient_temperature_profile=array([25. , 24.5, 24. ]))
Directly creating an InputProfile object using numpy arrays. 
>>> import numpy as np
>>> from datetime import datetime
>>> from transformer_thermal_model.schemas import InputProfile

>>> input_profile = InputProfile(
...     datetime_index=np.array(
...         [
...             datetime(2023, 1, 1, 0, 0),
...             datetime(2023, 1, 1, 1, 0),
...             datetime(2023, 1, 1, 2, 0)
...         ],
...         dtype=np.datetime64,
...     ),
...     load_profile=np.array([0.8, 0.9, 1.0], dtype=float),
...     ambient_temperature_profile=np.array([25.0, 24.5, 24.0], dtype=float),
... )
>>> input_profile
InputProfile(datetime_index=array(['2023-01-01T00:00:00.000000',
'2023-01-01T01:00:00.000000', '2023-01-01T02:00:00.000000'],
dtype='datetime64[us]'), load_profile=array([0.8, 0.9, 1. ]),
ambient_temperature_profile=array([25. , 24.5, 24. ]))
Source code in transformer_thermal_model/schemas/thermal_model/input_profile.py 
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
@classmethod
def create(
    cls,
    datetime_index: Collection[datetime],
    load_profile: Collection[float],
    ambient_temperature_profile: Collection[float],
) -> Self:
    """Create an InputProfile from datetime index, load profile, and ambient temperature profile.

    Args:
        datetime_index: The datetime index for the profiles.
        load_profile: The load profile for the transformer.
        ambient_temperature_profile: The ambient temperature profile for the transformer.

    Returns:
        An InputProfile object.

    Example: Creating an InputProfile from collections.
        ```python
        >>> from datetime import datetime
        >>> from transformer_thermal_model.schemas import InputProfile

        >>> datetime_index = [
        ...     datetime(2023, 1, 1, 0, 0),
        ...     datetime(2023, 1, 1, 1, 0),
        ...     datetime(2023, 1, 1, 2, 0),
        ... ]
        >>> load_profile = [0.8, 0.9, 1.0]
        >>> ambient_temperature_profile = [25.0, 24.5, 24.0]
        >>> input_profile = InputProfile.create(
        ...     datetime_index=datetime_index,
        ...     load_profile=load_profile,
        ...     ambient_temperature_profile=ambient_temperature_profile,
        ... )
        >>> input_profile
        InputProfile(datetime_index=array(['2023-01-01T00:00:00.000000',
        '2023-01-01T01:00:00.000000', '2023-01-01T02:00:00.000000'],
        dtype='datetime64[us]'), load_profile=array([0.8, 0.9, 1. ]),
        ambient_temperature_profile=array([25. , 24.5, 24. ]))

        ```

    Example: Directly creating an InputProfile object using numpy arrays.
        ```python
        >>> import numpy as np
        >>> from datetime import datetime
        >>> from transformer_thermal_model.schemas import InputProfile

        >>> input_profile = InputProfile(
        ...     datetime_index=np.array(
        ...         [
        ...             datetime(2023, 1, 1, 0, 0),
        ...             datetime(2023, 1, 1, 1, 0),
        ...             datetime(2023, 1, 1, 2, 0)
        ...         ],
        ...         dtype=np.datetime64,
        ...     ),
        ...     load_profile=np.array([0.8, 0.9, 1.0], dtype=float),
        ...     ambient_temperature_profile=np.array([25.0, 24.5, 24.0], dtype=float),
        ... )
        >>> input_profile
        InputProfile(datetime_index=array(['2023-01-01T00:00:00.000000',
        '2023-01-01T01:00:00.000000', '2023-01-01T02:00:00.000000'],
        dtype='datetime64[us]'), load_profile=array([0.8, 0.9, 1. ]),
        ambient_temperature_profile=array([25. , 24.5, 24. ]))

        ```
    """
    return cls(
        datetime_index=np.array(datetime_index, dtype=np.datetime64),
        load_profile=np.array(load_profile, dtype=float),
        ambient_temperature_profile=np.array(ambient_temperature_profile, dtype=float),
    )

from_dataframe classmethod 

from_dataframe(df: DataFrame) -> Self

Create an InputProfile from a dataframe.

Parameters:

Name Type Description Default
df DataFrame

The dataframe containing the profiles. The dataframe should have a datetime index and three columns: - 'datetime_index': The datetime index for the profiles. - 'load_profile': The load profile for the transformer. - 'ambient_temperature_profile': The ambient temperature profile for the transformer.

 required

Returns:

Type Description
Self

An InputProfile object.
Source code in transformer_thermal_model/schemas/thermal_model/input_profile.py 
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
@classmethod
def from_dataframe(cls, df: pd.DataFrame) -> Self:
    """Create an InputProfile from a dataframe.

    Args:
        df: The dataframe containing the profiles. The dataframe should have a datetime index and three columns:
            - 'datetime_index': The datetime index for the profiles.
            - 'load_profile': The load profile for the transformer.
            - 'ambient_temperature_profile': The ambient temperature profile for the transformer.

    Returns:
        An InputProfile object.
    """
    required_columns = {"datetime_index", "load_profile", "ambient_temperature_profile"}
    missing_columns = required_columns - set(df.columns)
    if missing_columns:
        raise ValueError(f"The dataframe is missing the following required columns: {', '.join(missing_columns)}")

    return cls(
        datetime_index=df["datetime_index"].to_numpy(),
        load_profile=df["load_profile"].to_numpy(),
        ambient_temperature_profile=df["ambient_temperature_profile"].to_numpy(),
    )

OutputProfile

Bases: BaseModel

Class containing the output data for the hot-spot and top-oil temperature calculations.

The class consists of the top-oil and hot-spot temperature profiles. These have the datetime index as the timestamp that link both of these series together.

Additionally, this class has a helper function to convert the output to a single dataframe for convenience.

Methods:

Name Description
convert_to_dataframe

Process the two pandas Series and convert them to a single dataframe, linked by the timestamp.

convert_to_dataframe 

convert_to_dataframe() -> DataFrame

Process the two pandas Series and convert them to a single dataframe, linked by the timestamp.

Source code in transformer_thermal_model/schemas/thermal_model/output_profile.py 
21
22
23
24
25
26
27
28
29
30
def convert_to_dataframe(self) -> pd.DataFrame:
    """Process the two pandas Series and convert them to a single dataframe, linked by the timestamp."""
    df = pd.DataFrame(
        {
            "timestamp": self.top_oil_temp_profile.index,
            "top_oil_temperature": self.top_oil_temp_profile,
            "hot_spot_temperature": self.hot_spot_temp_profile,
        }
    )
    return df