data-availability 0.2.0__tar.gz → 0.3.1__tar.gz

data_availability-0.3.1/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: data-availability
+Version: 0.3.1
+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: loguru>=0.7.3
+Requires-Dist: matplotlib>=3.10.9
+Requires-Dist: obspy>=1.5.0
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=3.0.2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# data-availability
+
+[![Version](https://img.shields.io/pypi/v/data-availability?label=version)](https://pypi.org/project/data-availability/)
+[![Python](https://img.shields.io/pypi/pyversions/data-availability?label=python)](https://pypi.org/project/data-availability/)
+[![License](https://img.shields.io/pypi/l/data-availability?label=license)](https://pypi.org/project/data-availability/)
+[![Status](https://img.shields.io/badge/status-active%20development-orange)](https://github.com/martanto/data-availability)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/data-availability?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/data-availability)
+
+Calendar heatmaps and daily bar strips that show data completeness over time.
+
+Use it to monitor instrument data quality or to track the availability of any time series. It returns a matplotlib `Figure` with one subplot per calendar year, with each day colored on a red-yellow-green gradient by its completeness.
+
+**Input**: Excel (`.xlsx`/`.xls`) or CSV with `date` and `completeness` (0–100) columns.  
+**Output**: A `matplotlib.figure.Figure` — save or display as needed.
+
+There are two kinds of figure:
+
+- **`kind="calendar"`** (default): a GitHub contribution-style heatmap, with one tile per day on a Mon–Sun × week grid.
+
+  ![Calendar heatmap of IJEN availability](https://raw.githubusercontent.com/martanto/data-availability/refs/heads/main/assets/output.png)
+
+- **`kind="bar"`**: a status-page style strip, with one thin bar per day and month labels underneath.
+
+  ![Daily bar strip of IJEN availability](https://raw.githubusercontent.com/martanto/data-availability/refs/heads/main/assets/output-bar.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")
+    .select(years="2023")
+    .plot(title="Sensor Uptime", tile_shape="squircle")
+)
+plt.savefig("availability.png", dpi=150, bbox_inches="tight")
+
+# Same data as a daily bar strip
+fig = (
+    PlotAvailability("data.xlsx")
+    .select(years=["2022", "2023"])
+    .plot(title="Sensor Uptime", kind="bar", fig_width=10)
+)
+fig.savefig("availability-bar.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")
+```
+
+### Seismic SDS data
+
+```python
+from data_availability import SeismicAvailability
+
+sa = SeismicAvailability(
+    start_date="2023-01-01",
+    end_date="2023-12-31",
+    sds_dir="/data/sds",
+    station="IJEN",
+    channel="EHZ",
+    network="VG",
+    location="00",
+    n_jobs=4,
+)
+
+fig = sa.plot(title="IJEN EHZ Availability 2023")
+fig.savefig("ijen_availability.png", dpi=150, bbox_inches="tight")
+
+fig = sa.plot(title="IJEN EHZ Availability 2023", kind="bar")
+
+# Optional: persist the per-day completeness DataFrame
+sa.to_excel()               # writes <NSLC>_<start>-<end>.xlsx into CWD
+sa.to_excel("ijen.xlsx")    # or pass an explicit path
+records = sa.to_json()      # or serialise to JSON records
+```
+
+> On Windows, wrap the call in `if __name__ == "__main__":` when using
+> `n_jobs > 1` — Python's `spawn` start method requires it.
+
+## API reference
+
+### `PlotAvailability(filepath)`
+
+Fluent builder class for Excel/CSV data.
+
+```python
+fig = (
+    PlotAvailability("data.xlsx")
+    .select(
+        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(
+        title="Data Availability",
+        kind="calendar",             # "calendar" (heatmap) or "bar" (daily strip)
+        hspace=None,                 # default: 0.2 calendar, 1.4 bar
+        figsize_per_year=None,       # inches per year; default: 2.2 calendar, 1.2 bar
+        fig_width=20.0,              # figure width in inches
+        missing_color="#e0e0e0",     # days absent from the data
+        cbar_bottom=20,              # px between last subplot and colorbar
+        cbar_height=10,              # colorbar height in px
+        title_pad=40,                # px between first subplot and title
+        tile_shape="square",         # calendar only: "square" or "squircle"
+        tile_gap=0.9,                # calendar only: tile size (< 1 adds gaps)
+        bar_gap=0.8,                 # bar only: bar width (< 1 adds gaps)
+    )
+)
+```
+
+`tile_shape` and `tile_gap` are ignored when `kind="bar"`, and `bar_gap` is
+ignored when `kind="calendar"`. Any other `kind` raises `ValueError`.
+
+### `SeismicAvailability(...)`
+
+Reads a SeisComP Data Structure (SDS) archive, computes per-day completeness,
+and renders the heatmap. Supports parallel processing via `n_jobs`.
+
+```python
+sa = SeismicAvailability(
+    start_date="2023-01-01",  # YYYY-MM-DD
+    end_date="2023-12-31",    # YYYY-MM-DD (inclusive)
+    sds_dir="/data/sds",      # root of the SDS archive
+    station="IJEN",
+    channel="EHZ",
+    network="VG",
+    location="00",
+    channel_type="D",         # SDS data-type qualifier (default "D")
+    n_jobs=1,                 # parallel workers (default 1 = serial)
+    verbose=False,
+)
+
+sa.plot(title="IJEN EHZ")    # returns a matplotlib Figure; accepts the same
+                             # kwargs as PlotAvailability.plot() (title defaults to NSLC)
+sa.get_df()                  # DataFrame: nslc, date, filepath, completeness
+sa.to_json()                 # list of records
+sa.to_excel(path=None)       # write DataFrame to Excel; default filename in CWD
+```
+
+With `kind="calendar"`, `.plot()` drops zero-completeness days, so days
+with no data render as `missing_color` (grey) instead of red at the bottom
+of the colormap. With `kind="bar"`, those days are kept and render red, so
+outages stand out in the strip. Call `.get_df()` for the unfiltered per-day
+results.
+
+### `plot_from_file(filepath, **kwargs)` / `plot_from_df(df, **kwargs)`
+
+Functional alternatives that accept the same keyword arguments as `.plot()` (including `kind`) plus `date_column` and `completeness_column`.
+
+These don't filter out zero-completeness rows, so those days render red in both kinds.
+
+### `load_data(filepath, date_column, completeness_column)`
+
+Load and normalize an Excel or CSV file into a DataFrame ready for plotting.
+
+## Logging
+
+A stderr console handler at `INFO` level is attached automatically on
+import — you don't need to configure anything to see log output. Opt into
+rotating daily file logs (general + errors) by calling `configure_logging`:
+
+```python
+from data_availability import configure_logging
+
+configure_logging(log_dir="./logs", console_level="DEBUG")
+```
+
+The library never creates directories or writes files on import.
+
+## 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 (writes output.png and output-bar.png)
+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.3.1/README.md

@@ -0,0 +1,224 @@
+# data-availability
+
+[![Version](https://img.shields.io/pypi/v/data-availability?label=version)](https://pypi.org/project/data-availability/)
+[![Python](https://img.shields.io/pypi/pyversions/data-availability?label=python)](https://pypi.org/project/data-availability/)
+[![License](https://img.shields.io/pypi/l/data-availability?label=license)](https://pypi.org/project/data-availability/)
+[![Status](https://img.shields.io/badge/status-active%20development-orange)](https://github.com/martanto/data-availability)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/data-availability?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/data-availability)
+
+Calendar heatmaps and daily bar strips that show data completeness over time.
+
+Use it to monitor instrument data quality or to track the availability of any time series. It returns a matplotlib `Figure` with one subplot per calendar year, with each day colored on a red-yellow-green gradient by its completeness.
+
+**Input**: Excel (`.xlsx`/`.xls`) or CSV with `date` and `completeness` (0–100) columns.  
+**Output**: A `matplotlib.figure.Figure` — save or display as needed.
+
+There are two kinds of figure:
+
+- **`kind="calendar"`** (default): a GitHub contribution-style heatmap, with one tile per day on a Mon–Sun × week grid.
+
+  ![Calendar heatmap of IJEN availability](https://raw.githubusercontent.com/martanto/data-availability/refs/heads/main/assets/output.png)
+
+- **`kind="bar"`**: a status-page style strip, with one thin bar per day and month labels underneath.
+
+  ![Daily bar strip of IJEN availability](https://raw.githubusercontent.com/martanto/data-availability/refs/heads/main/assets/output-bar.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")
+    .select(years="2023")
+    .plot(title="Sensor Uptime", tile_shape="squircle")
+)
+plt.savefig("availability.png", dpi=150, bbox_inches="tight")
+
+# Same data as a daily bar strip
+fig = (
+    PlotAvailability("data.xlsx")
+    .select(years=["2022", "2023"])
+    .plot(title="Sensor Uptime", kind="bar", fig_width=10)
+)
+fig.savefig("availability-bar.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")
+```
+
+### Seismic SDS data
+
+```python
+from data_availability import SeismicAvailability
+
+sa = SeismicAvailability(
+    start_date="2023-01-01",
+    end_date="2023-12-31",
+    sds_dir="/data/sds",
+    station="IJEN",
+    channel="EHZ",
+    network="VG",
+    location="00",
+    n_jobs=4,
+)
+
+fig = sa.plot(title="IJEN EHZ Availability 2023")
+fig.savefig("ijen_availability.png", dpi=150, bbox_inches="tight")
+
+fig = sa.plot(title="IJEN EHZ Availability 2023", kind="bar")
+
+# Optional: persist the per-day completeness DataFrame
+sa.to_excel()               # writes <NSLC>_<start>-<end>.xlsx into CWD
+sa.to_excel("ijen.xlsx")    # or pass an explicit path
+records = sa.to_json()      # or serialise to JSON records
+```
+
+> On Windows, wrap the call in `if __name__ == "__main__":` when using
+> `n_jobs > 1` — Python's `spawn` start method requires it.
+
+## API reference
+
+### `PlotAvailability(filepath)`
+
+Fluent builder class for Excel/CSV data.
+
+```python
+fig = (
+    PlotAvailability("data.xlsx")
+    .select(
+        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(
+        title="Data Availability",
+        kind="calendar",             # "calendar" (heatmap) or "bar" (daily strip)
+        hspace=None,                 # default: 0.2 calendar, 1.4 bar
+        figsize_per_year=None,       # inches per year; default: 2.2 calendar, 1.2 bar
+        fig_width=20.0,              # figure width in inches
+        missing_color="#e0e0e0",     # days absent from the data
+        cbar_bottom=20,              # px between last subplot and colorbar
+        cbar_height=10,              # colorbar height in px
+        title_pad=40,                # px between first subplot and title
+        tile_shape="square",         # calendar only: "square" or "squircle"
+        tile_gap=0.9,                # calendar only: tile size (< 1 adds gaps)
+        bar_gap=0.8,                 # bar only: bar width (< 1 adds gaps)
+    )
+)
+```
+
+`tile_shape` and `tile_gap` are ignored when `kind="bar"`, and `bar_gap` is
+ignored when `kind="calendar"`. Any other `kind` raises `ValueError`.
+
+### `SeismicAvailability(...)`
+
+Reads a SeisComP Data Structure (SDS) archive, computes per-day completeness,
+and renders the heatmap. Supports parallel processing via `n_jobs`.
+
+```python
+sa = SeismicAvailability(
+    start_date="2023-01-01",  # YYYY-MM-DD
+    end_date="2023-12-31",    # YYYY-MM-DD (inclusive)
+    sds_dir="/data/sds",      # root of the SDS archive
+    station="IJEN",
+    channel="EHZ",
+    network="VG",
+    location="00",
+    channel_type="D",         # SDS data-type qualifier (default "D")
+    n_jobs=1,                 # parallel workers (default 1 = serial)
+    verbose=False,
+)
+
+sa.plot(title="IJEN EHZ")    # returns a matplotlib Figure; accepts the same
+                             # kwargs as PlotAvailability.plot() (title defaults to NSLC)
+sa.get_df()                  # DataFrame: nslc, date, filepath, completeness
+sa.to_json()                 # list of records
+sa.to_excel(path=None)       # write DataFrame to Excel; default filename in CWD
+```
+
+With `kind="calendar"`, `.plot()` drops zero-completeness days, so days
+with no data render as `missing_color` (grey) instead of red at the bottom
+of the colormap. With `kind="bar"`, those days are kept and render red, so
+outages stand out in the strip. Call `.get_df()` for the unfiltered per-day
+results.
+
+### `plot_from_file(filepath, **kwargs)` / `plot_from_df(df, **kwargs)`
+
+Functional alternatives that accept the same keyword arguments as `.plot()` (including `kind`) plus `date_column` and `completeness_column`.
+
+These don't filter out zero-completeness rows, so those days render red in both kinds.
+
+### `load_data(filepath, date_column, completeness_column)`
+
+Load and normalize an Excel or CSV file into a DataFrame ready for plotting.
+
+## Logging
+
+A stderr console handler at `INFO` level is attached automatically on
+import — you don't need to configure anything to see log output. Opt into
+rotating daily file logs (general + errors) by calling `configure_logging`:
+
+```python
+from data_availability import configure_logging
+
+configure_logging(log_dir="./logs", console_level="DEBUG")
+```
+
+The library never creates directories or writes files on import.
+
+## 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 (writes output.png and output-bar.png)
+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.2.0 → data_availability-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "data-availability"
-version = "0.2.0"
+version = "0.3.1"
 authors = [
     {name = "Martanto", email = "martanto@live.com"},
 ]
@@ -30,11 +30,11 @@ classifiers = [
 
 [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",
+    "ipykernel",
+    "notebook",
+    "pandas-stubs",
+    "ruff",
+    "ty",
 ]
 
 [tool.uv]

data_availability-0.3.1/src/data_availability/.cache/uv/.gitignore

@@ -0,0 +1 @@
+*

data_availability-0.3.1/src/data_availability/.cache/uv/CACHEDIR.TAG

@@ -0,0 +1 @@
+Signature: 8a477f597d28d172789f06886806bc55

{data_availability-0.2.0 → data_availability-0.3.1}/src/data_availability/__init__.py

@@ -15,7 +15,7 @@ from data_availability.data import load_data
 from data_availability.plot import plot_from_df, plot_from_file
 from data_availability.logger import configure_logging
 from data_availability.availability import PlotAvailability
-from data_availability.seismic.plot_seismic import PlotSeismicAvailability
+from data_availability.seismic.seismic_availability import SeismicAvailability
 
 
 __version__ = version("data-availability")
@@ -32,7 +32,7 @@ __all__ = [
     "__license__",
     "__copyright__",
     "PlotAvailability",
-    "PlotSeismicAvailability",
+    "SeismicAvailability",
     "configure_logging",
     "load_data",
     "plot_from_df",

{data_availability-0.2.0 → data_availability-0.3.1}/src/data_availability/availability.py

@@ -58,50 +58,62 @@ class 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}."
-                )
+
+        if isinstance(self._df, pd.DataFrame) and self._df.empty:
+            raise ValueError("No data found.")
+
         return self
 
     def plot(
         self,
         title: str = "Data Availability",
-        hspace: float = 0.2,
+        kind: Literal["calendar", "bar"] = "calendar",
+        hspace: float | None = None,
         cbar_bottom: int = 20,
         cbar_height: int = 10,
         tile_gap: float = 0.9,
-        figsize_per_year: float = 2.2,
+        figsize_per_year: float | None = None,
+        fig_width: float = 20.0,
         missing_color: str = "#e0e0e0",
         tile_shape: Literal["square", "squircle"] = "square",
         title_pad: int = 40,
+        bar_gap: float = 0.8,
     ) -> plt.Figure:
-        """Build a GitHub-style calendar heatmap of data completeness over time.
+        """Build a figure 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.
+            kind: ``"calendar"`` for a GitHub-style heatmap; ``"bar"`` for a
+                status-page style daily bar strip.
+            hspace: Vertical spacing between year subplots. Defaults to
+                ``0.2`` for calendar and ``1.4`` for bar.
+            cbar_bottom: Gap in pixels between the bottom edge of the last
+                subplot (for bar, its month labels) and 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.
+            tile_gap: Calendar only. Side length of each day tile (values < 1
+                add whitespace between tiles).
+            figsize_per_year: Figure height in inches allocated per year
+                subplot. Defaults to ``2.2`` for calendar and ``1.2`` for bar.
+            fig_width: Figure width in inches. Defaults to ``20``.
             missing_color: Color used for calendar days absent from the input data.
-            tile_shape: Shape of each day tile. ``"square"`` draws plain rectangles;
+            tile_shape: Calendar only. ``"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.
+            title_pad: Gap in pixels between the top of the first subplot and
+                the figure super-title.
+            bar_gap: Bar only. Width of each day bar (values < 1 add
+                whitespace between bars).
 
         Returns:
-            A :class:`matplotlib.figure.Figure` containing the heatmap.
+            A :class:`matplotlib.figure.Figure`.
 
         Raises:
             RuntimeError: If :meth:`select` has not been called first.
+            ValueError: If ``kind`` is not ``"calendar"`` or ``"bar"``.
         """
         if self._df is None:
             raise RuntimeError("Call .select() before .plot().")
@@ -111,12 +123,15 @@ class PlotAvailability:
             title=title,
             date_column=self._date_column,
             completeness_column=self._completeness_column,
+            kind=kind,
             hspace=hspace,
             cbar_bottom=cbar_bottom,
             cbar_height=cbar_height,
             tile_gap=tile_gap,
             figsize_per_year=figsize_per_year,
+            fig_width=fig_width,
             missing_color=missing_color,
             tile_shape=tile_shape,
             title_pad=title_pad,
+            bar_gap=bar_gap,
         )