data-availability 0.1.0__tar.gz

data_availability-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: data-availability
+Version: 0.1.0
+Summary: Plot data availability for seismic
+Keywords: volcano,volcanology,seismic,data,plot,availability
+Author: Martanto
+Author-email: Martanto <martanto@live.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: matplotlib>=3.10.9
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=3.0.2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# data-availability
+
+GitHub contribution-style calendar heatmaps for data completeness over time.
+
+Useful for monitoring instrument data quality or any time-series availability tracking. Generates a matplotlib `Figure` with one subplot per calendar year, each day rendered as a color-coded tile on a red-yellow-green gradient.
+
+**Input**: Excel (`.xlsx`/`.xls`) or CSV with `date` and `completeness` (0–100) columns.  
+**Output**: A `matplotlib.figure.Figure` — save or display as needed.
+
+![Availability of IJEN](https://raw.githubusercontent.com/martanto/data-availability/refs/heads/dev/init/assets/output.png)
+
+## Installation
+
+```bash
+pip install data-availability
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add data-availability
+```
+
+## Quick start
+
+### Fluent builder (recommended)
+
+```python
+import matplotlib.pyplot as plt
+from data_availability import PlotAvailability
+
+fig = (
+    PlotAvailability("data.xlsx")
+    .load_data(years="2023")
+    .plot_availability(title="Sensor Uptime", tile_shape="squircle")
+)
+plt.savefig("availability.png", dpi=150, bbox_inches="tight")
+```
+
+### One-call helpers
+
+```python
+from data_availability import plot_from_file, plot_from_df
+
+# From a file
+fig = plot_from_file("data.csv", title="My Data")
+
+# From a pre-loaded DataFrame
+import pandas as pd
+df = pd.read_csv("data.csv")
+fig = plot_from_df(df, title="My Data")
+```
+
+## API reference
+
+### `PlotAvailability(filepath)`
+
+Fluent builder class.
+
+```python
+fig = (
+    PlotAvailability("data.xlsx")
+    .load_data(
+        date_column="date",          # column name for dates
+        completeness_column="completeness",  # column name for values (0–100)
+        years=["2022", "2023"],      # filter to specific years (optional)
+    )
+    .plot_availability(
+        title="Data Availability",
+        tile_shape="square",         # "square" or "squircle"
+        hspace=0.2,
+        figsize_per_year=2.2,
+        missing_color="#e0e0e0",
+        cbar_bottom=20,
+        cbar_height=10,
+        tile_gap=0.9,
+        title_pad=40,
+    )
+)
+```
+
+### `plot_from_file(filepath, **kwargs)` / `plot_from_df(df, **kwargs)`
+
+Functional alternatives that accept the same keyword arguments as `.plot_availability()` plus `date_column` and `completeness_column`.
+
+### `load_data(filepath, date_column, completeness_column)`
+
+Load and normalize an Excel or CSV file into a DataFrame ready for plotting.
+
+## Input format
+
+| Column | Type | Notes |
+|---|---|---|
+| `date` | date string or datetime | parsed automatically |
+| `completeness` | float | clipped to [0, 100]; strings replaced with NaN |
+
+Column names are configurable via `date_column` / `completeness_column` parameters.
+
+## Development
+
+```bash
+# Install with dev extras
+uv sync --group dev
+
+# Run the example
+uv run main.py
+
+# Lint and format
+uv run ruff check --fix .
+uv run ruff format .
+
+# Type check
+uv run ty check
+```
+
+## License
+
+MIT © [Martanto](https://github.com/martanto)

data_availability-0.1.0/README.md

@@ -0,0 +1,118 @@
+# data-availability
+
+GitHub contribution-style calendar heatmaps for data completeness over time.
+
+Useful for monitoring instrument data quality or any time-series availability tracking. Generates a matplotlib `Figure` with one subplot per calendar year, each day rendered as a color-coded tile on a red-yellow-green gradient.
+
+**Input**: Excel (`.xlsx`/`.xls`) or CSV with `date` and `completeness` (0–100) columns.  
+**Output**: A `matplotlib.figure.Figure` — save or display as needed.
+
+![Availability of IJEN](https://raw.githubusercontent.com/martanto/data-availability/refs/heads/dev/init/assets/output.png)
+
+## Installation
+
+```bash
+pip install data-availability
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add data-availability
+```
+
+## Quick start
+
+### Fluent builder (recommended)
+
+```python
+import matplotlib.pyplot as plt
+from data_availability import PlotAvailability
+
+fig = (
+    PlotAvailability("data.xlsx")
+    .load_data(years="2023")
+    .plot_availability(title="Sensor Uptime", tile_shape="squircle")
+)
+plt.savefig("availability.png", dpi=150, bbox_inches="tight")
+```
+
+### One-call helpers
+
+```python
+from data_availability import plot_from_file, plot_from_df
+
+# From a file
+fig = plot_from_file("data.csv", title="My Data")
+
+# From a pre-loaded DataFrame
+import pandas as pd
+df = pd.read_csv("data.csv")
+fig = plot_from_df(df, title="My Data")
+```
+
+## API reference
+
+### `PlotAvailability(filepath)`
+
+Fluent builder class.
+
+```python
+fig = (
+    PlotAvailability("data.xlsx")
+    .load_data(
+        date_column="date",          # column name for dates
+        completeness_column="completeness",  # column name for values (0–100)
+        years=["2022", "2023"],      # filter to specific years (optional)
+    )
+    .plot_availability(
+        title="Data Availability",
+        tile_shape="square",         # "square" or "squircle"
+        hspace=0.2,
+        figsize_per_year=2.2,
+        missing_color="#e0e0e0",
+        cbar_bottom=20,
+        cbar_height=10,
+        tile_gap=0.9,
+        title_pad=40,
+    )
+)
+```
+
+### `plot_from_file(filepath, **kwargs)` / `plot_from_df(df, **kwargs)`
+
+Functional alternatives that accept the same keyword arguments as `.plot_availability()` plus `date_column` and `completeness_column`.
+
+### `load_data(filepath, date_column, completeness_column)`
+
+Load and normalize an Excel or CSV file into a DataFrame ready for plotting.
+
+## Input format
+
+| Column | Type | Notes |
+|---|---|---|
+| `date` | date string or datetime | parsed automatically |
+| `completeness` | float | clipped to [0, 100]; strings replaced with NaN |
+
+Column names are configurable via `date_column` / `completeness_column` parameters.
+
+## Development
+
+```bash
+# Install with dev extras
+uv sync --group dev
+
+# Run the example
+uv run main.py
+
+# Lint and format
+uv run ruff check --fix .
+uv run ruff format .
+
+# Type check
+uv run ty check
+```
+
+## License
+
+MIT © [Martanto](https://github.com/martanto)

data_availability-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["uv_build<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "data-availability"
+version = "0.1.0"
+authors = [
+    {name = "Martanto", email = "martanto@live.com"},
+]
+description = "Plot data availability for seismic"
+readme = "README.md"
+license = "MIT"
+keywords = ["volcano", "volcanology", "seismic", "data", "plot", "availability"]
+requires-python = ">=3.11"
+dependencies = [
+    "matplotlib>=3.10.9",
+    "openpyxl>=3.1.5",
+    "pandas>=3.0.2",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.2.0",
+    "notebook>=7.5.6",
+    "pandas-stubs==3.0.0.260204",
+    "ruff>=0.15.12",
+    "ty>=0.0.34",
+]
+
+[tool.uv]
+cache-dir = "./.cache/uv"

data_availability-0.1.0/src/data_availability/__init__.py

@@ -0,0 +1,36 @@
+"""data-availability: GitHub-style calendar heatmaps for data completeness.
+
+Generates matplotlib figures showing data completeness over time, one subplot
+per calendar year, color-coded on a red-yellow-green gradient.
+
+Example:
+    >>> from data_availability import plot_from_file
+    >>> fig = plot_from_file("data.csv", title="Sensor Uptime")
+    >>> fig.savefig("availability.png", dpi=150)
+"""
+
+from importlib.metadata import version
+
+from data_availability.data import load_data
+from data_availability.plot import plot_from_df, plot_from_file
+from data_availability.availability import PlotAvailability
+
+
+__version__ = version("data-availability")
+__author__ = "Martanto"
+__author_email__ = "martanto@live.com"
+__license__ = "MIT"
+__copyright__ = "Copyright (c) 2026, Martanto"
+__url__ = "https://github.com/martanto/data-availability"
+
+__all__ = [
+    "__version__",
+    "__author__",
+    "__author_email__",
+    "__license__",
+    "__copyright__",
+    "PlotAvailability",
+    "load_data",
+    "plot_from_df",
+    "plot_from_file",
+]

data_availability-0.1.0/src/data_availability/availability.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Literal
+from pathlib import Path
+
+import pandas as pd
+import matplotlib.pyplot as plt
+
+from data_availability.data import load_data
+from data_availability.plot import plot_from_df as _plot_from_df
+
+
+class PlotAvailability:
+    def __init__(self, filepath: str | Path) -> None:
+        self._filepath = Path(filepath)
+        self._df: pd.DataFrame | None = None
+        self._date_column: str = "date"
+        self._completeness_column: str = "completeness"
+
+    def load_data(
+        self,
+        date_column: str = "date",
+        completeness_column: str = "completeness",
+        years: str | list[str] | None = None,
+    ) -> PlotAvailability:
+        self._date_column = date_column
+        self._completeness_column = completeness_column
+        self._df = load_data(self._filepath, date_column, completeness_column)
+        if years is not None:
+            selected = [str(y) for y in ([years] if isinstance(years, str) else years)]
+            mask = self._df[date_column].dt.year.astype(str).isin(selected)
+            self._df = self._df[mask].reset_index(drop=True)
+            if isinstance(self._df, pd.DataFrame) and self._df.empty:
+                raise ValueError(
+                    f"No data found for the specified year(s): {selected}."
+                )
+        return self
+
+    def plot_availability(
+        self,
+        title: str = "Data Availability",
+        hspace: float = 0.2,
+        cbar_bottom: int = 20,
+        cbar_height: int = 10,
+        tile_gap: float = 0.9,
+        figsize_per_year: float = 2.2,
+        missing_color: str = "#e0e0e0",
+        tile_shape: Literal["square", "squircle"] = "square",
+        title_pad: int = 40,
+    ) -> plt.Figure:
+        """Build a GitHub-style calendar heatmap of data completeness over time.
+
+        Args:
+            title: Figure super-title rendered above all subplots.
+            hspace: Vertical spacing between year subplots.
+            cbar_bottom: Gap in pixels between the bottom edge of the last subplot
+                and the top of the colorbar.
+            cbar_height: Height of the colorbar in pixels.
+            tile_gap: Side length of each day tile (values < 1 add whitespace
+                between tiles).
+            figsize_per_year: Figure height in inches allocated per year subplot.
+            missing_color: Color used for calendar days absent from the input data.
+            tile_shape: Shape of each day tile. ``"square"`` draws plain rectangles;
+                ``"squircle"`` draws rectangles with rounded corners.
+            title_pad: Gap in pixels between the top of the last subplot and the
+                figure super-title.
+
+        Returns:
+            A :class:`matplotlib.figure.Figure` containing the heatmap.
+
+        Raises:
+            RuntimeError: If :meth:`load_data` has not been called first.
+        """
+        if self._df is None:
+            raise RuntimeError("Call .load_data() before .plot_availability().")
+        return _plot_from_df(
+            self._df,
+            title=title,
+            date_column=self._date_column,
+            completeness_column=self._completeness_column,
+            hspace=hspace,
+            cbar_bottom=cbar_bottom,
+            cbar_height=cbar_height,
+            tile_gap=tile_gap,
+            figsize_per_year=figsize_per_year,
+            missing_color=missing_color,
+            tile_shape=tile_shape,
+            title_pad=title_pad,
+        )

data_availability-0.1.0/src/data_availability/data.py

@@ -0,0 +1,72 @@
+import warnings
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+
+def load_data(
+    filepath: str | Path,
+    date_column: str = "date",
+    completeness_column: str = "completeness",
+) -> pd.DataFrame:
+    """Load and normalize availability data from an Excel or CSV file.
+
+    Reads a file containing ``date`` and ``completeness`` columns, parses
+    dates, clips completeness values to the range [0, 100], and returns the
+    result sorted by date.
+
+    Args:
+        filepath: Path to an ``.xlsx``, ``.xls``, or ``.csv`` file.
+        date_column: Name of the column to use as the date index. Defaults to
+            ``"date"``.
+        completeness_column: Name of the column to use as completeness values.
+            Defaults to ``"completeness"``.
+
+    Returns:
+        A DataFrame with the selected date column (datetime64, time normalized
+        to midnight) and completeness column (float, 0–100), sorted ascending
+        by date with a reset integer index.
+
+    Raises:
+        FileNotFoundError: If ``filepath`` does not exist.
+        KeyError: If the file is missing the specified date or completeness column.
+        ValueError: If ``date`` values cannot be parsed as dates.
+    """
+    path = Path(filepath)
+    if path.suffix in (".xlsx", ".xls"):
+        df = pd.read_excel(path)
+    else:
+        df = pd.read_csv(path)
+
+    missing = [
+        c for c in (date_column, completeness_column) if c not in df.columns.tolist()
+    ]
+    if missing:
+        raise KeyError(f"Column(s) not found in file: {missing}")
+
+    df = df[[date_column, completeness_column]].copy()
+
+    df[date_column] = pd.to_datetime(df[date_column]).dt.normalize()
+    if not isinstance(
+        df[date_column].dtype, pd.DatetimeTZDtype
+    ) and not pd.api.types.is_datetime64_any_dtype(df[date_column]):
+        raise ValueError(
+            f"Column '{date_column}' could not be parsed as DatetimeIndex."
+        )
+
+    string_mask = df[completeness_column].apply(lambda x: isinstance(x, str))
+    if string_mask.any():
+        n = string_mask.sum()
+        warnings.warn(
+            f"Column '{completeness_column}' contains {n} string value(s); replacing with NaN.",
+            UserWarning,
+            stacklevel=2,
+        )
+        df.loc[string_mask, completeness_column] = np.nan
+
+    df[completeness_column] = pd.to_numeric(
+        df[completeness_column], errors="coerce"
+    ).clip(0, 100)
+
+    return df.sort_values(date_column).reset_index(drop=True)

data_availability-0.1.0/src/data_availability/plot.py

@@ -0,0 +1,320 @@
+from typing import Literal
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import matplotlib.colors as mcolors
+import matplotlib.pyplot as plt
+import matplotlib.patches as mpatches
+
+from data_availability.data import load_data
+
+
+def _build_figure(
+    df: pd.DataFrame,
+    title: str,
+    date_column: str,
+    completeness_column: str,
+    hspace: float,
+    cbar_bottom: int,
+    cbar_height: int,
+    tile_gap: float,
+    figsize_per_year: float,
+    missing_color: str,
+    tile_shape: Literal["square", "squircle"],
+    title_pad: int,
+) -> plt.Figure:
+    """Render a GitHub-style calendar heatmap from a pre-validated DataFrame.
+
+    Internal helper called by :func:`plot_from_file` and :func:`plot_from_df`.
+    Creates one subplot per calendar year in ``df``, draws day tiles on a
+    Mon–Sun × week grid, attaches a horizontal colorbar below the last subplot,
+    and places a super-title above the first.
+
+    Args:
+        df: DataFrame with a datetime ``date_column`` and a numeric
+            ``completeness_column`` (0–100), sorted ascending by date.
+        title: Figure super-title rendered above all subplots.
+        date_column: Name of the datetime column in ``df``.
+        completeness_column: Name of the numeric completeness column (0–100).
+        hspace: Vertical spacing between year subplots, passed to
+            ``Figure.subplots_adjust``.
+        cbar_bottom: Gap in pixels between the bottom edge of the last subplot
+            and the top of the colorbar.
+        cbar_height: Height of the colorbar in pixels.
+        tile_gap: Side length of each day tile; values less than 1 add
+            whitespace between tiles.
+        figsize_per_year: Figure height in inches allocated per year subplot.
+            Total figure height is ``n_years * figsize_per_year``.
+        missing_color: Hex or named color for calendar days absent from
+            ``df``.
+        tile_shape: ``"square"`` draws plain rectangles; ``"squircle"`` draws
+            rectangles with rounded corners.
+        title_pad: Gap in pixels between the top of the first subplot and the
+            figure super-title.
+
+    Returns:
+        A :class:`matplotlib.figure.Figure` containing the heatmap.
+    """
+    years = sorted(df[date_column].dt.year.unique())
+    n_years = len(years)
+
+    fig, axes = plt.subplots(n_years, 1, figsize=(20, n_years * figsize_per_year))
+    if n_years == 1:
+        axes = [axes]
+
+    cmap = mcolors.LinearSegmentedColormap.from_list(
+        "rg", ["#d73027", "#fee08b", "#1a9850"]
+    )
+    norm = mcolors.Normalize(vmin=0, vmax=100)
+
+    day_labels = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+
+    for ax, year in zip(axes, years, strict=True):
+        year_dates = pd.date_range(f"{year}-01-01", f"{year}-12-31", freq="D")
+        year_df = df[df[date_column].dt.year == year].set_index(date_column)[
+            completeness_column
+        ]
+
+        # Build a 7-row (weekday) x 53-col (week) grid
+        grid = np.full((7, 53), np.nan)
+        has_data = np.zeros((7, 53), dtype=bool)
+
+        for date in year_dates:
+            # GitHub-style: week col starts from the week of Jan 1
+            day_of_year = date.day_of_year - 1  # 0-indexed
+            # week column: offset by weekday of Jan 1
+            jan1_weekday = pd.Timestamp(f"{year}-01-01").weekday()  # Mon=0
+            col = (day_of_year + jan1_weekday) // 7
+            row = date.weekday()  # Mon=0, Sun=6
+            has_data[row, col] = True
+            if date in year_df.index:
+                grid[row, col] = year_df[date]
+            else:
+                grid[row, col] = np.nan  # missing = will render grey
+
+        # Draw tiles
+        rounding = tile_gap * 0.3
+        for col in range(53):
+            for row in range(7):
+                if not has_data[row, col]:
+                    continue
+                val = grid[row, col]
+                color = missing_color if np.isnan(val) else cmap(norm(val))
+                if tile_shape == "squircle":
+                    patch = mpatches.FancyBboxPatch(
+                        (col, 6 - row),
+                        tile_gap,
+                        tile_gap,
+                        boxstyle=f"round,pad=0,rounding_size={rounding}",
+                        facecolor=color,
+                        edgecolor="white",
+                        linewidth=0.5,
+                    )
+                else:
+                    patch = mpatches.Rectangle(
+                        (col, 6 - row),
+                        tile_gap,
+                        tile_gap,
+                        facecolor=color,
+                        edgecolor="white",
+                        linewidth=0.5,
+                    )
+                ax.add_patch(patch)
+
+        # Month label positions
+        month_starts = {}
+        for date in year_dates:
+            if date.day == 1:
+                jan1_weekday = pd.Timestamp(f"{year}-01-01").weekday()
+                day_of_year = date.day_of_year - 1
+                col = (day_of_year + jan1_weekday) // 7
+                month_starts[date.strftime("%b")] = col
+
+        for month, col in month_starts.items():
+            ax.text(
+                col + 0.4,
+                7.2,
+                month,
+                ha="center",
+                va="bottom",
+                fontsize=7,
+                color="#555",
+            )
+
+        ax.set_xlim(0, 53)
+        ax.set_ylim(-0.2, 7.8)
+        ax.set_aspect("equal")
+        ax.set_yticks([6 - r + tile_gap / 2 for r in range(7)])
+        ax.set_yticklabels(day_labels, fontsize=7)
+        ax.set_xticks([])
+        ax.set_ylabel(str(year), fontsize=9, rotation=0, labelpad=30, va="center")
+        ax.set_frame_on(False)
+        ax.tick_params(left=False)
+
+    fig.subplots_adjust(hspace=hspace)
+
+    # Get the bounding box of the last subplot to anchor the colorbar tightly below it
+    fig.canvas.draw()
+    last_ax = axes[-1]
+    first_ax = axes[0]
+    pos_last = last_ax.get_position()
+    pos_first = first_ax.get_position()
+
+    cbar_width = (pos_last.x1 - pos_last.x0) * 0.8
+    cbar_left = pos_last.x0 + (pos_last.x1 - pos_last.x0) * 0.1
+    fig_height_px = fig.get_size_inches()[1] * fig.dpi
+    cbar_height_fraction = cbar_height / fig_height_px
+    cbar_bottom_fraction = cbar_bottom / fig_height_px
+    cbar_ax = fig.add_axes(
+        [
+            cbar_left,
+            pos_last.y0 - cbar_bottom_fraction,
+            cbar_width,
+            cbar_height_fraction,
+        ]
+    )
+
+    sm = plt.cm.ScalarMappable(cmap=cmap, norm=norm)
+    sm.set_array([])
+    cbar = fig.colorbar(sm, cax=cbar_ax, orientation="horizontal")
+    cbar.set_label("Completeness (%)", fontsize=9)
+    cbar.ax.tick_params(labelsize=8)
+
+    title_pad_fraction = title_pad / fig_height_px
+    fig.suptitle(title, fontsize=13, fontweight="bold", y=pos_first.y1 + title_pad_fraction)
+
+    return fig
+
+
+def plot_from_file(
+    filepath: str | Path,
+    title: str = "Data Availability",
+    date_column: str = "date",
+    completeness_column: str = "completeness",
+    hspace: float = 0.2,
+    cbar_bottom: int = 20,
+    cbar_height: int = 10,
+    tile_gap: float = 0.9,
+    figsize_per_year: float = 2.2,
+    missing_color: str = "#e0e0e0",
+    tile_shape: Literal["square", "squircle"] = "square",
+    title_pad: int = 40,
+) -> plt.Figure:
+    """Build a GitHub-style calendar heatmap of data completeness from a file.
+
+    Loads data from an Excel or CSV file and delegates to
+    :func:`plot_from_df`. Creates one subplot per calendar year, with each day
+    rendered as a colored tile on a Mon–Sun × week grid. Tiles are color-coded
+    on a red-yellow-green gradient; days absent from the dataset are rendered
+    in ``missing_color``. A horizontal colorbar is placed below the last
+    subplot and a super-title above the first.
+
+    Args:
+        filepath: Path to an ``.xlsx``, ``.xls``, or ``.csv`` file accepted by
+            :func:`~data_availability.data.load_data`.
+        title: Figure super-title rendered above all subplots.
+        date_column: Name of the datetime column in the file.
+        completeness_column: Name of the numeric completeness column (0–100).
+        hspace: Vertical spacing between year subplots, passed to
+            ``Figure.subplots_adjust``.
+        cbar_bottom: Gap in pixels between the bottom edge of the last subplot
+            and the top of the colorbar.
+        cbar_height: Height of the colorbar in pixels.
+        tile_gap: Side length of each day tile; values less than 1 add
+            whitespace between tiles.
+        figsize_per_year: Figure height in inches allocated per year subplot.
+            Total figure height is ``n_years * figsize_per_year``.
+        missing_color: Hex or named color for calendar days absent from the
+            input data.
+        tile_shape: ``"square"`` draws plain rectangles; ``"squircle"`` draws
+            rectangles with rounded corners.
+        title_pad: Gap in pixels between the top of the first subplot and the
+            figure super-title.
+
+    Returns:
+        A :class:`matplotlib.figure.Figure` containing the heatmap. The figure
+        is not saved or displayed; call ``fig.savefig()`` or ``plt.show()``
+        afterwards.
+    """
+    df = load_data(
+        filepath, date_column=date_column, completeness_column=completeness_column
+    )
+    return _build_figure(
+        df,
+        title=title,
+        date_column=date_column,
+        completeness_column=completeness_column,
+        hspace=hspace,
+        cbar_bottom=cbar_bottom,
+        cbar_height=cbar_height,
+        tile_gap=tile_gap,
+        figsize_per_year=figsize_per_year,
+        missing_color=missing_color,
+        tile_shape=tile_shape,
+        title_pad=title_pad,
+    )
+
+
+def plot_from_df(
+    df: pd.DataFrame,
+    title: str = "Data Availability",
+    date_column: str = "date",
+    completeness_column: str = "completeness",
+    hspace: float = 0.2,
+    cbar_bottom: int = 20,
+    cbar_height: int = 10,
+    tile_gap: float = 0.9,
+    figsize_per_year: float = 2.2,
+    missing_color: str = "#e0e0e0",
+    tile_shape: Literal["square", "squircle"] = "square",
+    title_pad: int = 40,
+) -> plt.Figure:
+    """Build a GitHub-style calendar heatmap from an in-memory DataFrame.
+
+    Accepts a pre-loaded :class:`~pandas.DataFrame` instead of a file path.
+    Useful when data has already been loaded and optionally filtered before
+    plotting. For file-based access see :func:`plot_from_file`.
+
+    Args:
+        df: DataFrame with a datetime ``date_column`` and a numeric
+            ``completeness_column`` (0–100), as returned by
+            :func:`~data_availability.data.load_data`.
+        title: Figure super-title rendered above all subplots.
+        date_column: Name of the datetime column in ``df``.
+        completeness_column: Name of the numeric completeness column (0–100).
+        hspace: Vertical spacing between year subplots, passed to
+            ``Figure.subplots_adjust``.
+        cbar_bottom: Gap in pixels between the bottom edge of the last subplot
+            and the top of the colorbar.
+        cbar_height: Height of the colorbar in pixels.
+        tile_gap: Side length of each day tile; values less than 1 add
+            whitespace between tiles.
+        figsize_per_year: Figure height in inches allocated per year subplot.
+            Total figure height is ``n_years * figsize_per_year``.
+        missing_color: Hex or named color for calendar days absent from
+            ``df``.
+        tile_shape: ``"square"`` draws plain rectangles; ``"squircle"`` draws
+            rectangles with rounded corners.
+        title_pad: Gap in pixels between the top of the first subplot and the
+            figure super-title.
+
+    Returns:
+        A :class:`matplotlib.figure.Figure` containing the heatmap. The figure
+        is not saved or displayed; call ``fig.savefig()`` or ``plt.show()``
+        afterwards.
+    """
+    return _build_figure(
+        df,
+        title=title,
+        date_column=date_column,
+        completeness_column=completeness_column,
+        hspace=hspace,
+        cbar_bottom=cbar_bottom,
+        cbar_height=cbar_height,
+        tile_gap=tile_gap,
+        figsize_per_year=figsize_per_year,
+        missing_color=missing_color,
+        tile_shape=tile_shape,
+        title_pad=title_pad,
+    )