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

{data_availability-0.1.0 → data_availability-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: data-availability
-Version: 0.1.0
+Version: 0.2.0
 Summary: Plot data availability for seismic
 Keywords: volcano,volcanology,seismic,data,plot,availability
 Author: Martanto
@@ -11,7 +11,9 @@ 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
@@ -50,8 +52,8 @@ from data_availability import PlotAvailability
 
 fig = (
     PlotAvailability("data.xlsx")
-    .load_data(years="2023")
-    .plot_availability(title="Sensor Uptime", tile_shape="squircle")
+    .select(years="2023")
+    .plot(title="Sensor Uptime", tile_shape="squircle")
 )
 plt.savefig("availability.png", dpi=150, bbox_inches="tight")
 ```
@@ -70,21 +72,42 @@ df = pd.read_csv("data.csv")
 fig = plot_from_df(df, title="My Data")
 ```
 
+### Seismic SDS data
+
+```python
+from data_availability import PlotSeismicAvailability
+
+fig = (
+    PlotSeismicAvailability(
+        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,
+    )
+    .plot(title="IJEN EHZ Availability 2023")
+)
+fig.savefig("ijen_availability.png", dpi=150, bbox_inches="tight")
+```
+
 ## API reference
 
 ### `PlotAvailability(filepath)`
 
-Fluent builder class.
+Fluent builder class for Excel/CSV data.
 
 ```python
 fig = (
     PlotAvailability("data.xlsx")
-    .load_data(
+    .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_availability(
+    .plot(
         title="Data Availability",
         tile_shape="square",         # "square" or "squircle"
         hspace=0.2,
@@ -98,9 +121,29 @@ fig = (
 )
 ```
 
+### `PlotSeismicAvailability(...)`
+
+Reads a SeisComP Data Structure (SDS) archive, computes per-day completeness,
+and renders the heatmap. Supports parallel processing via `n_jobs`.
+
+```python
+PlotSeismicAvailability(
+    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,
+).plot(title="IJEN EHZ")
+```
+
 ### `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`.
+Functional alternatives that accept the same keyword arguments as `.plot()` plus `date_column` and `completeness_column`.
 
 ### `load_data(filepath, date_column, completeness_column)`
 

{data_availability-0.1.0 → data_availability-0.2.0}/README.md

@@ -31,8 +31,8 @@ from data_availability import PlotAvailability
 
 fig = (
     PlotAvailability("data.xlsx")
-    .load_data(years="2023")
-    .plot_availability(title="Sensor Uptime", tile_shape="squircle")
+    .select(years="2023")
+    .plot(title="Sensor Uptime", tile_shape="squircle")
 )
 plt.savefig("availability.png", dpi=150, bbox_inches="tight")
 ```
@@ -51,21 +51,42 @@ df = pd.read_csv("data.csv")
 fig = plot_from_df(df, title="My Data")
 ```
 
+### Seismic SDS data
+
+```python
+from data_availability import PlotSeismicAvailability
+
+fig = (
+    PlotSeismicAvailability(
+        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,
+    )
+    .plot(title="IJEN EHZ Availability 2023")
+)
+fig.savefig("ijen_availability.png", dpi=150, bbox_inches="tight")
+```
+
 ## API reference
 
 ### `PlotAvailability(filepath)`
 
-Fluent builder class.
+Fluent builder class for Excel/CSV data.
 
 ```python
 fig = (
     PlotAvailability("data.xlsx")
-    .load_data(
+    .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_availability(
+    .plot(
         title="Data Availability",
         tile_shape="square",         # "square" or "squircle"
         hspace=0.2,
@@ -79,9 +100,29 @@ fig = (
 )
 ```
 
+### `PlotSeismicAvailability(...)`
+
+Reads a SeisComP Data Structure (SDS) archive, computes per-day completeness,
+and renders the heatmap. Supports parallel processing via `n_jobs`.
+
+```python
+PlotSeismicAvailability(
+    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,
+).plot(title="IJEN EHZ")
+```
+
 ### `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`.
+Functional alternatives that accept the same keyword arguments as `.plot()` plus `date_column` and `completeness_column`.
 
 ### `load_data(filepath, date_column, completeness_column)`
 

{data_availability-0.1.0 → data_availability-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "data-availability"
-version = "0.1.0"
+version = "0.2.0"
 authors = [
     {name = "Martanto", email = "martanto@live.com"},
 ]
@@ -14,7 +14,9 @@ license = "MIT"
 keywords = ["volcano", "volcanology", "seismic", "data", "plot", "availability"]
 requires-python = ">=3.11"
 dependencies = [
+    "loguru>=0.7.3",
     "matplotlib>=3.10.9",
+    "obspy>=1.5.0",
     "openpyxl>=3.1.5",
     "pandas>=3.0.2",
 ]

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

@@ -1,36 +1,40 @@
-"""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: 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.logger import configure_logging
+from data_availability.availability import PlotAvailability
+from data_availability.seismic.plot_seismic import PlotSeismicAvailability
+
+
+__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",
+    "PlotSeismicAvailability",
+    "configure_logging",
+    "load_data",
+    "plot_from_df",
+    "plot_from_file",
+]

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

@@ -11,18 +11,50 @@ from data_availability.plot import plot_from_df as _plot_from_df
 
 
 class PlotAvailability:
+    """Fluent builder for GitHub-style calendar heatmaps from file-based data.
+
+    Chain :meth:`select` then :meth:`plot` to load data and produce a figure.
+
+    Args:
+        filepath: Path to an ``.xlsx``, ``.xls``, or ``.csv`` file.
+
+    Example:
+        >>> fig = (
+        ...     PlotAvailability("data.xlsx")
+        ...     .select(years="2023")
+        ...     .plot(title="Sensor Uptime", tile_shape="squircle")
+        ... )
+        >>> fig.savefig("availability.png", dpi=150, bbox_inches="tight")
+    """
+
     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(
+    def select(
         self,
         date_column: str = "date",
         completeness_column: str = "completeness",
         years: str | list[str] | None = None,
     ) -> PlotAvailability:
+        """Load and optionally filter data from the file supplied at construction.
+
+        Args:
+            date_column: Name of the date column in the source file.
+            completeness_column: Name of the completeness column (0–100) in the
+                source file.
+            years: One or more years to keep, e.g. ``"2023"`` or
+                ``["2022", "2023"]``. All years are kept when omitted.
+
+        Returns:
+            ``self`` — enables method chaining.
+
+        Raises:
+            KeyError: If the required columns are absent from the file.
+            ValueError: If ``years`` is specified but no matching rows exist.
+        """
         self._date_column = date_column
         self._completeness_column = completeness_column
         self._df = load_data(self._filepath, date_column, completeness_column)
@@ -36,7 +68,7 @@ class PlotAvailability:
                 )
         return self
 
-    def plot_availability(
+    def plot(
         self,
         title: str = "Data Availability",
         hspace: float = 0.2,
@@ -69,10 +101,11 @@ class PlotAvailability:
             A :class:`matplotlib.figure.Figure` containing the heatmap.
 
         Raises:
-            RuntimeError: If :meth:`load_data` has not been called first.
+            RuntimeError: If :meth:`select` has not been called first.
         """
         if self._df is None:
-            raise RuntimeError("Call .load_data() before .plot_availability().")
+            raise RuntimeError("Call .select() before .plot().")
+
         return _plot_from_df(
             self._df,
             title=title,

data_availability-0.2.0/src/data_availability/logger.py

@@ -0,0 +1,151 @@
+import os
+import sys
+
+from loguru import logger
+
+from data_availability.utils import ensure_dir
+
+
+# Retention periods for log files.
+_GENERAL_LOG_RETENTION = "30 days"
+_ERROR_LOG_RETENTION = "90 days"
+
+# Tracks whether logging is currently enabled.
+_logging_enabled: bool = True
+
+# Default log directory — not created until logging is first configured.
+DEFAULT_LOG_DIR = os.path.join(os.getcwd(), "logs")
+
+_FILE_FORMAT = (
+    "{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} - {message}"
+)
+
+_CONSOLE_FORMAT = (
+    "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | "
+    "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>"
+)
+
+logger.remove()
+
+
+def _configure_handlers(log_dir: str, console_level: str = "INFO") -> None:
+    """Remove all existing handlers and re-add console + file handlers.
+
+    Centralises handler configuration so that module-level setup, set_log_level(),
+    and set_log_directory() all use the same retention periods and formats.
+
+    Args:
+        log_dir (str): Directory path for log file output.
+        console_level (str, optional): Log level for the console handler.
+            Defaults to "INFO".
+    """
+    ensure_dir(log_dir)
+    logger.remove()
+
+    logger.add(
+        sys.stderr,
+        format=_CONSOLE_FORMAT,
+        level=console_level.upper(),
+        colorize=True,
+    )
+
+    logger.add(
+        os.path.join(log_dir, "availability_{time:YYYY-MM-DD}.log"),
+        rotation="00:00",
+        retention=_GENERAL_LOG_RETENTION,
+        compression="zip",
+        format=_FILE_FORMAT,
+        level="DEBUG",
+        enqueue=True,
+    )
+
+    logger.add(
+        os.path.join(log_dir, "errors_{time:YYYY-MM-DD}.log"),
+        rotation="00:00",
+        retention=_ERROR_LOG_RETENTION,
+        compression="zip",
+        format=_FILE_FORMAT,
+        level="ERROR",
+        enqueue=True,
+    )
+
+
+def configure_logging(log_dir: str | None = None, console_level: str = "INFO") -> None:
+    """Enable file + console logging for the package.
+
+    Must be called explicitly by the application; the library does **not** create
+    log files or directories on import.
+
+    Args:
+        log_dir: Directory for log files. Defaults to ``./logs`` relative to the
+            current working directory at call time.
+        console_level: Log level for the console handler (default ``"INFO"``).
+    """
+    global DEFAULT_LOG_DIR
+    if log_dir is not None:
+        DEFAULT_LOG_DIR = os.path.abspath(log_dir)
+    _configure_handlers(DEFAULT_LOG_DIR, console_level=console_level)
+
+
+def get_logger():
+    """Return the package-wide loguru logger instance.
+
+    Returns:
+        loguru.Logger: The configured logger instance with console and file handlers.
+    """
+    return logger
+
+
+def set_log_level(level: str) -> None:
+    """Change the console log level dynamically.
+
+    Removes all existing handlers and re-adds them with the new console level.
+    File handlers retain their original levels.
+
+    Args:
+        level (str): Desired log level for the console handler. One of
+            ``"DEBUG"``, ``"INFO"``, ``"WARNING"``, ``"ERROR"``, or
+            ``"CRITICAL"``. Case-insensitive.
+    """
+    _configure_handlers(DEFAULT_LOG_DIR, console_level=level)
+
+
+def set_log_directory(log_dir: str) -> None:
+    """Change the log file directory dynamically.
+
+    Updates the global ``DEFAULT_LOG_DIR``, creates the directory if needed,
+    then reconfigures all handlers to write to the new location.
+
+    Args:
+        log_dir (str): Absolute or relative path to the new log directory.
+            Created automatically if it does not exist.
+    """
+    global DEFAULT_LOG_DIR
+    DEFAULT_LOG_DIR = ensure_dir(os.path.abspath(log_dir))
+    _configure_handlers(DEFAULT_LOG_DIR)
+    logger.info(f"Log directory changed to: {DEFAULT_LOG_DIR}")
+
+
+def disable_logging() -> None:
+    """Disable all logging output globally.
+
+    Remove all active loguru handlers so no messages are written to the
+    console or log files. Call :func:`enable_logging` to restore handlers.
+    """
+    global _logging_enabled
+    _logging_enabled = False
+    os.environ["DISABLE_LOGGING"] = "1"
+    logger.remove()
+
+
+def enable_logging() -> None:
+    """Re-enable logging after a previous :func:`disable_logging` call.
+
+    Restore console and file handlers using the current ``DEFAULT_LOG_DIR``.
+    Has no effect if logging is already enabled.
+    """
+    global _logging_enabled
+    if not _logging_enabled:
+        _logging_enabled = True
+        os.environ.pop("DISABLE_LOGGING", None)
+        _configure_handlers(DEFAULT_LOG_DIR)

data_availability-0.2.0/src/data_availability/seismic/plot_seismic.py

@@ -0,0 +1,181 @@
+from typing import Literal
+from datetime import datetime
+from functools import cached_property
+from multiprocessing import Pool
+
+import pandas as pd
+from matplotlib import pyplot as plt
+
+from data_availability import plot_from_df
+from data_availability.utils import to_datetime
+from data_availability.logger import logger
+from data_availability.seismic.sds import SDS
+
+
+class PlotSeismicAvailability:
+    """Build a GitHub-style calendar heatmap from a SeisComP Data Structure (SDS) archive.
+
+    Iterates over every day in ``[start_date, end_date]``, computes the
+    completeness percentage for the given NSLC code via :class:`~data_availability.seismic.sds.SDS`,
+    and delegates figure construction to :func:`~data_availability.plot.plot_from_df`.
+    Parallel processing is supported through Python's :class:`multiprocessing.Pool`.
+
+    Args:
+        start_date: First date of the range in ``"YYYY-MM-DD"`` format.
+        end_date: Last date of the range in ``"YYYY-MM-DD"`` format (inclusive).
+        sds_dir: Root directory of the SDS archive.
+        station: Station code (case-insensitive).
+        channel: Channel code, e.g. ``"EHZ"`` (case-insensitive).
+        network: Network code, e.g. ``"VG"`` (case-insensitive).
+        location: Location code (case-insensitive).
+        channel_type: SDS data-type qualifier. Defaults to ``"D"``.
+        n_jobs: Number of parallel worker processes. Defaults to ``1`` (serial).
+        verbose: When ``True``, emit detailed log messages during processing.
+
+    Note:
+        On Windows, Python's ``multiprocessing`` uses the ``spawn`` start method.
+        When using ``n_jobs > 1`` in a script, wrap the call inside
+        ``if __name__ == "__main__":`` to prevent recursive worker spawning.
+
+    Example:
+        >>> fig = (
+        ...     PlotSeismicAvailability(
+        ...         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,
+        ...     )
+        ...     .plot(title="IJEN EHZ Availability 2023")
+        ... )
+        >>> fig.savefig("ijen_availability.png", dpi=150, bbox_inches="tight")
+    """
+
+    def __init__(
+        self,
+        start_date: str,
+        end_date: str,
+        sds_dir: str,
+        station: str,
+        channel: str,
+        network: str,
+        location: str,
+        channel_type: str = "D",
+        n_jobs: int = 1,
+        verbose: bool = False,
+    ):
+        self.start_date = to_datetime(start_date)
+        self.end_date = to_datetime(end_date)
+        self.dates = pd.date_range(self.start_date, self.end_date)
+        if n_jobs < 1:
+            raise ValueError("n_jobs must be >= 1")
+        self.sds = SDS(
+            sds_dir=sds_dir,
+            station=station,
+            network=network,
+            channel=channel,
+            location=location,
+            channel_type=channel_type,
+            verbose=verbose,
+        )
+        self.n_jobs = n_jobs
+        self.verbose = verbose
+
+    @cached_property
+    def _jobs(self) -> list[tuple[int, datetime]]:
+        """Generate jobs for multiprocessing.
+
+        Creates a list of (job_index, date) tuples for parallel processing,
+        one per day in the date range.
+
+        Returns:
+            list[tuple[int, datetime]]: List of (job_index, date) tuples.
+
+        Examples:
+            >>> psa = PlotSeismicAvailability(start_date="2025-01-01", end_date="2025-01-03", ...)
+            >>> print(len(psa._jobs))  # 3 days
+        """
+        return [(job_index, date) for job_index, date in enumerate(self.dates)]
+
+    def _get_completeness(self, job_index: int, date: datetime) -> dict:
+        """Compute completeness for a single date (used as a pool worker target).
+
+        Args:
+            job_index: Sequential job index used for progress logging.
+            date: Date for which to calculate completeness.
+
+        Returns:
+            A dict with ``"date"`` (datetime) and ``"completeness"`` (float) keys.
+        """
+        date_str = date.strftime("%Y-%m-%d")
+        if self.verbose:
+            logger.info(f"Running job {job_index}: {date_str}")
+        return {"date": date, "completeness": self.sds.get_completeness(date)}
+
+    def plot(
+        self,
+        title: str | None = None,
+        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:
+        """Compute seismic completeness and render a calendar heatmap.
+
+        Calculates completeness for every day in the configured date range,
+        then passes the resulting DataFrame to :func:`~data_availability.plot.plot_from_df`.
+        Days with zero completeness are excluded from the figure.
+
+        Args:
+            title: Figure super-title. Defaults to the NSLC string
+                (e.g. ``"VG.IJEN.00.EHZ"``).
+            hspace: Vertical spacing between year subplots.
+            cbar_bottom: Gap in pixels between the bottom 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.
+            missing_color: Color for calendar days absent from the dataset.
+            tile_shape: ``"square"`` for plain rectangles; ``"squircle"`` for
+                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.
+
+        Raises:
+            ValueError: If no completeness results are produced.
+        """
+        if self.n_jobs == 1:
+            results = [self._get_completeness(*job) for job in self._jobs]
+        else:
+            if self.verbose:
+                logger.info(f"Running on {self.n_jobs} job(s)")
+
+            with Pool(self.n_jobs) as pool:
+                results = pool.starmap(self._get_completeness, self._jobs)
+
+        df = pd.DataFrame(results)
+        df = df[df["completeness"] > 0]
+
+        return plot_from_df(
+            df,
+            title=title or self.sds.nslc,
+            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.2.0/src/data_availability/seismic/sds.py

@@ -0,0 +1,217 @@
+import os
+from datetime import datetime
+
+import numpy as np
+from obspy import Trace, Stream, ObsPyReadingError, read
+
+from data_availability.utils import to_datetime
+from data_availability.logger import logger
+
+
+class SDS:
+    """Reader for seismic data stored in SeisComP Data Structure (SDS) format.
+
+    SDS organises miniSEED files under a directory tree structured as
+    ``<sds_dir>/<year>/<network>/<station>/<channel.type>/``.
+
+    Args:
+        sds_dir: Root directory of the SDS archive.
+        station: Station code (case-insensitive, stored uppercased).
+        channel: Channel code, e.g. ``"EHZ"`` (case-insensitive).
+        network: Network code, e.g. ``"VG"`` (case-insensitive).
+        location: Location code (case-insensitive).
+        channel_type: SDS data-type qualifier. Defaults to ``"D"`` (waveform data).
+        verbose: When ``True``, emit DEBUG/INFO log messages for each loaded file.
+
+    Raises:
+        FileNotFoundError: If ``sds_dir`` does not exist.
+    """
+
+    def __init__(
+        self,
+        sds_dir: str,
+        station: str,
+        channel: str,
+        network: str,
+        location: str,
+        channel_type: str = "D",
+        verbose: bool = False,
+    ):
+        self.sds_dir = sds_dir
+        self.station = station.upper()
+        self.channel = channel.upper()
+        self.network = network.upper()
+        self.location = location.upper()
+        self.channel_type = channel_type.upper()
+        self.verbose = verbose
+        self.nslc = f"{self.network}.{self.station}.{self.location}.{self.channel}"
+
+        if not os.path.exists(sds_dir):
+            raise FileNotFoundError(f"Directory {sds_dir} does not exist")
+
+    def get_filepath(self, date: datetime) -> str:
+        """Return the expected miniSEED file path for a given date.
+
+        Constructs the path following the SDS convention:
+        ``<sds_dir>/<year>/<network>/<station>/<channel.type>/<nslc>.D.<year>.<julian_day>``.
+
+        Args:
+            date: Date for which to build the path.
+
+        Returns:
+            Absolute file path string (the file may or may not exist).
+        """
+        year = date.year
+        julian_day = date.strftime("%j")
+
+        # Construct SDS directory structure
+        data_dir = os.path.join(
+            self.sds_dir,
+            str(year),
+            self.network,
+            self.station,
+            f"{self.channel}.{self.channel_type}",
+        )
+
+        filename = f"{self.nslc}.D.{year}.{julian_day}"
+        filepath = os.path.join(data_dir, filename)
+
+        return filepath
+
+    def load_stream(self, filepath: str, date_str: str) -> Stream:
+        """Load seismic stream from miniSEED file.
+
+        Reads the miniSEED file using ObsPy and merges any gaps using interpolation.
+
+        Args:
+            filepath (str): Absolute path to miniSEED file.
+            date_str (str): Date string (YYYY-MM-DD) for logging purposes.
+
+        Returns:
+            Stream: ObsPy Stream object with traces merged, or an empty Stream
+                if the file cannot be read.
+        """
+        try:
+            stream = read(filepath, format="MSEED")
+            stream = stream.merge(fill_value=None)
+
+            if self.verbose:
+                logger.debug(
+                    f"{date_str} :: Loaded {len(stream)} trace(s) from {filepath}"
+                )
+
+            return stream
+
+        except ObsPyReadingError as e:
+            logger.error(f"{date_str} :: Failed to read miniSEED file: {filepath}")
+            logger.error(f"{date_str} :: Error: {e}")
+            return Stream()
+
+        except Exception as e:
+            logger.error(f"{date_str} :: Unexpected error loading {filepath}: {e}")
+            return Stream()
+
+    def get(self, date: str | datetime) -> Stream:
+        """Load the seismic stream for a given date.
+
+        Resolves the SDS path for ``date``, reads the miniSEED file, and merges
+        any gap-separated traces. Missing or unreadable files are logged and an
+        empty :class:`~obspy.core.stream.Stream` is returned.
+
+        Args:
+            date: Date to load, as a ``datetime`` object or ``"YYYY-MM-DD"`` string.
+
+        Returns:
+            An :class:`~obspy.core.stream.Stream` containing the merged trace(s),
+            or an empty Stream when no data is available.
+        """
+        _date: datetime = to_datetime(date)
+        date_str = _date.strftime("%Y-%m-%d")
+        filepath = self.get_filepath(_date)
+
+        # Check if file exists
+        if not os.path.exists(filepath):
+            if self.verbose:
+                logger.debug(f"{date_str} :: miniSEED file not found: {filepath}")
+            return Stream()
+
+        # Load stream from file
+        stream = self.load_stream(filepath, date_str)
+
+        # Log results
+        if len(stream) == 0:
+            logger.warning(f"{date_str} :: No traces found in {filepath}")
+        elif self.verbose:
+            trace: Trace = stream[0]
+            n_samples = len(trace.data)
+            sampling_rate = trace.stats.sampling_rate
+            duration = n_samples / sampling_rate if sampling_rate > 0 else 0
+
+            logger.debug(f"{date_str} :: Stream loaded successfully")
+            logger.info(
+                f"{date_str} :: {len(stream)} trace(s), {n_samples} samples, "
+                f"{duration:.1f}s duration @ {sampling_rate}Hz."
+            )
+
+        return stream
+
+    def get_trace(self, date: datetime) -> Trace | None:
+        """Retrieve a single Trace object for the given date.
+
+        Loads the seismic stream for the specified date and returns its single
+        merged trace. Returns None when no data is available.
+
+        Args:
+            date (datetime): Date for which to retrieve data.
+
+        Returns:
+            Trace | None: The merged Trace object, or None if no data is available.
+
+        Raises:
+            ValueError: If the stream contains more than one trace after merging.
+        """
+        stream = self.get(date)
+
+        if len(stream) == 0:
+            return None
+
+        if len(stream) > 1:
+            date_str = date.strftime("%Y-%m-%d")
+            raise ValueError(
+                f"{date_str} :: Stream has more than one trace ({len(stream)} trace(s)). "
+                f"SDS should have only one trace after merge."
+            )
+
+        return stream[0]
+
+    def get_completeness(self, date: datetime) -> float:
+        """Calculate the data completeness percentage for a given date.
+
+        Computes completeness as the fraction of non-zero samples relative to
+        the expected daily sample count at the trace's sampling rate.
+
+        Args:
+            date: Date for which to compute completeness.
+
+        Returns:
+            Completeness percentage in the range [0, 100], rounded to two
+            decimal places. Returns ``0.0`` when no data is available.
+        """
+        trace = self.get_trace(date)
+        date_str = date.strftime("%Y-%m-%d")
+
+        if trace is None:
+            if self.verbose:
+                logger.warning(f"{date_str} :: Completeness: 0.0%")
+            return 0.0
+
+        sampling_rate = trace.stats.sampling_rate
+        daily_sampling_rate = sampling_rate * 60 * 60 * 24
+        non_zero: float = np.round(
+            (np.count_nonzero(trace.data) / daily_sampling_rate) * 100, 2
+        )
+
+        if self.verbose:
+            logger.info(f"{date_str} :: Completeness: {non_zero}%")
+
+        return float(non_zero)

data_availability-0.2.0/src/data_availability/utils.py

@@ -0,0 +1,54 @@
+import os
+from datetime import datetime
+
+
+def to_datetime(date: str | datetime, variable_name: str | None = None) -> datetime:
+    """Ensure date object is a datetime object.
+
+    Converts date strings in YYYY-MM-DD format to datetime objects. If already a
+    datetime object, returns it unchanged. Used for standardizing date inputs.
+
+    Args:
+        date (str | datetime): Date string in YYYY-MM-DD format or datetime object.
+        variable_name (str | None, optional): Variable name for error messages.
+            Defaults to None.
+
+    Returns:
+        datetime: Datetime object.
+
+    Raises:
+        ValueError: If date string is not in YYYY-MM-DD format.
+
+    Examples:
+        >>> to_datetime("2025-03-20")
+        datetime.datetime(2025, 3, 20, 0, 0)
+        >>> to_datetime(datetime(2025, 3, 20))
+        datetime.datetime(2025, 3, 20, 0, 0)
+    """
+    if isinstance(date, datetime):
+        return date
+
+    variable_name = f"{variable_name}" if variable_name else "Date"
+
+    try:
+        return datetime.strptime(date, "%Y-%m-%d")
+    except ValueError:
+        raise ValueError(
+            f"{variable_name} value {date} is not in valid YYYY-MM-DD format."
+        )
+
+
+def ensure_dir(path: str) -> str:
+    """Create a directory (and any missing parents) if it does not already exist.
+
+    A thin, named wrapper around ``os.makedirs(path, exist_ok=True)`` that
+    returns the path so callers can chain it inline.
+
+    Args:
+        path (str): Directory path to create.
+
+    Returns:
+        str: The same ``path`` that was passed in.
+    """
+    os.makedirs(path, exist_ok=True)
+    return path