heatmapts 0.1.0__tar.gz

heatmapts-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.3
+Name: heatmapts
+Version: 0.1.0
+Summary: The classical time series heatmap plot extended with a mean profile and daily average and peaks.
+Author: Markus Kreft
+Author-email: Markus Kreft <mail@mkreft.de>
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: matplotlib>=3.9.2
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+<p align="center" width="100%">
+<img src="docs/logo_wide.png" width="300">
+</p>
+
+The classical time series heatmap plot extended with a mean profile and daily average and peaks.
+This type of visualization is very informative when showing large amounts of time series data.
+While I mostly use it for energy data, it can easily be adapted for any other time series.
+The figure works best for data with a range of a few months to a few years and a resolution of a few minutes to a few hours.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/sample-dark.png">
+  <img alt="Sample plot created with HeatmapTS" src="docs/sample-light.png">
+</picture>
+
+## Installation
+
+The package is available on [PyPI](https://pypi.org/project/heatmapts/):
+```sh
+pip install heatmapts
+```
+
+Alternatively, you can install it from GitHub:
+```sh
+pip install git+https://github.com/markus-kreft/heatmapts.git
+```
+or simply clone this repository and work in the local directory.
+
+
+## Usage
+
+The module provides the `heatmapfigure` function that takes a pandas Series with a timezone-aware DatetimeIndex with frequency.
+
+This example show how to load and prepare data from a csv file in the necessary way.
+This needs to be adapted depending on the format of the data at hand.
+
+```python
+from heatmapts import heatmapfigure
+
+# Read data
+df = pd.read_csv('data.csv', index_col='Timestamp')
+# Convert index to datetime and set timezone
+df.index = pd.to_datetime(df.index, format='%Y-%m-%d %H:%M:%S').tz_convert('Europe/Zurich')
+# Resample to 15 frequency
+df = df.asfreq("15min", fill_value=pd.NA)
+# Take data column and convert energy to power
+series = df['Value'] * 4
+
+fig = heatmapfigure(series, rasterized=True)
+fig.savefig("plot.pdf")
+```
+
+## Customization
+
+The figure is designed for easy customization.
+
+- Any additional keyword arguments are passed to pcolormesh, which is especially convenient for using a different colormap or norm or to use rasterization.
+
+<!-- norm = colors.TwoSlopeNorm(vcenter=0) | colors.CenteredNorm() -->
+<!-- cmap = 'gist_rainbow_r' | 'guppy' | 'fusion_r' -->
+
+- Passing a tuple of latitude and longitude coordinates will add sunrise and sunset times to the plot.
+
+```python
+fig = heatmapfigure(series, annotate_suntimes=(52.37, 4.90))
+```
+
+- The returned figure is subclassed from `matplotlib.figure.Figure` and features additional attributes for the heatmap, colorbar, daily and hourly axes.
+These can be modified as any other matplotlib axis.
+
+```python
+fig.ax_heatmap.xaxis.set_major_locator(mdates.YearLocator())
+fig.ax_heatmap.xaxis.set_major_formatter(mdates.DateFormatter("%Y"))
+```
+
+- The figure uses its own rcParams for styling.
+  You can modify or overwrite the parameters on a class level.
+  When setting an empty rcParams dictionary, the current parameters from matplotlib (e.g., as determined by `matplotlibrc`) will be used.
+
+```python
+from heatmapts import HeatmapFigure
+# Customize rc parameters
+HeatmapFigure.rc_params["font.family"] = "serif"
+HeatmapFigure.rc_params["font.size"] = 5
+
+# Set empty rc parameters to use those from matplotlib
+HeatmapFigure.rc_params = {}
+```

heatmapts-0.1.0/README.md

@@ -0,0 +1,87 @@
+<p align="center" width="100%">
+<img src="docs/logo_wide.png" width="300">
+</p>
+
+The classical time series heatmap plot extended with a mean profile and daily average and peaks.
+This type of visualization is very informative when showing large amounts of time series data.
+While I mostly use it for energy data, it can easily be adapted for any other time series.
+The figure works best for data with a range of a few months to a few years and a resolution of a few minutes to a few hours.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/sample-dark.png">
+  <img alt="Sample plot created with HeatmapTS" src="docs/sample-light.png">
+</picture>
+
+## Installation
+
+The package is available on [PyPI](https://pypi.org/project/heatmapts/):
+```sh
+pip install heatmapts
+```
+
+Alternatively, you can install it from GitHub:
+```sh
+pip install git+https://github.com/markus-kreft/heatmapts.git
+```
+or simply clone this repository and work in the local directory.
+
+
+## Usage
+
+The module provides the `heatmapfigure` function that takes a pandas Series with a timezone-aware DatetimeIndex with frequency.
+
+This example show how to load and prepare data from a csv file in the necessary way.
+This needs to be adapted depending on the format of the data at hand.
+
+```python
+from heatmapts import heatmapfigure
+
+# Read data
+df = pd.read_csv('data.csv', index_col='Timestamp')
+# Convert index to datetime and set timezone
+df.index = pd.to_datetime(df.index, format='%Y-%m-%d %H:%M:%S').tz_convert('Europe/Zurich')
+# Resample to 15 frequency
+df = df.asfreq("15min", fill_value=pd.NA)
+# Take data column and convert energy to power
+series = df['Value'] * 4
+
+fig = heatmapfigure(series, rasterized=True)
+fig.savefig("plot.pdf")
+```
+
+## Customization
+
+The figure is designed for easy customization.
+
+- Any additional keyword arguments are passed to pcolormesh, which is especially convenient for using a different colormap or norm or to use rasterization.
+
+<!-- norm = colors.TwoSlopeNorm(vcenter=0) | colors.CenteredNorm() -->
+<!-- cmap = 'gist_rainbow_r' | 'guppy' | 'fusion_r' -->
+
+- Passing a tuple of latitude and longitude coordinates will add sunrise and sunset times to the plot.
+
+```python
+fig = heatmapfigure(series, annotate_suntimes=(52.37, 4.90))
+```
+
+- The returned figure is subclassed from `matplotlib.figure.Figure` and features additional attributes for the heatmap, colorbar, daily and hourly axes.
+These can be modified as any other matplotlib axis.
+
+```python
+fig.ax_heatmap.xaxis.set_major_locator(mdates.YearLocator())
+fig.ax_heatmap.xaxis.set_major_formatter(mdates.DateFormatter("%Y"))
+```
+
+- The figure uses its own rcParams for styling.
+  You can modify or overwrite the parameters on a class level.
+  When setting an empty rcParams dictionary, the current parameters from matplotlib (e.g., as determined by `matplotlibrc`) will be used.
+
+```python
+from heatmapts import HeatmapFigure
+# Customize rc parameters
+HeatmapFigure.rc_params["font.family"] = "serif"
+HeatmapFigure.rc_params["font.size"] = 5
+
+# Set empty rc parameters to use those from matplotlib
+HeatmapFigure.rc_params = {}
+```

heatmapts-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "heatmapts"
+version = "0.1.0"
+description = "The classical time series heatmap plot extended with a mean profile and daily average and peaks."
+readme = "README.md"
+authors = [
+    { name = "Markus Kreft", email = "mail@mkreft.de" }
+]
+requires-python = ">=3.9"
+dependencies = [
+    "pandas>=2.2.3",
+    "matplotlib>=3.9.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.17,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pandas-stubs>=2.2.2.240807",
+]

heatmapts-0.1.0/src/heatmapts/__init__.py

@@ -0,0 +1,5 @@
+"""The classical time series heatmap plot extended with a mean profile and daily average and peaks."""
+
+from .heatmap import heatmapfigure, HeatmapFigure
+
+__all__ = ["heatmapfigure", "HeatmapFigure"]

heatmapts-0.1.0/src/heatmapts/heatmap.py

@@ -0,0 +1,396 @@
+import warnings
+import datetime as dt
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.dates as mdates
+from matplotlib.axes import Axes
+from cycler import cycler
+from typing import Optional
+
+from .suntimes import Sun
+
+
+class HeatmapFigure(plt.Figure):
+    """Custom matplotlib Figure subclass for plotting time series heatmaps.
+
+    Provides public attributes (ax_heatmap, ax_daily, ax_hourly, ax_cbar, ax_daily_peak)
+    for easy access and further customization of the individual plot axes.
+    """
+
+    COLOR_AXES = "#999999"
+    COLOR_SCATTER = "#000000"
+    COLOR_SUNTIMES = "#ffffff"
+    _default_figwidth = 8
+    rc_params = {
+        "figure.figsize": (_default_figwidth, _default_figwidth / 1.618),
+        "font.family": "sans-serif",
+        "font.size": 9,
+        "savefig.bbox": "tight",
+        "savefig.pad_inches": 0.02,
+        "axes.edgecolor": COLOR_AXES,
+        "xtick.color": COLOR_AXES,  # modifies both ticks and labels
+        "ytick.color": COLOR_AXES,
+        "xtick.labelcolor": "black",  # set labels back to black
+        "ytick.labelcolor": "black",
+        "lines.color": COLOR_AXES,
+        "axes.prop_cycle": cycler(
+            "color", ["#999999"]
+        ),  # this sets the facecolor for fill_between
+    }
+
+    ax_cbar: Axes
+    ax_heatmap: Axes
+    ax_daily: Axes
+    ax_daily_peak: Optional[Axes] = None
+    ax_hourly: Axes
+
+    def savefig(self, *args, **kwargs):
+        with plt.rc_context(self.rc_params):
+            super().savefig(*args, **kwargs)
+
+
+def heatmapfigure(
+    series: pd.Series,
+    cbar_label: str = "Power (kW)",
+    daily_label: str = "Energy (kWh)",
+    hourly_label: str = "Profile (kW)",
+    daily_max: bool = True,
+    daily_func: str = "integral",
+    title: Optional[str] = None,
+    annotate_suntimes: Optional[tuple[float, float]] = None,
+    figsize: Optional[tuple[int, int]] = None,
+    **kwargs,
+) -> HeatmapFigure:
+    """Makes a figure with heatmap, daily overview, and hourly profile.
+
+    Args:
+        series: Series with timezone-aware DatetimeIndex and frequency.
+                Timestamps describe the start of the interval for which the
+                value is valid.
+        cbar_label: Label for the colorbar.
+        daily_label: Label for the y-axis of the daily overview. This axis
+                     shows the integral of the series values over the day,
+                     i.e., miltiplied by the interval length.
+        hourly_label: Label for the y-axis of the mean profile.
+        daily_max: If True, the daily maximum is plotted as a scatter plot.
+        daily_func: Function to use for the daily overview. Can be "integral"
+                    for the integral over the day or "mean" for the mean.
+        title: Title of the figure.
+        annotate_suntimes: Tuple with latitude and longitude to annotate
+                           sunrise and sunset time for that location.
+        figsize: Tuple with width and height of the figure in inches.
+        **kwargs: Additional keyword arguments passed to pcolormesh.
+
+    Returns:
+        Custom Figure subclass with the plot and axes as additional attributes.
+    """
+
+    # check is series
+    if not isinstance(series, pd.Series):
+        raise TypeError("series must be a pandas Series")
+    if series.empty:
+        raise ValueError("Series cannot be empty")
+    # Check if the index is a datetime index
+    if not isinstance(series.index, pd.DatetimeIndex):
+        raise ValueError("Series index must be a DatetimeIndex")
+    index: pd.DatetimeIndex = series.index
+    # Check if the index is timezone aware
+    if index.tz is None:
+        raise ValueError("Series index must be timezone-aware")
+    # Check if the index has a fixed frequency
+    if index.freq is None:
+        raise ValueError("Series index must have a frequency")
+    if daily_func not in ["integral", "mean"]:
+        raise ValueError("`daily_func` must be either 'integral' or 'mean'")
+
+    interval_minutes = pd.to_timedelta(index.freq).total_seconds() / 60  # ty: ignore[no-matching-overload]
+
+    # Generate the pivoted heatmap and corresponding time and date range
+    data, daterange, timerange = _heatmap_data(series)
+
+    with plt.rc_context(HeatmapFigure.rc_params):
+        # Set up the figure and axes
+        fig: HeatmapFigure = plt.figure(FigureClass=HeatmapFigure, figsize=figsize)  # ty: ignore[invalid-assignment]
+        if title is not None:
+            fig.suptitle(title)
+        gs = fig.add_gridspec(
+            2,
+            2,
+            width_ratios=(7, 1),
+            height_ratios=(2, 8),
+            left=0.1,
+            right=0.9,
+            bottom=0.1,
+            top=0.9,
+            wspace=0.01,
+            hspace=0.01 * (fig.get_figwidth() / fig.get_figheight()),
+        )
+        ax = fig.add_subplot(gs[1, 0])
+        ax_daily = fig.add_subplot(gs[0, 0])
+        ax_hourly = fig.add_subplot(gs[1, 1])
+        ax_cbar = ax_daily.inset_axes((1.0, 0, 0.035, 1))  # (1.055, 0, 0.035, 1)
+
+        daily_peak_ax = _plot_hists(
+            daterange,
+            timerange,
+            data,
+            ax_daily,
+            ax_hourly,
+            interval_minutes,
+            daily_max=daily_max,
+            daily_func=daily_func,
+        )
+        ax_daily.set_ylabel(daily_label)
+        ax_hourly.set_xlabel(hourly_label)
+
+        mesh = plot_pcolormesh(ax, daterange, timerange, data, **kwargs)
+
+        # Add and style the colorbar
+        cbar = fig.colorbar(mesh, cax=ax_cbar, label=cbar_label)
+        cbar.outline.set_visible(False)  # ty: ignore[call-non-callable]
+        ax_cbar.tick_params(which="both", rotation=0, left=False, labelleft=False)
+        ax_cbar.minorticks_on()
+        # for t in ax_cbar.get_yticklabels():
+        #     t.set_verticalalignment('center')
+        ax_cbar.set_zorder(100)
+
+        if annotate_suntimes:
+            _annotate_suntimes(ax, daterange, coords=annotate_suntimes)
+
+        fig.ax_cbar = ax_cbar
+        fig.ax_heatmap = ax
+        fig.ax_daily = ax_daily
+        fig.ax_hourly = ax_hourly
+        fig.ax_daily_peak = daily_peak_ax
+        if daily_max and daily_peak_ax is not None:
+            # equalize y-axis limits of cbar and peak hist
+            daily_peak_ax.set_ylim(ax_cbar.get_ylim())
+
+        return fig
+
+
+def _heatmap_data(
+    series: pd.Series,
+) -> tuple[np.ndarray, pd.DatetimeIndex, pd.DatetimeIndex]:
+    """Get [day x hour] matrix and date-/timeranges from series"""
+    index = series.index
+    if not isinstance(index, pd.DatetimeIndex):
+        raise ValueError("Series index must be a DatetimeIndex")
+
+    # Pad to start and end of day if the series is does not cover a full day
+    if index.min().date() == index.max().date():
+        new_index = pd.date_range(
+            index.min().floor("D"),
+            index.max().floor("D") + pd.Timedelta(days=1),
+            freq=index.freq,
+        )[:-1]
+        series = series.reindex(new_index, fill_value=np.nan)
+        index = series.index
+        if not isinstance(index, pd.DatetimeIndex):
+            raise ValueError("Series index must be a DatetimeIndex")
+
+    timezone = index.tz
+    # Alternative: set date and time as multiindex (drop duplicates) and use unstack
+    df = series.copy().to_frame(name="values")
+    df["date"] = index.date
+    df["time"] = index.time
+    data = df.pivot_table(
+        index="time",
+        columns="date",
+        values="values",
+        # in local time there are duplicates, set them to nan
+        aggfunc=lambda x: x.iloc[0] if len(x) == 1 else np.nan,
+        # aggfunc=lambda x: x if len(x) == 1 else np.nan,
+        # aggfunc=lambda x: x.iloc[0],
+        # aggfunc=lambda x: x.sum(skipna=False),
+        dropna=False,
+    )
+    # Construct daterange with timezone
+    daterange = data.columns.astype("datetime64[ns]").tz_localize(timezone)
+    # Add one day to the end because pcolormesh requires edges.  When last date
+    # is one with time change backwards, adding one in local time does not add
+    # the day. Therefore, use naive timestamps and add timezone explicitly.
+    daterange = pd.date_range(
+        start=daterange.min().tz_localize(None),
+        end=daterange.max().tz_localize(None) + pd.Timedelta(days=1),
+        tz=timezone,
+    )
+    # Construct timerange with frequency and timezone information
+    timerange = pd.date_range(
+        start="1970-01-01T00:00:00",
+        end="1970-01-02T00:00:00",
+        freq=index.freq,
+        tz=timezone,
+    )
+    # Numpy needs float type with np.nan instead of pf.NA
+    data = data.replace(pd.NA, np.nan).to_numpy()
+    return data, daterange, timerange
+
+
+def plot_pcolormesh(
+    ax: Axes,
+    daterange: pd.DatetimeIndex,
+    timerange: pd.DatetimeIndex,
+    data: np.ndarray,
+    **kwargs,
+):
+    """
+    Plot the 2D demand profile
+    Take a numpy matrix and indices and make a figure with heatmap and sum/avg
+    """
+
+    mesh = ax.pcolormesh(daterange, timerange, data, **kwargs)
+    ax.set_xlim(daterange[0], daterange[-1])  # ty: ignore[invalid-argument-type]
+    ax.invert_yaxis()
+
+    locator = mdates.AutoDateLocator(tz=daterange.tz)
+    formatter = mdates.ConciseDateFormatter(locator, tz=daterange.tz)
+    ax.xaxis.set_major_locator(locator)
+    # ax.xaxis.set_major_formatter(mdates.DateFormatter("%m.%y"))
+    ax.xaxis.set_major_formatter(formatter)
+    ax.xaxis.set_minor_locator(mdates.MonthLocator(tz=daterange.tz))
+
+    # Alternative format: '%#H' if os.name == 'nt' else '%-H'
+    ax.yaxis.set_major_formatter(mdates.DateFormatter("%H", tz=timerange.tz))
+    ax.yaxis.set_major_locator(mdates.AutoDateLocator(tz=timerange.tz))
+    ax.yaxis.set_minor_locator(mdates.HourLocator(tz=timerange.tz))
+
+    # Remove last xticklabel to avoid overlap with next axis
+    ax.xaxis.get_majorticklabels()[-1].set_visible(False)
+    # Also remove first and last yticklabel to avoid overlap and because is 00
+    ax.yaxis.get_majorticklabels()[0].set_visible(False)
+    ax.yaxis.get_majorticklabels()[-1].set_visible(False)
+
+    ax.set_xlabel("Date")
+    ax.set_ylabel("Hour")
+
+    # Hide axes frame lines and set color
+    ax.spines[["top", "right"]].set_visible(False)
+
+    return mesh
+
+
+def _plot_hists(
+    daterange: pd.DatetimeIndex,
+    timerange: pd.DatetimeIndex,
+    data: np.ndarray,
+    ax_daily: Axes,
+    ax_hourly: Axes,
+    interval_minutes: float,
+    daily_max: bool,
+    daily_func: str,
+) -> Optional[Axes]:
+    """Plot the daily aggregated profile (top axis) and mean profile (right axis)."""
+    twinx = None
+    # Daily max
+    if daily_max:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", category=RuntimeWarning)
+            daily_max_draw = np.nanmax(data, axis=0)
+            daily_min_draw = np.nanmin(data, axis=0)
+            # take max if max larger than abs(min)
+            daily_peak_draw = np.where(
+                np.abs(daily_max_draw) >= np.abs(daily_min_draw),
+                daily_max_draw,
+                daily_min_draw,
+            )
+        twinx = ax_daily.twinx()
+        # twinx.set_ylabel("Peak", labelpad=0)
+        twinx.scatter(
+            daterange[:-1] + dt.timedelta(hours=12),
+            daily_peak_draw,
+            color=HeatmapFigure.COLOR_SCATTER,
+            s=1,
+            linewidths=0,
+        )
+        twinx.set_ylim(0, None)
+
+        twinx.spines[["top", "left", "bottom"]].set_visible(False)
+
+        # Rotate in case they are long
+        # # does not work in older mpl
+        # # twinx.set_yticks(twinx.get_yticks())
+        # # twinx.set_yticklabels(twinx.get_yticklabels(), rotation=90, va='center')
+        # for t in twinx.get_yticklabels():
+        #     t.set_verticalalignment('center')
+        # remove ticks and labels because we use the ones from the coolorbar
+        twinx.set_yticklabels([])
+        twinx.yaxis.set_tick_params(size=0)
+
+        # Add a line at 0 if the min is below zero
+        if np.nanmin(daily_peak_draw) < 0:
+            twinx.axhline(0, color=HeatmapFigure.COLOR_AXES, lw=0.5)
+
+    # Daily sum
+    if daily_func == "integral":
+        daily_demand = np.nansum(data, axis=0) * interval_minutes / 60
+    elif daily_func == "mean":
+        daily_demand = np.nanmean(data, axis=0)
+    ax_daily.fill_between(
+        daterange[:-1] + dt.timedelta(hours=12),
+        daily_demand,
+        alpha=0.5,
+    )
+    ax_daily.set_xlim(daterange[0], daterange[-1])  # ty: ignore[invalid-argument-type]
+    # Need to set the max here as well, else when removing the lower tick (below)
+    # the limits get extended, since the ticks have not been rendered yet.
+    ax_daily.set_ylim(min(0, daily_demand.min()), daily_demand.max())
+    # Remove first label because it may overlap with heat map
+    # ax_histx.yaxis.get_majorticklabels()[0].set_visible(False)
+
+    ax_daily.ticklabel_format(axis="y", style="sci", scilimits=(-2, 2))
+
+    # Mean profile
+    ax_hourly.fill_betweenx(
+        timerange[:-1] + dt.timedelta(minutes=interval_minutes) / 2,
+        np.nanmean(data, axis=1),
+        alpha=0.5,
+    )
+    ax_hourly.set_zorder(-1)  # Draw behind so labels from other axes can be on graph
+    ax_hourly.set_yticklabels([])
+    # If demand is larger than zero, always show from zero, else show from negative demand on
+    ax_hourly.set_xlim(min(0, np.nanmean(data, axis=1).min()), None)
+    ax_hourly.set_ylim(timerange[0], timerange[-1])  # ty: ignore[invalid-argument-type]
+    ax_hourly.invert_yaxis()  # This has to be called after setting lims
+
+    # Hide the ticks and labels
+    ax_daily.get_xaxis().set_visible(False)
+    ax_hourly.get_yaxis().set_visible(False)
+    # Hide axes frame lines
+    ax_daily.spines[["top", "right", "bottom"]].set_visible(False)
+    ax_hourly.spines[["top", "right", "left"]].set_visible(False)
+    ax_daily.minorticks_on()
+    ax_hourly.minorticks_on()
+
+    return twinx
+
+
+def _annotate_suntimes(
+    ax: Axes,
+    daterange: pd.DatetimeIndex,
+    coords: tuple[float, float],
+) -> None:
+    """Plots lines for sunrise and sunset times."""
+    # Shift daterange by half a day to match the heatmap
+    daterange = daterange[:-1] + pd.Timedelta(hours=12)
+    times = daterange.to_frame(index=False, name="date").merge(
+        pd.DataFrame(columns=["date", "sunrise", "sunset"]), how="left", on="date"
+    )
+    lat, long = coords
+    sun = Sun(latitude=lat, longitude=long)
+    times[["sunrise", "sunset"]] = times.apply(
+        lambda d: [
+            # non-aware datetime in local timezone
+            dt.datetime.combine(dt.datetime(year=1970, month=1, day=1).date(), x)
+            for x in sun.get_suntimes(d["date"])
+        ],
+        axis="columns",
+        result_type="expand",
+    )
+    # Suntimes are calcualted in the local timezone and need to be localized
+    times["sunset"] = times["sunset"].dt.tz_localize(daterange.tz)
+    times["sunrise"] = times["sunrise"].dt.tz_localize(daterange.tz)
+
+    ax.plot(daterange, times["sunset"], color=HeatmapFigure.COLOR_SUNTIMES, lw=0.5)
+    ax.plot(daterange, times["sunrise"], color=HeatmapFigure.COLOR_SUNTIMES, lw=0.5)

heatmapts-0.1.0/src/heatmapts/suntimes.py

@@ -0,0 +1,135 @@
+import datetime
+from math import sin, cos, tan, radians, degrees, acos, asin
+
+
+class Sun:
+    """Calculate sunrise and sunset based on equations from NOAA:
+    http://www.srrb.noaa.gov/highlights/sunrise/calcdetails.html
+    A similar implementation is available at
+    https://michelanders.blogspot.com/2010/12/calulating-sunrise-and-sunset-in-python.html
+    The algorithm is based on the Book Astronomical Algorithms by Jean Meeus.
+    """
+
+    def __init__(self, latitude, longitude):
+        self.latitude = latitude
+        self.longitude = longitude
+
+    @staticmethod
+    def percentday2time(x):
+        """Convert a fractional day float [0.0, 1.0) into a datetime.time object."""
+        # Ensure x is in [0, 1) by wrapping
+        x = x % 1.0
+        hours = 24 * x
+        h = int(hours)
+        minutes = (hours - h) * 60
+        m = int(minutes)
+        seconds = (minutes - m) * 60
+        s = int(seconds)
+        return datetime.time(h, m, s)
+
+    @staticmethod
+    def day_time_timezone_from_datetime(
+        date: datetime.datetime,
+    ) -> tuple[int, float, float]:
+        """Convert a datetime into a fractional day and timezone offset (in hours)."""
+        # OpenOffice day zero is December 30, 1899
+        day = date.toordinal() - datetime.datetime(1899, 12, 30).toordinal()
+        t = date.time()
+        time = (t.hour + t.minute / 60 + t.second / 3600) / 24
+        offset = date.utcoffset()
+        timezone = offset.total_seconds() / 3600 if offset else 0
+        return day, time, timezone
+
+    def get_suntimes(
+        self, date: datetime.datetime
+    ) -> tuple[datetime.time, datetime.time]:
+        """Calculate sunrise and sunset times for a given date.
+
+        The sunrise and sunset results are accurate to one minute for latitudes
+        between +/- 72°, and 10 minutes outside those.  Calculations are valid
+        for dates between 1901 and 2099, due to an approximation used in the
+        Julian Day calculation.
+
+        Args:
+            date: The date for which to calculate sunrise and sunset.
+
+        Returns:
+            tuple: A tuple containing sunrise and sunset times in local time.
+        """
+        day, time, timezone = self.day_time_timezone_from_datetime(date)
+
+        julian_day = day + 2415018.5 + time - timezone / 24
+        julian_century = (julian_day - 2451545) / 36525
+
+        geom_mean_long_sun_deg = (
+            280.46646 + julian_century * (36000.76983 + julian_century * 0.0003032)
+        ) % 360
+        geom_mean_anom_sun_deg = 357.52911 + julian_century * (
+            35999.05029 - 0.0001537 * julian_century
+        )
+        eccent_earth_orbit = 0.016708634 - julian_century * (
+            0.000042037 + 0.0000001267 * julian_century
+        )
+        sun_eq_of_ctr = (
+            sin(radians(geom_mean_anom_sun_deg))
+            * (1.914602 - julian_century * (0.004817 + 0.000014 * julian_century))
+            + sin(radians(2 * geom_mean_anom_sun_deg))
+            * (0.019993 - 0.000101 * julian_century)
+            + sin(radians(3 * geom_mean_anom_sun_deg)) * 0.000289
+        )
+        sun_true_long_deg = geom_mean_long_sun_deg + sun_eq_of_ctr
+        sun_app_long_deg = (
+            sun_true_long_deg
+            - 0.00569
+            - 0.00478 * sin(radians(125.04 - 1934.136 * julian_century))
+        )
+        mean_obliq_ecliptic_deg = (
+            23
+            + (
+                26
+                + (
+                    21.448
+                    - julian_century
+                    * (46.815 + julian_century * (0.00059 - julian_century * 0.001813))
+                )
+                / 60
+            )
+            / 60
+        )
+        obliq_corr_deg = mean_obliq_ecliptic_deg + 0.00256 * cos(
+            radians(125.04 - 1934.136 * julian_century)
+        )
+        sun_declin_deg = degrees(
+            asin(sin(radians(obliq_corr_deg)) * sin(radians(sun_app_long_deg)))
+        )
+        var_y = tan(radians(obliq_corr_deg / 2)) * tan(radians(obliq_corr_deg / 2))
+        eq_of_time_minutes = 4 * degrees(
+            var_y * sin(2 * radians(geom_mean_long_sun_deg))
+            - 2 * eccent_earth_orbit * sin(radians(geom_mean_anom_sun_deg))
+            + 4
+            * eccent_earth_orbit
+            * var_y
+            * sin(radians(geom_mean_anom_sun_deg))
+            * cos(2 * radians(geom_mean_long_sun_deg))
+            - 0.5 * var_y * var_y * sin(4 * radians(geom_mean_long_sun_deg))
+            - 1.25
+            * eccent_earth_orbit
+            * eccent_earth_orbit
+            * sin(2 * radians(geom_mean_anom_sun_deg))
+        )
+        cos_ha = cos(radians(90.833)) / (
+            cos(radians(self.latitude)) * cos(radians(sun_declin_deg))
+        ) - tan(radians(self.latitude)) * tan(radians(sun_declin_deg))
+        # Clip to avoid ValueError: math domain error at extreme latitudes/seasons
+        cos_ha = max(-1.0, min(1.0, cos_ha))
+        ha_sunrise_deg = degrees(acos(cos_ha))
+        solar_noon_lst = (
+            720 - 4 * self.longitude - eq_of_time_minutes + timezone * 60
+        ) / 1440
+        sunrise_time_lst = solar_noon_lst - ha_sunrise_deg * 4 / 1440
+        sunset_time_lst = solar_noon_lst + ha_sunrise_deg * 4 / 1440
+
+        sunrise_time_lst = self.percentday2time(sunrise_time_lst)
+        sunset_time_lst = self.percentday2time(sunset_time_lst)
+
+        return sunrise_time_lst, sunset_time_lst