energy_analysis_toolbox.synthetic.thermosensitive_consumption#

Classes generating synthetic energy data using a thermo-sensitive model.

class energy_analysis_toolbox.synthetic.thermosensitive_consumption.CategorySynthTSConsumption(parameters: list[TSParameters], t_ref_heat: float, t_ref_cool: float, list_categories: list, category_func: Callable, noise_seed: int = 42, temperature_amplitude_year: float = 9.36, temperature_period_year: float = 0.017214630791388245, temperature_phase_year: int = 13)[source]#

Bases: DateSynthTSConsumption

Generates synthetic energy consumption with temperature-based categorization.

A class to generate fake energy consumptions as a function of the temperature. Based on DateSynthTSConsumption, including both heating and cooling domains.

Add the possibility to generate different categories of energy consumption with a function that categorize the periods.

Note

The categories are labeled by a function. The base temperatures (t_ref_heat and t_ref_cool) are the same for all categories.

For an example, see the WeekEndSynthTSConsumption class that implement the concept of week-end and week days.

fake_energy(dd_heating: Series, dd_cooling: Series, t_samples: Series) → DataFrame[source]#

Return fake energy consumption based on input daily temperatures.

Parameters:

dd_heating (pd.Series) – A series of DD. Usually daily aggregates, depending on the scale chosen for the thermosensitivity and base consumption values.
dd_cooling (pd.Series) – A series of DD. Usually daily aggregates, depending on the scale chosen for the thermosensitivity and base consumption values.
t_samples (pd.Series) – A time series of daily temperatures sampled from a Gaussian distribution, representing the temperature values (in °C) for the specified date range.

Returns:

pd.DataFrame – A table with rows labeled by dd_samples index and the following columns :

T : the t_samples series.
energy : the energy consumption for each row in the table.
thermosensitive : the value of the thermosensitive energy consumption for each period.
base : the value of the averaged non-thermosensitive consumption. This value is constant across the table, equal to self.base_energy.
residual : the energy-noise, i.e. the residual between the affine model and the actual energy for each period.

Notes

The fake energy generation relies on two instances of SynthDDConsumption, each one being associated with one of the heating and cooling temperature domains which bounds are defined by self.t_ref_heat and self.t_ref_cool, leading to an energy which is assumed to be affine per part depending on the temperature:

with slope -self.ts_heat in the heating domain (colder than self.t_ref_heat);
with slope self.ts_cool in the cool domain (warmer than self.t_ref_cool);
with slope 0 and constant value self.base_energy between self.t_ref_heat and self.t_ref_cool.

See SynthTSConsumption for more details.

Example

>>> synth_consumption = SynthTSConsumption(base_energy=100, ts_heat=2,
    ts_cool=0.2)
>>> dds_cool = pd.Series(data=[0,2,12])
>>> dds_heat = pd.Series(data=[52,1,0])
>>> t_samples = pd.Series(data=[10, 15, 20])
>>> synth_consumption.fake_energy(dds_heat, dds_cool, t_samples)
base  thermosensitive  residual  energy  heating  cooling   T  DD_heating             DD_cooling
0   100            104.0       0.0   204.0      104      0.0  10           52             0
1   100              2.4       0.0   102.4        2      0.4  15            1             2
2   100              2.4       0.0   102.4        0      2.4  20            0             12

class energy_analysis_toolbox.synthetic.thermosensitive_consumption.DateSynthTSConsumption(base_energy: float, ts_heat: float, ts_cool: float, t_ref_heat: float = 17, t_ref_cool: float = 20, noise_std: float = 0, noise_seed: int = 42, temperature_amplitude_year: float = 9.36, temperature_period_year: float = 0.017214630791388245, temperature_phase_year: int = 13)[source]#

Bases: SynthTSConsumption

Generates synthetic energy data based on date-driven temperature variations.

A class to generate fake energy consumptions as a function of the temperature. Based on SynthTSConsumption, including both heating and cooling domains.

The generation relies on the assumption of linear DD dependencies in the heating and cooling domains.

This class extends the SynthTSConsumption to generate a realistic temperature as function of the date.

random_dds(t_mean: float = 15, t_std: float = 5, size: int = 100, start: str | Timestamp = '2022-11-01', end: str | Timestamp | None = None) → DataFrame[source]#

Return realistic DD samples.

Parameters:

t_mean (float, default 15) – The average of the gaussian temperature distribution.
t_std (float, optional) – The standard deviation of the gaussian noise added to the temperature base. Default is 5.
size (int, optional) – The number of samples to generate. Default is 100.
start (pd.Timestamp or alike, optional) – The first date of the generated time-series. Default is “2022-11-01”.
end (pd.Timestamp or alike, optional) – The last date of the generated time-series. Default is None.

Returns:

pd.DataFrame – A DataFrame with the following columns : - DD_heating : the heating DD values. - DD_cooling : the cooling DD values. - T : the temperature.

Notes

The DDs are computed using the mean temperature of the day as

\[\begin{split}DD = \\max(0, T_{mean} - T_{ref})\end{split}\]

Hence, it is really just the same as the mean temperature of the day.

From the 3 parameter size, start and end, only two must be given.

Example

>>> synth_consumption = DateTimeSynthTSConsumption(base_energy=100, ts_heat=2,
    ts_cool=0.2)
>>> synth_consumption.random_dds(size=5, t_std=25)
            DD_heating  DD_cooling          T
2022-11-01     0.000000     0.000000  19.281473
2022-11-02    31.491731     0.000000 -14.491731
2022-11-03     0.000000    10.114216  30.114216
2022-11-04     0.000000    14.712902  34.712902
2022-11-05    54.730417     0.000000 -37.730417

synthetic_temperature(t_mean: float = 14, t_std: float = 5, size: int = 100, start: Timestamp | str = '2022-11-01', end: str | Timestamp | None = None) → Series[source]#

Return a synthetic temperature time-series.

Note

The temperature is generated using a sinusoidal model with a gaussian noise added. The parameters of the sinusoidal model are the class attributes.

The noise model should be improved in the future, as the temperature fluctuations present actually several frequencies.

Parameters:

t_mean (float, default 15) – The average of the gaussian temperature distribution.
t_std (float) – The standard deviation of the gaussian noise added to the temperature base.
size (int, optional) – The number of samples to generate. Default is 100.
start (pd.Timestamp or alike, optional) – The first date of the generated time-series. Default is “2022-11-01”.
end (pd.Timestamp or alike, optional) – The last date of the generated time-series. Default is None.

Returns:

pd.Series – A time-series of synthetic temperatures.

Example

>>> synth_consumption = DateTimeSynthTSConsumption(base_energy=100, ts_heat=2,
    ts_cool=0.2)
>>> synth_consumption.synthetic_temperature(size=5)
2022-11-01    13.187131
2022-11-02     6.307951
2022-11-03    15.105192
2022-11-04    15.901608
2022-11-05     1.290287
Freq: D, Name: T(°C), dtype: float64

Notes

From the 3 parameters size, start and end, only two must be given.

class energy_analysis_toolbox.synthetic.thermosensitive_consumption.SynthDDConsumption(base_energy: float, ts_slope: float, noise_std: float, noise_seed: int = 42, exp_scale_dd: float = 3.0, *, clip_negative: bool = True)[source]#

Bases: object

Class to generate synthetic thermosensitive energy consumption data.

The generated consumption is split into a base, a thermosensitive and a residual contributions.

Note

Only one DD can be used at a time to generate the energy consumption. For multiple DDs, use the FakeTSConsumption class.

Example:#

>>> synth_consumption = SynthDDConsumption(base_energy=100, ts_slope=0.1,
    noise_std=5)
>>> synth_consumption.random_consumption(size=5)
                 DD  base  thermosensitive  residual      energy
2022-11-01  7.212626   100         0.721263 -6.510898   94.210365
2022-11-02  7.008569   100         0.700857  0.639202  101.340059
2022-11-03  7.154283   100         0.715428 -1.581213   99.134215
2022-11-04  0.839383   100         0.083938 -0.084006   99.999932
2022-11-05  0.259312   100         0.025931 -4.265220   95.760712

fake_energy(dd_samples: Series) → DataFrame[source]#

Return a fake energy consumption for each day in the DD samples.

Parameters:

dd_samples (pd.Series) – A timeseries of DDs to be used to infer the energy consumption.

Returns:

pd.DataFrame – A table with rows labeled by dd_samples index and the following columns :

DD: the dd_samples series.
energy: the energy consumption for each raw in the table.
thermosensitive: the value of the thermosensitive energy consumption for each period.
base: the value of the averaged non-thermosensitive consumption. This value is constant across the table, equal to self.base_energy.
residual: the energy-noise, i.e. the residual between the affine model and the actual energy for each period.

Notes

The energy is generated assuming that the energy consumption satisfies the following equation:

\[\begin{split}E = \\Theta. DD + E_{base} + \\epsilon\end{split}\]

Where \(\\epsilon\) is a gaussian, centered, random variable, which standard deviation is self.noise_std.

Example

>>> synth_consumption = SynthDDConsumption(base_energy=100, ts_slope=2,
    noise_std=5)
>>> dds = pd.Series(data=[0,2,12])
>>> synth_consumption.fake_energy(dds)
   DD  base  thermosensitive  residual      energy
0    0   100                0  1.523585  101.523585
1    2   100                4 -5.199921   98.800079
2   12   100               24  3.752256  127.752256

measures(*args, **kwargs) → DataFrame[source]#

Return a fake energy consumption decomposition VS temperature.

This method is a wrapper around random_consumption to keep the same signature as the Handlers.

See random_consumption

random_consumption(size: int = 100, start: Timestamp | str = '2022-11-01') → DataFrame[source]#

Return a random decomposed energy consumption.

Parameters:

size (int, default : 100) – Number of days in the sample.
start (pd.Timestamp or alike, optional) – First day in the generated sample.

Returns:

pd.DataFrame – The table of fake consumption, as described in fake_energy.

Warning

The date provided in the sample is not consistent with the DD values. Still, the distribution of the DDs remain correct when using large enough number of samples.

Example

>>> synth_consumption = SynthDDConsumption(base_energy=100, ts_slope=2,
    noise_std=5)
>>> synth_consumption.random_consumption(size=5)
                 DD  base  thermosensitive  residual      energy
2022-11-01  7.212626   100        14.425252 -6.510898  107.914354
2022-11-02  7.008569   100        14.017138  0.639202  114.656340
2022-11-03  7.154283   100        14.308566 -1.581213  112.727353
2022-11-04  0.839383   100         1.678766 -0.084006  101.594760
2022-11-05  0.259312   100         0.518624 -4.265220   96.253405

random_dds(size: int = 100, start: Timestamp | str = '2022-11-01') → Series[source]#

Return realistic DD samples.

Parameters:

size (int, default : 100) – Number of days in the sample.
start (pd.Timestamp or alike, optional) – First day in the generated sample.

Returns:

pd.Series – A time-series with 1 day period containing randomly generated DD values.
.. warning:: – The date provided in the sample is not consistent with the DD values. Still, the distribution of the DDs remain correct when using large enough number of samples.

Notes

The samples are drawn from an exponential law.

Example

>>> synth_consumption = SynthDDConsumption(base_energy=100, ts_slope=0.1,
    noise_std=5)
>>> synth_consumption.random_dds(size=5)
2022-11-01    7.212626
2022-11-02    7.008569
2022-11-03    7.154283
2022-11-04    0.839383
2022-11-05    0.259312
Freq: D, Name: DD, dtype: float64

class energy_analysis_toolbox.synthetic.thermosensitive_consumption.SynthTSConsumption(base_energy: float, ts_heat: float, ts_cool: float, t_ref_heat: float = 17, t_ref_cool: float = 20, noise_std: float = 0, noise_seed: int = 42)[source]#

Bases: object

Generates synthetic energy consumption with linear degree-day dependencies.

A class to generate fake energy consumptions as a function of the temperature. Based on FakeDDConsumption, including both heating and cooling domains.

The generation relies on the assumption of linear DD dependencies in the heating and cooling domains.

Example:#

>>> synth_consumption = SynthTSConsumption(base_energy=100, ts_heat=2, ts_cool=3,
...     noise_std=5)
>>> synth_consumption.random_consumption(size=5, t_mean=20, t_std=20)
            base  thermosensitive  residual      energy    heating            cooling          T  DD_heating  DD_cooling
    2022-11-01   100        18.283025 -6.510898  111.772127   0.000000          18.283025  26.094342     0.000000     6.094342
    2022-11-02   100        35.599364  0.639202  136.238566  35.599364           0.000000  -0.799682    17.799682     0.000000
    2022-11-03   100        45.027072 -1.581213  143.445859   0.000000          45.027072  35.009024     0.000000    15.009024
    2022-11-04   100        56.433883 -0.084006  156.349877   0.000000          56.433883  38.811294     0.000000    18.811294
    2022-11-05   100        72.041408 -4.265220  167.776188  72.041408           0.000000 -19.020704    36.020704     0.000000

fake_energy(dd_heating: Series, dd_cooling: Series, t_samples: Series) → DataFrame[source]#

Return fake energy data depending on input daily temperatures.

Parameters:

dd_heating (pd.Series) – A series of DD. Usually daily aggregates, depending on the scale chosen for the thermosensitivity and base consumption values.
dd_cooling (pd.Series) – A series of DD. Usually daily aggregates, depending on the scale chosen for the thermosensitivity and base consumption values.
t_samples (pd.Series) – A time series of daily temperatures sampled from a Gaussian distribution, representing the temperature values (in °C) for the specified date range.

Returns:

pd.DataFrame – A table with rows labeled by dd_samples index and the following columns :

T : the t_samples series.
energy : the energy consumption for each raw in the table.
thermosensitive : the value of the thermosensitive energy consumption for each period.
base : the value of the averaged non-thermosensitive consumption. This value is constant across the table, equal to self.base_energy.
residual : the energy-noise, i.e. the residual between the affine model and the actual energy for each period.

Notes

The fake energy generation relies on two instances of SynthDDConsumption, each one being associated with one of the heating and cooling temperature domains which bounds are defined by self.t_ref_heat and self.t_ref_cool, leading to an energy which is assumed to be affine per part depending on the temperature:

with slope -self.ts_heat in the heating domain (colder than self.t_ref_heat.);
with slope self.ts_cool in the cool domain (warmer than self.t_ref_cool.);
with slope 0 and constant value self.base_energy between self.t_ref_heat and self.t_ref_cool.

Example

>>> synth_consumption = SynthTSConsumption(base_energy=100, ts_heat=2,
    ts_cool=0.2)
>>> dds_cool = pd.Series(data=[0,2,12])
>>> dds_heat = pd.Series(data=[52,1,0])
>>> t_samples = pd.Series(data=[10, 15, 20])
>>> synth_consumption.fake_energy(dds_heat, dds_cool, t_samples)
   base  thermosensitive  residual  energy  heating  cooling   T  DD_heating                 DD_cooling
0   100            104.0       0.0   204.0      104      0.0  10           52             0
1   100              2.4       0.0   102.4        2      0.4  15            1             2
2   100              2.4       0.0   102.4        0      2.4  20            0             12

measures(*args, **kwargs) → DataFrame[source]#

Return a fake energy consumption decomposition VS temperature.

This method is a wrapper around random_consumption to keep the same signature as the Handlers.

random_consumption(size: int = 100, t_mean: float = 15, t_std: float = 5, start: Timestamp | str = '2022-11-01', end: str | Timestamp | None = None) → DataFrame[source]#

Return a fake energy consumption decomposition VS temperature.

The input temperatures are generated using a gaussian distribution.

Parameters:

size (int, optional) – The number of samples to generate. Default is 100.
t_mean (float, default 15) – The average of the gaussian temperature distribution.
t_std (float, default 5) – The std if the gaussian temperature distribution.
start (pd.Timestamp or alike, optional) – The first date of the generated time-series. Default is “2022-11-01”.
end (pd.Timestamp or alike, optional) – The last date of the generated time-series. Default is None.

Returns:

pd.DataFrame – A table of randomly generated energy consumption as a function of the temperature. See fake_energy.

random_dds(t_mean: float = 15, t_std: float = 5, size: int = 100, start: str | Timestamp = '2022-11-01', end: str | Timestamp | None = None) → DataFrame[source]#

Return realistic DD samples.

Parameters:

t_mean (float, default 15) – The average of the gaussian temperature distribution.
t_std (float, default 5) – The std if the gaussian temperature distribution.
size (int, optional) – The number of samples to generate. Default is 100.
start (pd.Timestamp or alike, optional) – The first date of the generated time-series. Default is “2022-11-01”.
end (pd.Timestamp or alike, optional) – The last date of the generated time-series. Default is None.

Returns:

pd.DataFrame – A dataframe with 1-day period containing randomly generated DD values.
.. warning:: – The date provided in the sample is not consistent with the DD values (think winter in July!) Still, the distribution of the DDs remain correct when using large enough number of samples.

Notes

The daily mean temperature is drawn from a Normal distribution. The DD uses the mean method to compute the DD values.

Example

>>> synth_consumption = SynthTSConsumption(base_energy=100, ts_heat=2,
    ts_cool=0.2)
>>> synth_consumption.random_dds(size=5, t_mean=20, t_std=20)
            DD_heating  DD_cooling          T
2022-11-01     0.000000     6.094342  26.094342
2022-11-02    17.799682     0.000000  -0.799682
2022-11-03     0.000000    15.009024  35.009024
2022-11-04     0.000000    18.811294  38.811294
2022-11-05    36.020704     0.000000 -19.020704

class energy_analysis_toolbox.synthetic.thermosensitive_consumption.TSParameters[source]#

Bases: TypedDict

TypedDict for specifying thermosensitive model parameters.

The TSParameters class defines the structure of parameters used to generate synthetic energy data with a thermo-sensitive model. It includes fields for base energy consumption and thermosensitivity in both heating and cooling domains, as well as noise standard deviation.

base_energy#

The base energy consumption that is independent of temperature variations.

Type:: float

ts_heat#

The slope that represents how much the energy consumption increases per degree day below the reference heating temperature (thermosensitivity for heating).

Type:: float

ts_cool#

The slope that represents how much the energy consumption increases per degree day above the reference cooling temperature (thermosensitivity for cooling).

Type:: float

noise_std#

The standard deviation of the Gaussian noise added to simulate randomness in the energy consumption.

Type:: float

class energy_analysis_toolbox.synthetic.thermosensitive_consumption.WeekEndSynthTSConsumption(parameters: list[TSParameters], t_ref_heat: float, t_ref_cool: float, noise_seed: int = 42, temperature_amplitude_year: float = 9.36, temperature_period_year: float = 0.017214630791388245, temperature_phase_year: int = 13)[source]#

Bases: CategorySynthTSConsumption

Generates synthetic energy consumption categorized by weekdays and weekends.

A class to generate fake energy consumptions as a function of the temperature with two categories: week days and weekends.

Based on CategorySynthTSConsumption.