volue-insight-timeseries 2.0.2__py3-none-any.whl

volue_insight_timeseries/util.py

@@ -0,0 +1,377 @@
+#
+# Various utility and conversion functions to make it easier to work with
+# the data from the backend
+#
+
+import calendar
+import datetime
+import dateutil.parser
+import pandas as pd
+import numpy as np
+import warnings
+
+try:
+    from urllib.parse import quote_plus
+except ImportError:
+    from urllib import quote_plus
+from zoneinfo import ZoneInfo
+from zoneinfo._common import ZoneInfoNotFoundError
+
+
+# Curve types
+TIME_SERIES = "TIME_SERIES"
+TAGGED = "TAGGED"
+INSTANCES = "INSTANCES"
+TAGGED_INSTANCES = "TAGGED_INSTANCES"
+
+
+# Frequency mapping from TS to Pandas
+_TS_FREQ_TABLE = {
+    "Y": "YS",
+    "S": "2QS",
+    "Q": "QS",
+    "M": "MS",
+    "W": "W-MON",
+    "H12": "12h",
+    "H6": "6h",
+    "H3": "3h",
+    "H": "h",
+    "MIN30": "30min",
+    "MIN15": "15min",
+    "MIN5": "5min",
+    "MIN": "min",
+    "D": "D",
+}
+
+# Mapping from various versions of Pandas to TS is built from map above,
+# with some additions to support older versions of pandas
+_PANDAS_FREQ_TABLE = {
+    "YS-JAN": "Y",
+    "AS-JAN": "Y",
+    "AS": "Y",
+    "2QS-JAN": "S",
+    "QS-JAN": "Q",
+    "12H": "H12",
+    "6H": "H6",
+    "3H": "H3",
+    "30T": "MIN30",
+    "15T": "MIN15",
+    "5T": "MIN5",
+    "T": "MIN",
+}
+for ts_freq, pandas_freq in _TS_FREQ_TABLE.items():
+    _PANDAS_FREQ_TABLE[pandas_freq.upper()] = ts_freq
+
+
+class CurveException(Exception):
+    pass
+
+
+class TS(object):
+    """
+    A class to hold a basic time series.
+    """
+
+    def __init__(
+        self, id=None, name=None, frequency=None, time_zone=None, tag=None, issue_date=None, curve_type=None, points=None, input_dict=None
+    ):
+        self.id = id
+        self.name = name
+        self.frequency = frequency
+        self.time_zone = time_zone
+        self.tag = tag
+        self.issue_date = issue_date
+        self.curve_type = curve_type
+        self.points = points
+
+        # input_dict is the json dict from the API
+        if input_dict is not None:
+            for k, v in input_dict.items():
+                setattr(self, k, v)
+
+        if self.time_zone is not None:
+            self.tz = parse_tz(self.time_zone)
+        else:
+            self.tz = ZoneInfo("CET")
+
+        if self.curve_type is None:
+            self.curve_type = detect_curve_type(self.issue_date, self.tag)
+        # Validation
+        if self.frequency is None:
+            raise CurveException("TS must have frequency")
+
+    def __str__(self):
+        size = ""
+        if self.points:
+            size = " size: {}".format(len(self.points))
+        return "TS: {}{}".format(self.fullname, size)
+
+    @property
+    def fullname(self):
+        attrs = []
+        if self.name:
+            attrs.append(self.name)
+        else:
+            if self.id:
+                attrs.append(str(self.id))
+            attrs.extend([self.curve_type, str(self.tz), self.frequency])
+        if self.tag:
+            attrs.append(self.tag)
+        if self.issue_date:
+            attrs.append(str(self.issue_date))
+        return " ".join(attrs)
+
+    def to_pandas(self, name=None):
+        """Converting :class:`volue_insight_timeseries.util.TS` object
+        to a pandas.Series object
+
+        Parameters
+        ----------
+        name: str, optional
+            Name of the returned pandas.Series object. If not given the name
+            of the curve will be used.
+        Returns
+        -------
+        pandas.Series
+        """
+        if name is None:
+            name = self.fullname
+        if self.points is None or len(self.points) == 0:
+            return pd.Series(name=name, dtype="float64")
+
+        index = []
+        values = []
+        for row in self.points:
+            if len(row) != 2:
+                raise ValueError("Points have unexpected contents")
+            dt = datetime.datetime.fromtimestamp(row[0] / 1000.0, self.tz)
+            index.append(dt)
+            values.append(row[1])
+        res = pd.Series(name=name, index=index, data=values)
+        mapped_freq = res.asfreq(self._map_freq(self.frequency))
+        dropped = mapped_freq.dropna()
+
+        # Warn about edge case for Gas Day timezone during DST changes.
+        # Gas Day is a 24-hour period starting at 4:00 UTC in summer and 5:00 UTC in winter, 
+        # and finishing at 4:00 UTC (or 5:00) the next day. corresponding to 6:00 local time in Germany year-round.
+        # A gas loader bug causes timestamps on the day after DST to shift to 5:00 or 7:00 instead of 6:00.
+        number_of_nan = sum(1 for point in self.points if point[1] is None)
+        if len(self.points) -  number_of_nan  != len(dropped):
+            warnings.warn(
+                f"Data length mismatch: original data length is {len(self.points)}, but mapped frequency data length is "
+                f"{len(dropped)}. This may indicate data truncation.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+        return mapped_freq
+
+    @staticmethod
+    def from_pandas(pd_series):
+        # Clean up some of the more common Pandas/api problems
+        pd_series = pd_series.astype(np.float64)
+        pd_series.replace({np.nan: None}, inplace=True)
+
+        name = pd_series.name
+        frequency = TS._rev_map_freq(pd_series.index.freqstr)
+
+        points = []
+        for i in pd_series.index:
+            t = i.astimezone("UTC")
+            timestamp = int(calendar.timegm(t.timetuple()) * 1000)
+            points.append([timestamp, pd_series[i]])
+
+        if is_integer(name):
+            return TS(id=int(name), frequency=frequency, points=points)
+        else:
+            return TS(name=name, frequency=frequency, points=points)
+
+    @staticmethod
+    def _map_freq(frequency):
+        if frequency.upper() in _TS_FREQ_TABLE:
+            frequency = _TS_FREQ_TABLE[frequency.upper()]
+        return frequency
+
+    @staticmethod
+    def _rev_map_freq(frequency):
+        if frequency.upper() in _PANDAS_FREQ_TABLE:
+            frequency = _PANDAS_FREQ_TABLE[frequency.upper()]
+        else:
+            warnings.warn(f"Frequency is not supported: '{frequency}'", FutureWarning, stacklevel=2)
+        return frequency
+
+    @staticmethod
+    def sum(ts_list, name):
+        """calculate the sum of a given list
+        of :class:`volue_insight_timeseries.util.TS` objects
+
+        Returns a :class:`~volue_insight_timeseries.util.TS`
+        (:class:`volue_insight_timeseries.util.TS`) object that is
+        the sum of a list of TS objects with the given name.
+
+        Parameters
+        ----------
+        ts_list: list
+            list of TS objects
+        name: str
+            Name of the returned TS object.
+        Returns
+        -------
+        :class:`volue_insight_timeseries.util.TS` object
+        """
+        df = _ts_list_to_dataframe(ts_list)
+        return _generated_series_to_TS(df.sum(axis=1), name)
+
+    @staticmethod
+    def mean(ts_list, name):
+        """calculate the mean of a given list of TS objects
+
+        Returns a TS (:class:`volue_insight_timeseries.util.TS`) object that is
+        the mean of a list of TS objects with the given name.
+
+        Parameters
+        ----------
+        ts_list: list
+            list of TS objects
+        name: str
+            Name of the returned TS object.
+        Returns
+        -------
+        :class:`volue_insight_timeseries.util.TS` object
+        """
+        df = _ts_list_to_dataframe(ts_list)
+        return _generated_series_to_TS(df.mean(axis=1), name)
+
+    @staticmethod
+    def median(ts_list, name):
+        """calculate the median of a given list of TS objects
+
+        Returns a TS (:class:`volue_insight_timeseries.util.TS`) object that is
+        the median of a list of TS objects with the given name.
+
+        Parameters
+        ----------
+        ts_list: list
+            list of TS objects
+        name: str
+            Name of the returned TS object.
+        Returns
+        -------
+        :class:`volue_insight_timeseries.util.TS` object
+        """
+        df = _ts_list_to_dataframe(ts_list)
+        return _generated_series_to_TS(df.median(axis=1), name)
+
+
+def _generated_series_to_TS(series, name):
+    series.name = name
+    return TS.from_pandas(series)
+
+
+def _ts_list_to_dataframe(ts_list):
+    pd_list = []
+    for ts in ts_list:
+        pd_list.append(ts.to_pandas())
+
+    return pd.concat(pd_list, axis=1)
+
+
+def tags_to_DF(tagged_list):
+    """
+    Given a list of tagged series/instances, create a DataFrame with the tag of
+    each as column name
+    """
+    return pd.DataFrame({s.tag: s.to_pandas() for s in tagged_list})
+
+
+#
+# Some parsing helpers
+#
+
+
+def parsetime(datestr, tz=None):
+    """
+    Parse the input date and optionally convert to correct time zone
+    """
+
+    d = dateutil.parser.parse(datestr)
+
+    if tz is not None:
+        if not isinstance(tz, datetime.tzinfo):
+            tz = parse_tz(tz)
+
+        if d.tzinfo is not None:
+            d = d.astimezone(tz)
+        else:
+            d = d.replace(tzinfo=tz)
+
+    else:
+        # If datestr does not have tzinfo and no tz given, assume CET
+        if d.tzinfo is None:
+            d = d.replace(tzinfo=ZoneInfo("CET"))
+    return d
+
+
+def parserange(rangeobj, tz=None):
+    """
+    Parse a range object (a pair of date strings, which may each be None)
+    """
+    if rangeobj.get("empty") is True:
+        return None
+    begin = rangeobj.get("begin")
+    end = rangeobj.get("end")
+    if begin is not None:
+        begin = parsetime(begin, tz=tz)
+    if end is not None:
+        end = parsetime(end, tz=tz)
+    return (begin, end)
+
+
+_tzmap = {
+    "CEGT": "CET",
+    "WEGT": "WET",
+    "PST": "US/Pacific",
+    "TRT": "Turkey",
+    "MSK": "Europe/Moscow",
+    "ART": "America/Argentina/Buenos_Aires",
+    "JST": "Asia/Tokyo",
+}
+
+
+def parse_tz(time_zone):
+    try:
+        if time_zone in _tzmap:
+            time_zone = _tzmap[time_zone]
+        return ZoneInfo(time_zone)
+    except ZoneInfoNotFoundError:
+        return ZoneInfo("CET")
+
+
+def detect_curve_type(issue_date, tag):
+    if issue_date is None and tag is None:
+        return TIME_SERIES
+    elif issue_date is None:
+        return TAGGED
+    elif tag is None:
+        return INSTANCES
+    else:
+        return TAGGED_INSTANCES
+
+
+def is_integer(s):
+    try:
+        int(s)
+        return True
+    except ValueError:
+        return False
+
+
+def make_arg(key, value):
+    if hasattr(value, "__iter__") and not isinstance(value, str):
+        return "&".join([make_arg(key, v) for v in value])
+
+    if isinstance(value, datetime.date):
+        tmp = value.isoformat()
+    else:
+        tmp = "{}".format(value)
+    v = quote_plus(tmp)
+    return "{}={}".format(key, v)

volue_insight_timeseries-2.0.2.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: volue_insight_timeseries
+Version: 2.0.2
+Summary: Volue Insight API python library
+Home-page: https://www.volueinsight.com
+Author: Volue Insight
+Author-email: support.insight@volue.com
+Requires-Python: >=3.10, <3.14
+License-File: LICENSE
+Requires-Dist: requests>=2.18
+Requires-Dist: sseclient-py>=1.7
+Requires-Dist: pandas>=1.5.0; python_version >= "3.10" and python_version < "3.13"
+Requires-Dist: pandas>=2.3.2; python_version ~= "3.13"
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+This library is meant as a simple toolkit for working with data from https://api.volueinsight.com/ (or equivalent services).  Note that access is based on some sort of login credentials, this library is not all that useful unless you have a valid Volue Insight account.

volue_insight_timeseries-2.0.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+volue_insight_timeseries/VERSION,sha256=tLFvrqUtwEzP4y97NCCUhVkj6_WZo8rBlARwotbXwmE,6
+volue_insight_timeseries/__init__.py,sha256=DXR1tB3huHaG9wKRbpSEYhAat97msXrFgdp9eyYR5Wc,274
+volue_insight_timeseries/auth.py,sha256=wetOsgVpAU3ApnDqjcjGsCbyWO1sewmByLPzvGSFiKg,2322
+volue_insight_timeseries/curves.py,sha256=VN6EVuaLg-6QqIKLnCbGq0-vbe_rTd5FPu8irZoDxfo,65901
+volue_insight_timeseries/events.py,sha256=GI_b6tMbmTZBmBiYXXddBb-7u9tEvbcdvREAitenvXs,4190
+volue_insight_timeseries/session.py,sha256=Ml-6V_HcPD5v5xkiqWqhwcDlylgRH4GfTee_HS8JDHY,20281
+volue_insight_timeseries/util.py,sha256=D5DstNtPXyrcLz7i5nNe4OqwKDNNbj57lQn67G_lPSo,10545
+volue_insight_timeseries-2.0.2.dist-info/licenses/LICENSE,sha256=QW5nSxE0LozNpYWdyJm_0hco_PidycTnelwYzKdW7ZM,1069
+volue_insight_timeseries-2.0.2.dist-info/METADATA,sha256=J1xazdqCvKTU6nR-MVG6ALiYp1xl6HBfbKvVhkTmiqs,902
+volue_insight_timeseries-2.0.2.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+volue_insight_timeseries-2.0.2.dist-info/top_level.txt,sha256=IxOCIoqzMAV5gS4n6CIoRW9kBZnKQHyUPlDuJpEXmNY,25
+volue_insight_timeseries-2.0.2.dist-info/RECORD,,

volue_insight_timeseries-2.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (79.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

volue_insight_timeseries-2.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Wattsight AS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

volue_insight_timeseries-2.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+volue_insight_timeseries