ebas-plot 0.1.0__py3-none-any.whl

ebas_plot-0.1.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: ebas-plot
+Version: 0.1.0
+Summary: Plotting utilities for EBAS datasets served via THREDDS/OPeNDAP.
+Author-email: Lise Eder Murberg <lemu@nilu.no>, Marthe Brevig <mbre@nilu.no>, Jonathan Elias Holme <jhol@nilu.no>
+License-Expression: AGPL-3.0-or-later
+Project-URL: Homepage, https://git.nilu.no/ebas/ebas-web/ebas-web-plotting
+Project-URL: Source, https://git.nilu.no/ebas/ebas-web/ebas-web-plotting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: netCDF4
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: plotly
+Requires-Dist: pydap
+Requires-Dist: requests
+Requires-Dist: xarray
+Dynamic: license-file
+
+# ebas-plot
+
+Plotting utilities for EBAS datasets served via THREDDS/OPeNDAP.
+
+## Installation
+
+For normal use, install the latest released version from the public Python
+Package Index (PyPI):
+
+```bash
+python3 -m pip install ebas-plot
+```
+
+This installs a fixed release, such as `0.1.0`, together with its required
+dependencies. It is the recommended command for users after a version has been
+published through GitLab CI.
+
+For testing changes that have not yet been published, install the current code
+directly from the `python-package` development branch:
+
+```bash
+python3 -m pip install "git+https://git.nilu.no/ebas/ebas-web/ebas-web-plotting.git@python-package"
+```
+
+This bypasses PyPI and installs the latest commit on that branch. It requires
+Git to be installed and permission to access `git.nilu.no`; use it only when
+you need unreleased changes.
+
+## Usage
+
+### Command line
+
+```bash
+ebas-plot <url>
+```
+
+`<url>` can be a local EBAS NetCDF file or a remote EBAS dataset:
+
+- `/path/to/dataset.nc`
+- `https://doi.nilu.no/doi/8HWP-FRNN`
+- `https://doi.org/10.48597/8HWP-FRNN`
+- `https://thredds.nilu.no/thredds/dodsC/ebas_doi/...`
+- `https://thredds.nilu.no/thredds/fileServer/ebas_doi/...`
+
+The plot type is selected automatically: datasets with a `d_D` dimension are
+shown as PNSD heatmaps; other supported EBAS datasets are shown as time series.
+
+Choose the time-series rendering explicitly with `--mode line` or
+`--mode scatter`:
+
+```bash
+ebas-plot --mode scatter /path/to/dataset.nc
+```
+
+Use `--var_plots` to open one plot per physical quantity rather than one
+combined time-series plot:
+
+```bash
+ebas-plot --var_plots https://doi.nilu.no/doi/8HWP-FRNN
+```
+
+### As a library
+
+```python
+from ebas_plot import open_dataset, plot, plot_pnsd, plot_timeseries
+
+# Auto-detect a remote dataset's plot type.
+fig = plot("https://doi.nilu.no/doi/8HWP-FRNN")
+fig.show()
+
+# Open a local EBAS NetCDF file and select scatter points.
+ds = open_dataset("/path/to/dataset.nc")
+fig = plot_timeseries(ds, mode="scatter")
+fig.show()
+
+# Produce one time-series figure per physical quantity.
+figures = plot("https://doi.nilu.no/doi/8HWP-FRNN", var_plots=True, mode="line")
+for figure in figures:
+	figure.show()
+```
+
+## Releases
+
+The `python-package` branch is the release branch. GitLab CI builds the source
+and wheel distributions for its commits. To publish a new version, update
+`__version__` in `ebas_plot.py`, push the branch, and run the manual `publish`
+job. Configure the protected GitLab CI/CD variable `PYPI_TOKEN` with a PyPI
+project-scoped API token before publishing.
+
+## License
+
+Copyright (C) 2026 Lise Eder Murberg, Marthe Brevig, and Jonathan Elias Holme.
+
+This project is licensed under the GNU Affero General Public License, version
+3 or later (AGPL-3.0-or-later). The full license text is available at
+https://www.gnu.org/licenses/agpl-3.0.html.

ebas_plot-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+ebas_plot.py,sha256=HuRbjOgGLGunHqQWBFmLocyHMoAuumkLHsi4herzeMs,35201
+ebas_plot-0.1.0.dist-info/licenses/LICENSE,sha256=7ZpO8LOz0uwP0ZXf1VdifRWnVKK6wPAICJ9ULsrndDs,840
+ebas_plot-0.1.0.dist-info/METADATA,sha256=TR897rdRB_NSyl5EU7cnfW-cftWV33B0RLxd3mSK0TU,4006
+ebas_plot-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ebas_plot-0.1.0.dist-info/entry_points.txt,sha256=pOXlW0kxym2YdjkQw2HxLtHgXoaLOgQBzxZ78uVovn0,45
+ebas_plot-0.1.0.dist-info/top_level.txt,sha256=EcUPwQUC64wFbj_S3eIgWmItisCrkva69sjFY-5ywd4,10
+ebas_plot-0.1.0.dist-info/RECORD,,

ebas_plot-0.1.0.dist-info/WHEEL

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

ebas_plot-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ebas-plot = ebas_plot:main

ebas_plot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,17 @@
+ebas-plot
+Copyright (C) 2026 Lise Eder Murberg, Marthe Brevig, and Jonathan Elias Holme
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License along
+with this program. If not, see <https://www.gnu.org/licenses/>.
+
+The complete GNU Affero General Public License version 3 is available at
+<https://www.gnu.org/licenses/agpl-3.0.html>.

ebas_plot-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ebas_plot

ebas_plot.py

@@ -0,0 +1,873 @@
+import re
+
+import xarray as xr
+import plotly.graph_objects as go
+import numpy as np
+import requests
+from netCDF4 import num2date
+import pandas as pd
+
+__version__ = "0.1.0"
+
+
+class DatasetAccessError(Exception):
+    """OPeNDAP data endpoint denied or failed access; carries the HTTP status that caused it."""
+
+    def __init__(self, status_code: int, message: str):
+        super().__init__(message)
+        self.status_code = status_code
+
+_CUSTOM_COLORS_WAVELENGTH = [
+    "#9400D3",  # DarkViolet
+    "#0000FF",  # Blue
+    "#00FF00",  # Lime
+    "#FFD700",  # Gold
+    "#FF0000",  # Red
+    "#8B0000",  # DarkRed
+    "#000000",  # Black
+    "#FF1493",  # DeepPink
+    "#00CED1",  # DarkTurquoise
+    "#FF8C00",  # DarkOrange
+]
+
+_CUSTOM_COLORS_PNSD = [
+    "#000CF2", "#0026D8", "#003FBF", "#0059A5", "#00728C", "#008C72",
+    "#00A559", "#00BF3F", "#00D826", "#00F20C", "#0CFF00", "#26FF00",
+    "#3FFF00", "#59FF00", "#72FF00", "#8CFF00", "#A5FF00", "#BFFF00",
+    "#D8FF00", "#F2FF00", "#FFF200", "#FFD800", "#FFBF00", "#FFA500",
+    "#FF8C00", "#FF7200", "#FF5900", "#FF3F00", "#FF2600", "#FF0C00",
+]
+
+# NILU Primary and additional colors for variables (17 total)
+_CUSTOM_COLORS_VARIABLES = [
+    "#053F53", # Dark Teal
+    "#9FD2FE", # Light Blue
+    "#FF891D", # Orange
+    "#0A8AB6", # Blue
+    "#A74FFF", # Purple
+    "#2D7756", # Dark Green 
+    "#E93CAC", # Pink
+    "#E9C649", # Yellow
+    "#840F5A", # Dark Magenta
+    "#01C399", # Turquoise
+    "#C00000", # Dark Red
+    "#6F6F6F", # Gray
+    "#F2A3C5", # Light Pink
+    "#54FEDB", # Light Turquoise
+    "#5B3F9B",  # Indigo
+    "#7FB800",  # Lime Green
+    "#D45500",  # Burnt Orange
+]
+
+_AUXILIARY = {"v_pressure", "v_relative_humidity", "v_temperature", "v_pH", "v_conductivity"}
+_STATISTICS = {
+    "_prec1587", "_perc1587", "_perc8413", "_prec8413",
+    "_uncertainty", "_stddev", "_det_lim", "_ExpUnc2s",
+    "_precision", "_max", "_min", "_median",
+}  # ancillary statistics; excluded from plots (not primary mean values)
+# Only these d_* dimensions are allowed in timeseries plots, d_D is in spesific PNSD plot.
+_ALLOWED_D_DIMS = {"d_Wavelength", "d_Tower_inlet_height"}
+
+_RESOLUTION_UNIT_DAYS = {"mn": 1 / 1440, "h": 1 / 24, "d": 1, "w": 7, "mo": 30, "y": 365} # used for converting resolution codes to days
+_RESOLUTION_CODE_RE = re.compile(r"^(\d+)(mn|mo|[hdwy])$")
+
+_MONTH_ONLY_THRESHOLD = pd.Timedelta(days=32)  # spans >= this are shown as month-only in hover text
+
+def validate_dataset(path: str) -> xr.Dataset | None:
+    """Open a local netCDF file, validate it against EBAS plotting requirements, and return the dataset.
+
+    Prints ERROR for missing required fields (returns None) and WARNING for missing optional fields.
+    """
+    import os
+    if not path.endswith(".nc"):
+        print(f"ERROR: expected a .nc file, got: {path}")
+        return None
+    if not os.path.isfile(path):
+        print(f"ERROR: file not found: {path}")
+        return None
+    try:
+        ds = xr.open_dataset(path)
+    except Exception as exc:
+        print(f"ERROR: could not open file: {exc}")
+        return None
+
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    # --- Required ---
+    if "time" not in ds.coords and "time" not in ds.dims:
+        errors.append("Missing required 'time' dimension/coordinate.")
+
+    plot_vars = _plot_vars(ds)
+    if not plot_vars:
+        errors.append("No plottable variables found — need at least one 'v_*' float variable with a 'time' dimension.")
+    else:
+        for name in plot_vars:
+            if not ds[name].attrs.get("ebas_unit") and not ds[name].attrs.get("units"):
+                warnings.append(f"'{name}' has no 'ebas_unit' or 'units' attribute — unit label will be blank.")
+
+    # --- Optional ---
+    if "time_bnds" not in ds:
+        warnings.append("Missing 'time_bnds' — hover text will show timestamps instead of sample periods.")
+    if not ds.attrs.get("title") and not ds.attrs.get("ebas_station_name") and not ds.attrs.get("site_name"):
+        warnings.append("Missing 'title'/'ebas_station_name'/'site_name' — plot title will be 'Unknown Site'.")
+    if not ds.attrs.get("ebas_resolution_code"):
+        warnings.append("Missing 'ebas_resolution_code' — resolution will be omitted from hover text.")
+    if not ds.attrs.get("ebas_matrix"):
+        warnings.append("Missing 'ebas_matrix' — auxiliary variables (temperature, pressure, etc.) will be excluded.")
+
+    for msg in errors:
+        print(f"ERROR: {msg}")
+    for msg in warnings:
+        print(f"WARNING: {msg}")
+
+    return None if errors else ds
+
+
+def _doi_to_opendap_url(doi: str) -> str:
+    """Convert a DOI identifier like '8HWP-FRNN' to the THREDDS OPeNDAP URL."""
+    s = doi.replace("-", "")
+    return f"https://thredds.nilu.no/thredds/dodsC/ebas_doi/{s[0:2]}/{s[2:4]}/{s[4:6]}/{doi}.nc"
+
+
+def open_dataset(url: str, token: str | None = None) -> xr.Dataset:
+    """Open an EBAS dataset from a local .nc path, DOI, or THREDDS URL."""
+    if not url.startswith("http"):  # local file
+        ds = validate_dataset(url)
+        if ds is None:
+            raise ValueError(f"Dataset failed validation: {url}")
+        return ds
+    elif url.startswith("https://doi.nilu.no/doi/") or url.startswith("https://doi.org/"):  # DOI link
+        opendap_url = _doi_to_opendap_url(url.split("/")[-1])
+    elif url.startswith("https://thredds.nilu.no/thredds/fileServer/ebas_doi/"):  # Download link, convert to OPeNDAP
+        opendap_url = url.replace("fileServer", "dodsC")
+    elif url.startswith("https://thredds.nilu.no/thredds/dodsC/ebas_doi/"):  # direct OPeNDAP link
+        opendap_url = url
+    else:
+        raise ValueError(f"Unsupported dataset URL: {url}")
+
+    # netCDF4's DAP client doesn't surface THREDDS's 401/403 quickly, silently retrying
+    # for 40-120s -- probe the data endpoint ourselves so access issues fail fast.
+    headers = {"Authorization": f"Bearer {token}"} if token else None
+    try:
+        probe = requests.get(f"{opendap_url}.dods?time[0:1:0]", headers=headers, timeout=5)
+    except requests.exceptions.RequestException as exc:
+        raise DatasetAccessError(503, f"OPeNDAP server unreachable: {exc}") from exc
+    if probe.status_code in (401, 403):
+        raise DatasetAccessError(probe.status_code, "Dataset is restricted")
+    if probe.status_code >= 500:
+        raise DatasetAccessError(503, f"OPeNDAP server error ({probe.status_code})")
+
+    if token:
+        session = requests.Session()
+        session.headers["Authorization"] = f"Bearer {token}"
+        return xr.open_dataset(opendap_url, engine="pydap", session=session)
+
+    try:
+        return xr.open_dataset(opendap_url, engine="netcdf4")
+    except RuntimeError:
+        # Driver-level I/O failure -- retrying with decode_times=False would just double the load.
+        raise
+    except Exception as exc:
+        print(f"Standard open failed ({exc}); retrying with decode_times=False")
+        return xr.open_dataset(opendap_url, engine="netcdf4", decode_times=False)
+
+
+def get_plot_time(ds: xr.Dataset):
+    """Return time axis values, decoding numeric time when possible."""
+    time_da = ds["time"]
+    if np.issubdtype(time_da.dtype, np.datetime64):
+        return time_da.values
+    units = time_da.attrs.get("units")
+    calendar = time_da.attrs.get("calendar", "standard")
+    if units:
+        try:
+            return np.array(num2date(time_da.values, units=units, calendar=calendar))
+        except Exception as exc:
+            print(f"Could not decode numeric time ({exc}); using raw values.")
+    return time_da.values
+
+
+def _hex_to_rgba(hex_color: str, alpha: float) -> str:
+    """Convert a hex color string to an rgba() string with the given opacity."""
+    h = hex_color[1:]
+    r, g, b = int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
+    return f"rgba({r},{g},{b},{alpha:.2f})"
+
+
+def _dataset_title(ds: xr.Dataset) -> str:
+    """Return a plot title from dataset attributes."""
+    title = (ds.attrs.get("title") or "").replace("_", " ")
+    station = ds.attrs.get("ebas_station_name", ds.attrs.get("site_name", ""))
+    if title:
+        if ds.attrs.get("ebas_data_level", "") not in ("3a", "3b"): # OBS check for NOx when we have combined products! 
+            return title
+        if "equivalent black carbon" in title:
+            return "Equivalent black carbon at " + station
+    return station or "Unknown Site"
+
+
+def _var_mean(ds: xr.Dataset, name: str) -> float:
+    """Mean of finite values, used as a sort key."""
+    vals = ds[name].values.ravel()
+    finite = vals[np.isfinite(vals)]
+    return float(finite.mean()) if len(finite) else 0.0
+
+
+def _var_unit(ds: xr.Dataset, name: str) -> str:
+    """Return the preferred unit label for a variable."""
+    return ds[name].attrs.get("ebas_unit", ds[name].attrs.get("units", ""))
+
+
+def _unit_score(unit: str) -> int:
+    """Rank a unit for default visibility: mol/mol (3) > plain mass /m3 (2) > element-specific (1)."""
+    u = unit.lower().replace("µ", "u")
+    if "mol/mol" in u:
+        return 3
+    if u.endswith("/m3") and " " not in u:
+        return 2
+    return 1
+
+
+def _sampling_resolution(ds: xr.Dataset, time_step: pd.Timedelta) -> pd.Timedelta:
+    """Return the dataset's nominal sampling resolution as a timedelta, using the EBAS resolution code."""
+    m = _RESOLUTION_CODE_RE.match(ds.attrs.get("ebas_resolution_code", "").strip().lower())
+    if not m:
+        return time_step
+    n, unit = int(m.group(1)), m.group(2)
+    return pd.Timedelta(days=n * _RESOLUTION_UNIT_DAYS[unit])
+
+
+def _default_plot_mode(ds: xr.Dataset, time_step: pd.Timedelta) -> str:
+    """Return 'line' or 'scatter': the mode to use when the caller doesn't specify one.
+
+    A single time step can only be shown as a scatter point. Otherwise, weekly-or-coarser
+    declared resolutions default to scatter (typical of passive samplers/campaigns), as
+    does data that's actually sparser than declared (e.g. a '1d' code but samples that are
+    really >3 days apart on average) -- everything else defaults to line.
+    """
+    if ds.sizes.get("time", 0) == 1:
+        return "scatter"
+    resolution = _sampling_resolution(ds, time_step)
+    if resolution >= pd.Timedelta(weeks=1) or time_step > pd.Timedelta(days=3):
+        return "scatter"
+    return "line"
+
+
+def _scatter_hovertexts(x_time, ds: xr.Dataset) -> list[str]:
+    """Build per-point hover strings e.g. 'Aug 2006 \u2013 Oct 2006 (3mo)' or '12 \u2013 19 Nov 2012 (1w)'."""
+    if "time_bnds" in ds:
+        bnds = ds["time_bnds"].values
+        starts, ends = bnds[:, 0], bnds[:, 1]
+    else:
+        starts = ends = x_time
+    res = ds.attrs.get("ebas_resolution_code", "")
+    suffix = f" ({res})" if res else ""
+
+    def _fmt(s, e) -> str:
+        start, end = pd.Timestamp(s), pd.Timestamp(e)
+        if end - start >= _MONTH_ONLY_THRESHOLD:  # coarse/campaign samples
+            return f"{start:%b %Y} \u2013 {end:%b %Y}{suffix}"
+        # Sub-monthly: exact days
+        same_month = start.month == end.month and start.year == end.year
+        start_fmt = f"{start:%-d}" if same_month else f"{start:%-d %b}"
+        return f"{start_fmt} \u2013 {end:%-d %b %Y}{suffix}"
+
+    return [_fmt(s, e) for s, e in zip(starts, ends)]
+
+
+def _pnsd_var(ds: xr.Dataset) -> str | None:
+    """Return the name of the particle number size distribution variable, or None."""
+    return next((n for n in ds.data_vars if n.startswith("v_") and "d_D" in ds[n].dims), None)
+
+
+def _dimension_with_prefix(da: xr.DataArray, prefix: str) -> str | None:
+    """Return a dimension named prefix or its EBAS-suffixed form, e.g. d_Wavelength_d0."""
+    return next((dim for dim in da.dims if dim == prefix or dim.startswith(f"{prefix}_")), None)
+
+
+def _plot_vars(ds: xr.Dataset) -> list[str]:
+    """Return measurement variable names to plot for a timeseries dataset.
+
+    Excludes auxiliary variables, percentile statistics, all-missing variables,
+    and variables whose extra (non-time) dimensions contain any d_* dimension
+    that is not in _ALLOWED_D_DIMS (e.g. d_D for PNSD would be excluded).
+    EBAS-suffixed dimension names such as d_Wavelength_d0 are treated as their
+    base name.
+
+    For data level 3a/3b datasets that contain equivalent black carbon,
+    only eBC variables are returned.
+    """
+    is_met_dataset = ds.attrs.get("ebas_matrix", "").strip().lower() == "met"
+
+    result = []
+    for name in ds.data_vars:
+        if not name.startswith("v_"):
+            continue
+        if "time" not in ds[name].dims:
+            continue
+        if name in _AUXILIARY and not is_met_dataset:
+            continue
+        if any(name.endswith(suffix) for suffix in _STATISTICS):
+            continue
+        if any(
+            d.startswith("d_")
+            and not any(d == allowed or d.startswith(f"{allowed}_") for allowed in _ALLOWED_D_DIMS)
+            for d in ds[name].dims
+        ):
+            continue
+        if not np.isfinite(ds[name].values).any():
+            continue
+        result.append(name)
+
+    # For level 3a/3b datasets with eBC, only show the eBC variable
+    data_level = ds.attrs.get("ebas_data_level", "")
+    if data_level in ("3a", "3b"):
+        ebc_vars = [n for n in result if "equivalent_black_carbon" in n]
+        if ebc_vars:
+            return ebc_vars
+
+    return result
+
+
+def _pretty_var_name(name: str, units: str = "") -> str:
+    """Return a human-readable label from a variable name."""
+    s = name[2:] if name.startswith("v_") else name
+    for suffix in ("_amean", "_mean"):
+        if s.endswith(suffix):
+            s = s[:-len(suffix)]
+            break
+    if units:
+        unit_key = units.replace("/", "_per_").replace(" ", "_").replace(".", "").lower()
+        idx = s.lower().find(unit_key)
+        if idx > 0:
+            s = s[:idx].rstrip("_")
+    s = s.replace("_", " ")
+    return s[:1].upper() + s[1:]
+
+
+def _group_vars_by_physical_quantity(ds: xr.Dataset, plot_vars: list[str]) -> list[tuple[str, list[str]]]:
+    """Group plot variables by physical quantity (same base name, possibly different units).
+
+    Returns an ordered list of (group_label, [var_names]) where group_label is
+    the human-readable name of the physical quantity (e.g. 'Methane').
+    Variables that share the same pretty name after stripping unit descriptors
+    and stat suffixes are considered the same physical quantity.
+    """
+    groups: dict[str, list[str]] = {}
+    for name in plot_vars:
+        key = _pretty_var_name(name, _var_unit(ds, name))
+        groups.setdefault(key, []).append(name)
+    return list(groups.items())
+
+
+def plot_pnsd(ds: xr.Dataset) -> go.Figure:
+    """Plot particle number size distribution (PNSD) as a heatmap."""
+    var_name = _pnsd_var(ds)
+    if var_name is None:
+        raise ValueError(
+            "No PNSD variable found (expected a 'v_*' variable with a 'd_D' dimension). "
+            f"Available: {list(ds.data_vars)}"
+        )
+    if "time" not in ds.coords and "time" not in ds.dims:
+        raise ValueError(
+            "Missing time coordinate/dimension 'time'. "
+            f"Dataset coordinates: {list(ds.coords)}"
+        )
+
+    da = ds[var_name].transpose("d_D", "time")
+    z_raw = np.asarray(da.values, dtype=float)
+    z_raw[z_raw <= 0] = np.nan
+    z = np.log10(z_raw)
+    x_time = get_plot_time(ds)
+    y_d = ds["d_D"].values
+
+    # Fixed logarithmic scale from -1.0 to 5.0 with 0.2 interval; APS instruments cap lower (max 3.0).
+    log_min = -1.0
+    log_max = 3.0 if ds.attrs.get("ebas_instrument_type", "").strip().lower() == "aps" else 5.0
+    tick_interval = 0.2
+
+    tickvals1 = np.arange(log_min, log_max + tick_interval, tick_interval)
+    ticktext1 = [f'{val:.1f}' for val in tickvals1]
+
+    # Build discrete Plotly colorscale from global palette
+    n = len(_CUSTOM_COLORS_PNSD)
+    plotly_discrete_colorscale = [
+        [i / (n - 1), c] for i, c in enumerate(_CUSTOM_COLORS_PNSD)
+    ]
+
+    fig = go.Figure(go.Heatmap(
+            x=x_time,
+            y=y_d,
+            z=z,
+            zmin=log_min,
+            zmax=log_max,
+            zsmooth='best',
+            colorscale=plotly_discrete_colorscale,
+            showscale=True,
+            colorbar=dict(
+                orientation='h',
+                x=0.5,
+                y=1.02,
+                xanchor='center',
+                yanchor='bottom',
+                len=1,
+                thickness=15,
+                title=dict(
+                    text=r'log10(dN/dlogDp) [1/cm3]',
+                    font=dict(size=12, family='Arial, sans-serif'),
+                    side='right'
+                ),
+                tickvals=tickvals1,
+                ticktext=ticktext1,
+                tick0=log_min,          
+                dtick=tick_interval,
+            ),
+        )
+    )       
+    fig.update_layout(
+        title=_dataset_title(ds),
+        xaxis_title="Time",
+        yaxis_title="Diameter (D)",
+        yaxis_type="log",
+        template="plotly_white",
+        hovermode="x unified",
+        autosize=True,
+        height=450,
+        margin=dict(l=60, r=20, t=80, b=60),
+        modebar=dict(remove=["lasso2d", "select2d"]),
+    )
+    return fig
+
+
+def _isolated_points_mask(y: np.ndarray) -> np.ndarray:
+    """Return a bool mask of finite values that have no finite neighbor on either side."""
+    finite = np.isfinite(y)
+    left_finite = np.concatenate(([False], finite[:-1]))
+    right_finite = np.concatenate((finite[1:], [False]))
+    return finite & ~left_finite & ~right_finite
+
+
+def _fill_small_gaps(y: np.ndarray, max_gap_steps: int) -> np.ndarray:
+    """Linearly interpolate over NaN runs of <= max_gap_steps for line plots; keep longer runs as NaN.
+
+    Filled values are not real measurements, only used so Plotly draws a connecting line across the gap.
+    """
+    if max_gap_steps <= 0:
+        return y
+    return pd.Series(y, dtype=float).interpolate(
+        method="linear", limit=max_gap_steps, limit_area="inside"
+    ).to_numpy()
+
+
+def _time_valid_mask(da: xr.DataArray, arr: np.ndarray) -> np.ndarray:
+    """Return which time steps contain at least one finite value."""
+    if arr.ndim == 1:
+        return np.isfinite(arr)
+    time_axis = list(da.dims).index("time")
+    return np.any(np.isfinite(arr), axis=tuple(i for i in range(arr.ndim) if i != time_axis))
+
+
+def _valid_time_indices(da: xr.DataArray, arr: np.ndarray) -> np.ndarray | None:
+    """Return valid time indices for floating point data, else None."""
+    if not np.issubdtype(arr.dtype, np.floating):
+        return None
+    return np.flatnonzero(_time_valid_mask(da, arr))
+
+
+def _gap_fill_threshold(
+    ds: xr.Dataset, plot_vars: list[str], time_step: pd.Timedelta,
+    var_data: dict[str, np.ndarray] | None = None,
+) -> int:
+    """Return how many consecutive NaN steps to interpolate over based on sampling frequency for line plots."""
+    gaps = []
+    for name in plot_vars:
+        arr = var_data[name] if var_data is not None and name in var_data else ds[name].values
+        idx = _valid_time_indices(ds[name], arr)
+        if idx is not None and len(idx) > 1:
+            gaps.append(np.diff(idx))
+    if not gaps:
+        return 0
+    median_iv = np.median(np.concatenate(gaps)) * time_step
+    max_gap = 6 * time_step if time_step <= pd.Timedelta(hours=1) else 3 * median_iv # HERE is where the threshold is chosen based on the sampling frequency (6*1h and 3*all other)
+    return max(1, round(max_gap / time_step))
+
+
+def _break_temporal_gaps(
+    x_time: np.ndarray, y: np.ndarray, max_gap_steps: int, time_step: pd.Timedelta
+) -> tuple[np.ndarray, np.ndarray]:
+    """Insert a NaN sentinel at each x_time jump > max_gap_steps so Plotly breaks the line."""
+    if max_gap_steps <= 0:
+        return x_time, y
+    gap_idx = np.where((pd.Series(pd.to_datetime(x_time)).diff() / time_step).values > max_gap_steps + 0.5)[0]
+    if not len(gap_idx):
+        return x_time, y
+    return (np.insert(x_time, gap_idx, x_time[gap_idx - 1]),
+            np.insert(y.astype(float), gap_idx, np.nan))
+
+
+def _add_timeseries_trace(
+    fig: go.Figure,
+    *,
+    x_time,
+    y: np.ndarray,
+    name: str,
+    color: str,
+    legendgroup: str | None,
+    use_scatter: bool,
+    hovertexts,
+    max_gap_steps: int,
+    time_step: pd.Timedelta,
+    iso_marker_size: int,
+    visible: bool | str = True,
+) -> None:
+    """Emit a single trace per variable. No-op if no finite data.
+
+    In line mode, isolated finite points get a small marker on the same trace.
+    """
+    if not np.isfinite(y).any():
+        return
+
+    if use_scatter:
+        kw: dict = dict(x=x_time, y=y, mode="markers",
+                         marker=dict(color=color, size=6),
+                         hovertemplate="%{y:.4g}<br>%{customdata}<extra></extra>", customdata=hovertexts)
+    else:
+        y_line = _fill_small_gaps(y, max_gap_steps)
+        x_line, y_line = _break_temporal_gaps(x_time, y_line, max_gap_steps, time_step)
+        isolated_points = _isolated_points_mask(y_line)
+        kw = dict(x=x_line, y=y_line, mode="lines",
+                   line=dict(color=color, width=2),
+                   hovertemplate="%{y:.4g}<extra></extra>")
+        if isolated_points.any():
+            kw.update(mode="lines+markers",
+                      marker=dict(color=color,
+                                  size=np.where(isolated_points, iso_marker_size, 0).tolist(),
+                                  symbol="circle"))
+
+    kw.update(name=name, connectgaps=False)
+    if visible != True:
+        kw["visible"] = visible
+    if legendgroup is not None:
+        kw["legendgroup"] = legendgroup
+        kw["legendgrouptitle_text"] = legendgroup
+    fig.add_trace(go.Scatter(**kw))
+
+
+def _has_line_segments(
+    ds: xr.Dataset, plot_vars: list[str], max_gap_steps: int, var_data: dict[str, np.ndarray],
+) -> bool:
+    """Return True if at least one variable has two consecutive valid samples within max_gap_steps.
+
+    Used to fail fast when line mode is requested/selected but the data is so sparse or
+    irregular that no connecting line segment would actually be drawn.
+    """
+    for name in plot_vars:
+        idx = _valid_time_indices(ds[name], var_data[name])
+        if idx is not None and len(idx) > 1 and np.any(np.diff(idx) <= max_gap_steps):
+            return True
+    return False
+
+
+def plot_timeseries(
+    ds: xr.Dataset,
+    *,
+    subset_vars: list[str] | None = None,
+    title: str | None = None,
+    var_color_offsets: dict[str, int] | None = None,
+    wl_color_offsets: dict[str, int] | None = None,
+    mode: str | None = None,
+) -> go.Figure:
+    """Plot timeseries variables in a single plot, grouped by variable in the legend.
+
+    Args:
+        subset_vars: If provided, only plot these variable names instead of all
+            plottable variables from the dataset.
+        title: Override the plot title. Defaults to the dataset title.
+        var_color_offsets: Per-variable index into the VARIABLES/WAVELENGTH color palette.
+            When provided, overrides the auto-incremented counter for each named variable.
+        wl_color_offsets: Per-variable starting offset into WAVELENGTH palette for
+            variables with a d_Wavelength dimension.
+        mode: 'line' or 'scatter' to force a plot mode; if None, it's chosen automatically
+            via `_default_plot_mode`. Line mode raises a ValueError if the data is too
+            sparse/irregular to draw any connecting line segment (see `_has_line_segments`).
+    """
+    if mode is not None and mode not in ("line", "scatter"):
+        raise ValueError(f"Invalid mode: {mode!r}. Expected 'line', 'scatter', or None.")
+
+    if "time" not in ds.coords and "time" not in ds.dims:
+        raise ValueError(
+            "Missing time coordinate/dimension 'time'. "
+            f"Dataset coordinates: {list(ds.coords)}"
+        )
+
+    plot_vars = subset_vars if subset_vars is not None else _plot_vars(ds)
+    if not plot_vars:
+        raise ValueError(
+            "No plottable variables found (expected 'v_*' mean variables). "
+            f"Available: {list(ds.data_vars)}"
+        )
+
+    # Pre-load all variable data once to avoid redundant OPeNDAP reads during sort, gap computation, and trace emission.
+    _var_data: dict[str, np.ndarray] = {n: ds[n].values for n in plot_vars}
+
+    # Detect whether all variables share the same unit; if so use flat legend style
+    all_units = [_var_unit(ds, n) for n in plot_vars]
+    multi_unit = len(set(all_units)) > 1
+
+    # For multi-unit groups, only show the highest-ranked unit by default; others are legend-only.
+    quantity_groups = _group_vars_by_physical_quantity(ds, plot_vars)
+    if multi_unit:
+        _preferred_var = {
+            max(vs, key=lambda n: _unit_score(_var_unit(ds, n)))
+            for _, vs in quantity_groups
+        }
+    else:
+        _preferred_var = set(plot_vars)
+
+    def _mean_pre(n: str) -> float:
+        arr = _var_data[n].ravel()
+        f = arr[np.isfinite(arr)]
+        return float(f.mean()) if len(f) else 0.0
+
+    # Sort physical-quantity groups (preferred first, then by descending mean of their best
+    # variant), but keep each group's own unit variants adjacent -- Plotly requires traces
+    # sharing a legendgroup to be contiguous in fig.data, or legend click/isolate misbehaves.
+    def _group_sort_key(group: tuple[str, list[str]]) -> tuple[int, float]:
+        _, names = group
+        best = max(names, key=_mean_pre)
+        return (0 if best in _preferred_var else 1, -_mean_pre(best))
+
+    plot_vars = [
+        n for _, names in sorted(quantity_groups, key=_group_sort_key)
+        for n in sorted(names, key=lambda n: 0 if n in _preferred_var else 1)
+    ]
+
+    x_time = get_plot_time(ds)
+    fig = go.Figure()
+
+    _iso_marker_size = 4
+
+    _time_step = pd.Series(pd.to_datetime(x_time)).diff().median()
+    use_scatter = (mode or _default_plot_mode(ds, _time_step)) == "scatter"
+    _max_gap_steps = _gap_fill_threshold(ds, plot_vars, _time_step, _var_data)
+    if not use_scatter and not _has_line_segments(ds, plot_vars, _max_gap_steps, _var_data):
+        raise ValueError(
+            "Line mode was requested/selected, but the data is too sparse or irregular "
+            "to draw any connecting line -- use mode='scatter' instead."
+        )
+    hovertexts = _scatter_hovertexts(x_time, ds)
+
+    # Determine plot mode
+    has_wavelength = any(_dimension_with_prefix(ds[n], "d_Wavelength") is not None for n in plot_vars)
+    var_color_idx = 0
+    wl_color_offset = 0  # advances through _CUSTOM_COLORS_WAVELENGTH per wl variable
+
+    def _var_color(name: str, palette: list[str]) -> str:
+        """Pick the next color for a plain/tower variable, honoring var_color_offsets if given."""
+        nonlocal var_color_idx
+        idx = var_color_offsets[name] if var_color_offsets and name in var_color_offsets else var_color_idx
+        if var_color_offsets is None:
+            var_color_idx += 1
+        return palette[idx % len(palette)]
+
+    def _wl_colors(name: str, n_values: int) -> list[str]:
+        """Pick n_values consecutive wavelength colors, honoring wl_color_offsets if given."""
+        nonlocal wl_color_offset
+        eff = wl_color_offsets[name] if wl_color_offsets and name in wl_color_offsets else wl_color_offset
+        if wl_color_offsets is None:
+            wl_color_offset += n_values
+        return [_CUSTOM_COLORS_WAVELENGTH[(eff + i) % len(_CUSTOM_COLORS_WAVELENGTH)] for i in range(n_values)]
+
+    for name in plot_vars:
+        da = ds[name]
+        units = _var_unit(ds, name)
+        pretty = _pretty_var_name(name, units)
+        group_title = f"{pretty} [{units}]" if units else pretty
+
+        wavelength_dim = _dimension_with_prefix(da, "d_Wavelength")
+        if wavelength_dim:
+            wl_values = da.coords[wavelength_dim].values
+            for color, wl in zip(_wl_colors(name, len(wl_values)), wl_values):
+                y = da.sel({wavelength_dim: wl}).values.copy()
+                _add_timeseries_trace(fig, x_time=x_time, y=y, name=f"{float(wl):.1f} nm",
+                            color=color, legendgroup=group_title,
+                            use_scatter=use_scatter, hovertexts=hovertexts,
+                            max_gap_steps=_max_gap_steps, time_step=_time_step,
+                            iso_marker_size=_iso_marker_size)
+
+        elif "d_Tower_inlet_height" in da.dims:
+            base_color = _var_color(name, _CUSTOM_COLORS_VARIABLES)
+            height_values = da.coords["d_Tower_inlet_height"].values
+            n_heights = len(height_values)
+            opacities = [1.0 - (i / max(n_heights - 1, 1)) * 0.65 for i in range(n_heights)]
+            for h_idx, height in enumerate(height_values):
+                color = _hex_to_rgba(base_color, opacities[h_idx])
+                y = da.sel(d_Tower_inlet_height=height).values.copy()
+                _add_timeseries_trace(fig, x_time=x_time, y=y, name=f"h\u1d35\u2099\u1d35={height:.0f}m",
+                            color=color, legendgroup=group_title,
+                            use_scatter=use_scatter, hovertexts=hovertexts,
+                            max_gap_steps=_max_gap_steps, time_step=_time_step,
+                            iso_marker_size=_iso_marker_size)
+
+        else:
+            wl = None
+            if "d_Wavelength" in da.coords:
+                wl = float(da.coords["d_Wavelength"].values)
+            elif "wavelength" in da.attrs:
+                try:
+                    wl = float(da.attrs["wavelength"])
+                except (TypeError, ValueError):
+                    pass
+
+            palette = _CUSTOM_COLORS_WAVELENGTH if has_wavelength else _CUSTOM_COLORS_VARIABLES
+            color = _var_color(name, palette)
+
+            trace_name = f"{wl:.1f} nm" if isinstance(wl, float) else (
+                (f"[{units}]" if units else pretty) if multi_unit else group_title
+            )
+            lg = pretty if (multi_unit and not isinstance(wl, float)) else None
+            visible = True if name in _preferred_var else "legendonly"
+
+            y = _var_data[name].copy()
+            _add_timeseries_trace(fig, x_time=x_time, y=y, name=trace_name,
+                        color=color, legendgroup=lg, visible=visible,
+                        use_scatter=use_scatter, hovertexts=hovertexts,
+                        max_gap_steps=_max_gap_steps, time_step=_time_step,
+                        iso_marker_size=_iso_marker_size)
+
+    n_traces = len(fig.data)
+    legend_rows = max(1, -(-n_traces // 3))  # ceil(n_traces / 3)
+    bottom_margin = max(80, 30 + legend_rows * 28)
+
+    # Approximate 7px per character at font size 11; min 120px.
+    all_labels = [t.name or "" for t in fig.data] + [
+        t.legendgrouptitle.text for t in fig.data
+        if getattr(t, "legendgrouptitle", None) and t.legendgrouptitle.text
+    ]
+    entry_width = max(80, max((len(l) for l in all_labels), default=10) * 7)
+
+    fig.update_layout(
+        title=title if title is not None else _dataset_title(ds),
+        xaxis_title="Time",
+        template="plotly_white",
+        hovermode="x unified",
+        showlegend=True,
+        autosize=True,
+        height=400 + bottom_margin,
+        legend=dict(
+            groupclick="toggleitem",
+            itemclick="toggle",
+            itemdoubleclick="toggleothers",
+            orientation="h",
+            yanchor="top",
+            y=-0.2,
+            xanchor="left",
+            x=0,
+            font=dict(size=11),
+            entrywidth=entry_width,
+            entrywidthmode="pixels",
+        ),
+        margin=dict(l=60, r=20, t=50, b=bottom_margin),
+        modebar=dict(remove=["lasso2d", "select2d"]),
+    )
+    return fig
+
+
+def plot_timeseries_per_var(ds: xr.Dataset, *, mode: str | None = None) -> list[go.Figure]:
+    """Return one figure per physical quantity, preserving combined-plot colors.
+
+    Variables with the same base name but different units are grouped together.
+    Falls back to a single combined figure when there is only one group.
+    """
+    plot_vars = _plot_vars(ds)
+    if not plot_vars:
+        raise ValueError(
+            "No plottable variables found (expected 'v_*' mean variables). "
+            f"Available: {list(ds.data_vars)}"
+        )
+    groups = _group_vars_by_physical_quantity(ds, plot_vars)
+    if len(groups) <= 1:
+        return [plot_timeseries(ds, mode=mode)]
+
+    # Walk the same sorted order as the combined plot to build per-variable color offsets.
+    all_units = {_var_unit(ds, n) for n in plot_vars}
+    preferred = (
+        {max(vs, key=lambda n: _unit_score(_var_unit(ds, n)))
+         for _, vs in groups}
+        if len(all_units) > 1 else set(plot_vars)
+    )
+    vc, wc = 0, 0
+    vc_map: dict[str, int] = {}
+    wc_map: dict[str, int] = {}
+    def _group_sort_key(group: tuple[str, list[str]]) -> tuple[int, float]:
+        _, names = group
+        best = max(names, key=lambda n: _var_mean(ds, n))
+        return (0 if best in preferred else 1, -_var_mean(ds, best))
+
+    ordered_vars = [
+        n for _, names in sorted(groups, key=_group_sort_key)
+        for n in sorted(names, key=lambda n: 0 if n in preferred else 1)
+    ]
+
+    for name in ordered_vars:
+        wavelength_dim = _dimension_with_prefix(ds[name], "d_Wavelength")
+        if wavelength_dim:
+            wc_map[name] = wc
+            wc += len(ds[name].coords[wavelength_dim].values)
+        else:
+            vc_map[name] = vc
+            vc += 1
+
+    station = ds.attrs.get("ebas_station_name", ds.attrs.get("site_name", ""))
+    return [
+        plot_timeseries(ds, subset_vars=vars_,
+                        title=f"{lbl} at {station}" if station else lbl,
+                        var_color_offsets={n: vc_map[n] for n in vars_ if n in vc_map},
+                        wl_color_offsets={n: wc_map[n] for n in vars_ if n in wc_map},
+                        mode=mode)
+        for lbl, vars_ in groups
+    ]
+
+
+def plot(url: str, var_plots: bool = False, mode: str | None = None) -> "go.Figure | list[go.Figure]":
+    """Open a dataset and dispatch to the appropriate plot function.
+
+    Args:
+        var_plots: When True, return a list of figures — one per physical
+            quantity — instead of a single combined figure.
+        mode: 'line' or 'scatter' to force a plot mode on standard timeseries plots
+            (ignored for PNSD heatmap plots). If None, it's chosen automatically.
+    """
+    ds = open_dataset(url)
+    if "d_D" in ds.dims or "d_D" in ds.coords:
+        return plot_pnsd(ds)
+    if var_plots:
+        return plot_timeseries_per_var(ds, mode=mode)
+    return plot_timeseries(ds, mode=mode)
+
+
+def main() -> None:
+    """Run the command-line interface."""
+    import sys
+    args = sys.argv[1:]
+    var_plots = "--var_plots" in args
+    args = [a for a in args if a != "--var_plots"]
+    mode = None
+    if "--mode" in args:
+        i = args.index("--mode")
+        if i + 1 >= len(args):
+            raise ValueError("--mode requires 'line' or 'scatter'")
+        mode = args[i + 1]
+        args = args[:i] + args[i + 2:]
+    url = args[0] if args else "https://doi.nilu.no/doi/4VU2-MCJG"
+    result = plot(url, var_plots=var_plots, mode=mode)
+    if isinstance(result, list):
+        for fig in result:
+            fig.show()
+    else:
+        result.show()
+
+
+if __name__ == "__main__":
+    main()