energy_analysis_toolbox.weather.degree_days#

Provides functions for calculating degree days.

The provided functions assumes that:

  • the sampling is not regular (missing data possible)

  • the temperature is given in Celsius

  • the frequency of the data is around hourly (e.g. 1-3 hours), as the computations assume multiple temperature values during each day to compute the min, max, integral, and so on during each day.

Notation#

  • \(DD\) : Degree-days for a given day (heating or cooling)

  • \(T_{min}\) : Minimum temperature for a given day

  • \(T_{max}\) : Maximum temperature for a given day

  • \(T_{ref}\) : Reference temperature for degree-days computation

  • \(\\Delta t_i\) : Duration of the i-th timestep

  • \(T_{mean}\) : Mean temperature for a given day computed as \(\\sum_{i=1}^{N} T_i \\cdot \\Delta t_i / \\sum_{i=1}^{N} \\Delta t_i\)

  • \(N\) : Number of timesteps in a day

  • \(T_i\) : Temperature at the i-th timestep

  • \((x)^+\) : Positive part of x, i.e. \(max(x, 0)\)

  • Type of degree-days:

    • Heating : Degree-days for heating season, means that the reference temperature is higher than the outside temperature

    • Cooling : Degree-days for cooling season, means that the reference temperature is lower than the outside temperature

Examples

>>> temp = pd.Series(np.random.randn(100), index=pd.date_range("2020-01-01",
... periods=100, freq='h'))
>>> dd_compute(temp, 17, method="integral").head()
2020-01-01    17.147638
2020-01-02    17.262956
2020-01-03    16.903173
2020-01-04    17.132581
2020-01-05    16.918075
Freq: D, Name: heating_degree_days, dtype: float64

>>> dd_compute(temp, 17, method="integral", type="cooling").head()
2020-01-01    0.0
2020-01-02    0.0
2020-01-03    0.0
2020-01-04    0.0
2020-01-05    0.0
Freq: D, Name: cooling_degree_days, dtype: float64
energy_analysis_toolbox.weather.degree_days._assert_dd_type(dd_type: str) → None[source]#

Check that the degree-days type is valid.

Parameters:

dd_type (str) – the type of degree-days to compute.

Raises:

EATInvalidDegreeDaysError – If the type is not recognized, i.e. not ‘heating’ or ‘cooling’.

energy_analysis_toolbox.weather.degree_days.dd_calc_method(func: Callable) → Literal['min_max', 'mean', 'integral', 'pro', 'unknown'][source]#

Return the name of the method used for computing degree-days.

Parameters:

func (function) – The function to check.

Returns:

str – The name of the method used for computing degree-days.

energy_analysis_toolbox.weather.degree_days.dd_compute(temperature: Series, reference: float, dd_type: Literal['heating', 'cooling'], clip_tshd: float = 0, method: Literal['min_max', 'mean', 'integral', 'pro'] = 'integral', **kwargs) → Series[source]#

Return daily degree-days with the specified method.

Parameters:

  • temperature (pd.Series) – The

  • reference (float) – The reference temperature for degree-days computation.

  • dd_type ({'heating', 'cooling'}) – The type of degree-days to compute.

  • clip_tshd (float or None, optional) – A threshold under which the computed degree-days are clipped. Using 0 will return only positive DD values. The default is 0.

  • method ({'min_max', 'mean', 'integral'}, optional) – The method to use for computing the degree-days. The default is ‘integral’. - ‘min_max’ : Min-max method dd_min_max - ‘mean’ : Mean method dd_mean - ‘integral’ : Integral method dd_integral - ‘pro’ : Pro method dd_pro

  • kwargs (mapping, optional) – A dictionary of keyword arguments passed to the degree-days computation methods, such as dd_integral.

Returns:

pd.Series – The timeseries of daily degree-days for the period covered by temperature.

Raises:

EATInvalidDegreeDaysMethodError – If the method is not recognized.

See also

-

py:func:dd_min_max : Min-max method

-

py:func:dd_mean : Mean method

-

py:func:dd_integral : Integral method

-

py:func:dd_pro : Pro method

Examples

>>> temp = pd.Series(np.random.randn(100), index=pd.date_range("2020-01-01",
... periods=100, freq='h'))
>>> dd_compute(temp, 17, method="integral").head()
2020-01-01    16.968044
2020-01-02    17.147927
2020-01-03    16.837810
2020-01-04    16.877662
2020-01-05    17.453723
Freq: D, Name: heating_degree_days, dtype: float64
energy_analysis_toolbox.weather.degree_days.dd_integral(temperature: Series, reference: float, dd_type: Literal['heating', 'cooling'], clip_tshd: float = 0, intraday_clip_tshd: float = 0) → Series[source]#

Return daily degree-days with integral method.

This is the most accurate method for computing degree-days, as it takes into account the temperature variations during the day.

\[\begin{split}DD = \\frac{\\sum_{i=1}^{N} (T_{ref} - T_i)^+ \\ \\cdot \\Delta t_i}{\\sum_{i=1}^{N} \\Delta t_i}\end{split}\]
Parameters:

  • temperature (pd.Series) – The timeseries of temperature measures from which DD data has to be inferred.

  • reference (float) – The reference temperature for degree-days computation.

  • dd_type ({'heating', 'cooling'}) – The type of degree-days to compute.

  • clip_tshd (float or None, optional) – A threshold under which the computed degree-days are clipped. Using 0 will return only positive DD values. The default is 0.

  • intraday_clip_tshd (float or None, optional) – A threshold under which the instantaneous temperature differences used in degree-days computation are clipped. If None, no clipping is done, hence resulting in the same results as dd_mean. The default is 0. Using 0 will assign no heating-need (resp. cooling) to moments when the reference temperature is lower than the outside one.

Returns:

pd.Series – The timeseries of daily degree-days for the period covered by temperature.

Warning

Days without data receive nan values, while those with partial data are processed as regular ones.

Notes

About the parameter intraday_clip_tshd:

If the temperature is always below or above the reference temperature, the clipping has no effect.

If the temperature is sometimes below and sometimes above the reference temperature, The question is : does the cold temperature compensate the warm temperature? Meaning: would the user heat (resp. cool) the building if the temperature in the morning, even though it is warm in the afternoon? If the answer is yes, then the clipping should be set to 0. If the answer is no, then the clipping should be set to None.

Examples

>>> temp = pd.Series(np.random.randn(100), index=pd.date_range("2020-01-01",
... periods=100, freq='h'))
>>> dd_integral(temp, 17).head()
2020-01-01    16.666671
2020-01-02    17.109244
2020-01-03    17.087415
2020-01-04    16.976660
2020-01-05    16.337652
Freq: D, Name: heating_degree_days, dtype: float64
energy_analysis_toolbox.weather.degree_days.dd_mean(temperature: Series, reference: float, dd_type: Literal['heating', 'cooling'], clip_tshd: float = 0) → Series[source]#

Return daily degree-days with mean method.

This uses a better estimate of the daily average temperature than the min-max method of dd_min_max.

\[DD = (T_{mean} - T_{ref})^+\]
Parameters:

  • temperature (pd.Series) – The timeseries of temperature measures from which DD data has to be inferred.

  • reference (float) – The reference temperature for degree-days computation.

  • dd_type ({'heating', 'cooling'}) – The type of degree-days to compute.

  • clip_tshd (float or None, optional) – A threshold under which the computed degree-days are clipped. Using 0 will return only positive DD values. The default is 0.

Returns:

pd.Series – The timeseries of daily degree-days for the period covered by temperature.

Warning

Days without data receive nan values, while those with partial data are processed as regular ones.

Examples

>>> temp = pd.Series(np.random.randn(100), index=pd.date_range("2020-01-01",
... periods=100, freq='h'))
>>> dd_mean(temp, 17).head()
2020-01-01    16.688565
2020-01-02    17.205562
2020-01-03    16.898472
2020-01-04    16.794069
2020-01-05    16.808996
Freq: D, Name: heating_degree_days, dtype: float64
energy_analysis_toolbox.weather.degree_days.dd_min_max(temperature: Series, reference: float, dd_type: Literal['heating', 'cooling'], clip_tshd: float = 0) → Series[source]#

Return daily degree-days with min-max method.

\[\begin{split}DD = (\\frac{T_{min} + T_{max}}{2} - T_{ref})^+\end{split}\]
Parameters:

  • temperature (pd.Series) – The timeseries of temperature measures from which DD data has to be inferred.

  • reference (float) – The reference temperature for degree-days computation.

  • dd_type ({'heating', 'cooling'}) – The type of degree-days to compute.

  • clip_tshd (float or None, optional) – A threshold under which the computed degree-days are clipped. Using 0 will return only positive DD values. The default is 0.

Returns:

pd.Series – The timeseries of daily degree-days for the period covered by temperature.

Warning

Days without data receive nan values, while those with partial data are processed as regular ones.

Note

To developers

The min_count parameter of the sum method is used to return nan when one of the values (usually both) is nan. This is the desired behavior, as it avoids returning the value of reference when the data is not available.

Examples

>>> temp = pd.Series(np.random.randn(100), index=pd.date_range("2020-01-01",
... periods=100, freq='h'))
>>> dd_min_max(temp, 17).head()
2020-01-01    16.766840
2020-01-02    17.219413
2020-01-03    17.168598
2020-01-04    16.263783
2020-01-05    17.786569
Freq: D, Name: heating_degree_days, dtype: float64
energy_analysis_toolbox.weather.degree_days.dd_pro(temperature: Series, reference: float, dd_type: Literal['heating', 'cooling'], clip_tshd: float = 0) → Series[source]#

Return daily degree-days with pro method.

\[\begin{split}DD = (T_{max} - T_{ref}) * \\ (0.08 + 0.42 * \\ (T_{max} - T_{ref}) / (T_{max} - T_{min}))\end{split}\]

Use in France to estimate the degree days during the intermediate seasons, when the reference temperature is between the min and max temperature of the day.

Reference: meteo France

A small modification is made to the original formula to use the true average temperature instead of the min and max temperature mean.