solph._helpers

Complexity

Total Complexity

14

Size/Duplication

Total Lines	144
Duplicated Lines	0 %

Importance

Changes

0

3 Functions

Rating	Name	Duplication	Size	Complexity
A	warn_if_missing_attribute()	0	10	1
A	check_node_object_for_missing_attribute()	0	12	2
C	create_time_index()	0	91	11

# -*- coding: utf-8 -*-

"""
Private helper functions.

SPDX-FileCopyrightText: Uwe Krien <krien@uni-bremen.de>
SPDX-FileCopyrightText: Simon Hilpert
SPDX-FileCopyrightText: Cord Kaldemeyer
SPDX-FileCopyrightText: Stephan Günther
SPDX-FileCopyrightText: Birgit Schachler
SPDX-FileCopyrightText: David Fuhrländer
SPDX-FileCopyrightText: Johannes Röder

SPDX-License-Identifier: MIT

"""

import calendar
import datetime
from warnings import warn

import pandas as pd
from oemof.tools import debugging


def check_node_object_for_missing_attribute(obj, attribute):
    """Raises a predefined warning if object does not have attribute.

    Arguments
    ---------

    obj : python object
    attribute : (string) name of the attribute to test for

    """
    if not getattr(obj, attribute):
        warn_if_missing_attribute(obj, attribute)


def warn_if_missing_attribute(obj, attribute):
    """Raises warning if attribute is missing for given object"""
    msg = (
        "Attribute <{0}> is missing in Node <{1}> of {2}.\n"
        "If this is intended and you know what you are doing you can"
        "disable the SuspiciousUsageWarning globally."
    )
    warn(
        msg.format(attribute, obj.label, type(obj)),
        debugging.SuspiciousUsageWarning,
    )


def create_time_index(
    year: int = None,
    interval_length: float = None,
    number_of_intervals: int = None,
    start: datetime.date = None,
    number: int = None,
    interval: float = None,
):
    """
    Create a datetime index for one year.

    Notes
    -----
    To create 8760 hourly intervals for a non leap year a datetime index with
    8761 time points need to be created. So the number of time steps is always
    the number of intervals plus one.

    Parameters
    ----------
    year : int, datetime
        The year of the index.
        Used to automatically set start and number for the specific year.
    interval_length : float
        The length time interval in hours e.g. 0.5 for 30min or 2 for a
        two hour interval (default: 1).
    number_of_intervals : int
        The number of time intervals. By default number is calculated to create
        an index of one year. For a shorter or longer period the number of
        intervals can be set by the user.
    start : datetime.datetime or datetime.date
        Optional start time. If start is not set, 00:00 of the first day of
        the given year is the start time.

    Examples
    --------
    >>> len(create_time_index(2014))
    8761
    >>> len(create_time_index(2012))  # leap year
    8785
    >>> len(create_time_index(2014, interval=0.5))
    17521
    >>> len(create_time_index(2014, interval=0.5, number=10))
    11
    >>> len(create_time_index(2014, number=10))
    11
    >>> str(create_time_index(2014, interval=0.5, number=10)[-1])
    '2014-01-01 05:00:00'
    >>> str(create_time_index(2014, interval=2, number=10)[-1])
    '2014-01-01 20:00:00'
    """
    if number is not None:
        warnig_text = "The argument 'number_of_intervals' repleaces 'number'."
        if number_of_intervals is None:
            warn(warnig_text)
            number_of_intervals = number
        else:
            raise AttributeError(warnig_text + " You cannot set both!")

    if interval is not None:
        warnig_text = "The argument 'interval_length' repleaces 'interval'."
        if interval_length is None:
            warn(warnig_text)
            interval_length = interval
        else:
            raise AttributeError(warnig_text + " You cannot set both!")
    if interval_length is None:
        interval_length = 1

    if number_of_intervals is None:
        if calendar.isleap(year):
            hours_in_year = 8784
        else:
            hours_in_year = 8760
        number_of_intervals = round(hours_in_year / interval_length)
    if start is not None:
        if year is not None:
            raise ValueError(
                "Arguments 'start' and 'year' are mutually exclusive."
            )
    else:
        start = f"1/1/{year}"
    try:
        time_index = pd.date_range(
            start, periods=number_of_intervals + 1, freq=f"{interval_length}h"
        )
    except ValueError:
        # Pandas <2.2 compatibility
        time_index = pd.date_range(
            start, periods=number_of_intervals + 1, freq=f"{interval_length}H"
        )
    return time_index