ebas-plot 0.1.5__tar.gz → 0.1.6__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ebas-plot
3
- Version: 0.1.5
3
+ Version: 0.1.6
4
4
  Summary: Plotting utilities for EBAS netCDF datasets.
5
5
  Author-email: Lise Eder Murberg <lemu@nilu.no>, Marthe Brevig <mbre@nilu.no>, Jonathan Elias Holme <jhol@nilu.no>
6
6
  License-Expression: AGPL-3.0-or-later
@@ -69,6 +69,16 @@ Choose the time-series rendering explicitly with `--mode line` or
69
69
  ebas-plot --mode scatter /path/to/dataset.nc
70
70
  ```
71
71
 
72
+ Limit the plotted time range with `--time "[START,END]"` (inclusive ISO
73
+ dates/times; leave one side empty for an open-ended range, e.g.
74
+ `"[2020-01-01,]"`). When omitted, the whole dataset is plotted. For remote
75
+ datasets only the selected range is fetched over OPeNDAP. An invalid format
76
+ prints the expected format and exits:
77
+
78
+ ```bash
79
+ ebas-plot --time "[2020-01-01,2020-12-31]" https://doi.nilu.no/doi/8HWP-FRNN
80
+ ```
81
+
72
82
  Use `--var_plots` to open one plot per physical quantity rather than one
73
83
  combined time-series plot:
74
84
 
@@ -94,6 +104,10 @@ fig.show()
94
104
  figures = plot("https://doi.nilu.no/doi/8HWP-FRNN", var_plots=True, mode="line")
95
105
  for figure in figures:
96
106
  figure.show()
107
+
108
+ # Only fetch and plot 2020 (whole dataset if time is omitted).
109
+ fig = plot("https://doi.nilu.no/doi/8HWP-FRNN", time="[2020-01-01,2020-12-31]")
110
+ ds = open_dataset("https://doi.nilu.no/doi/8HWP-FRNN", time=("2020-01-01", None))
97
111
  ```
98
112
 
99
113
  ## License
@@ -40,6 +40,16 @@ Choose the time-series rendering explicitly with `--mode line` or
40
40
  ebas-plot --mode scatter /path/to/dataset.nc
41
41
  ```
42
42
 
43
+ Limit the plotted time range with `--time "[START,END]"` (inclusive ISO
44
+ dates/times; leave one side empty for an open-ended range, e.g.
45
+ `"[2020-01-01,]"`). When omitted, the whole dataset is plotted. For remote
46
+ datasets only the selected range is fetched over OPeNDAP. An invalid format
47
+ prints the expected format and exits:
48
+
49
+ ```bash
50
+ ebas-plot --time "[2020-01-01,2020-12-31]" https://doi.nilu.no/doi/8HWP-FRNN
51
+ ```
52
+
43
53
  Use `--var_plots` to open one plot per physical quantity rather than one
44
54
  combined time-series plot:
45
55
 
@@ -65,6 +75,10 @@ fig.show()
65
75
  figures = plot("https://doi.nilu.no/doi/8HWP-FRNN", var_plots=True, mode="line")
66
76
  for figure in figures:
67
77
  figure.show()
78
+
79
+ # Only fetch and plot 2020 (whole dataset if time is omitted).
80
+ fig = plot("https://doi.nilu.no/doi/8HWP-FRNN", time="[2020-01-01,2020-12-31]")
81
+ ds = open_dataset("https://doi.nilu.no/doi/8HWP-FRNN", time=("2020-01-01", None))
68
82
  ```
69
83
 
70
84
  ## License
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ebas-plot
3
- Version: 0.1.5
3
+ Version: 0.1.6
4
4
  Summary: Plotting utilities for EBAS netCDF datasets.
5
5
  Author-email: Lise Eder Murberg <lemu@nilu.no>, Marthe Brevig <mbre@nilu.no>, Jonathan Elias Holme <jhol@nilu.no>
6
6
  License-Expression: AGPL-3.0-or-later
@@ -69,6 +69,16 @@ Choose the time-series rendering explicitly with `--mode line` or
69
69
  ebas-plot --mode scatter /path/to/dataset.nc
70
70
  ```
71
71
 
72
+ Limit the plotted time range with `--time "[START,END]"` (inclusive ISO
73
+ dates/times; leave one side empty for an open-ended range, e.g.
74
+ `"[2020-01-01,]"`). When omitted, the whole dataset is plotted. For remote
75
+ datasets only the selected range is fetched over OPeNDAP. An invalid format
76
+ prints the expected format and exits:
77
+
78
+ ```bash
79
+ ebas-plot --time "[2020-01-01,2020-12-31]" https://doi.nilu.no/doi/8HWP-FRNN
80
+ ```
81
+
72
82
  Use `--var_plots` to open one plot per physical quantity rather than one
73
83
  combined time-series plot:
74
84
 
@@ -94,6 +104,10 @@ fig.show()
94
104
  figures = plot("https://doi.nilu.no/doi/8HWP-FRNN", var_plots=True, mode="line")
95
105
  for figure in figures:
96
106
  figure.show()
107
+
108
+ # Only fetch and plot 2020 (whole dataset if time is omitted).
109
+ fig = plot("https://doi.nilu.no/doi/8HWP-FRNN", time="[2020-01-01,2020-12-31]")
110
+ ds = open_dataset("https://doi.nilu.no/doi/8HWP-FRNN", time=("2020-01-01", None))
97
111
  ```
98
112
 
99
113
  ## License
@@ -4,10 +4,10 @@ import xarray as xr
4
4
  import plotly.graph_objects as go
5
5
  import numpy as np
6
6
  import requests
7
- from netCDF4 import num2date
7
+ from netCDF4 import date2num, num2date
8
8
  import pandas as pd
9
9
 
10
- __version__ = "0.1.5"
10
+ __version__ = "0.1.6"
11
11
 
12
12
 
13
13
  class DatasetAccessError(Exception):
@@ -130,8 +130,58 @@ def _doi_to_opendap_url(doi: str) -> str:
130
130
  return f"https://thredds.nilu.no/thredds/dodsC/ebas_doi/{s[0:2]}/{s[2:4]}/{s[4:6]}/{doi}.nc"
131
131
 
132
132
 
133
- def open_dataset(url: str, token: str | None = None) -> xr.Dataset:
134
- """Open an EBAS dataset from a local .nc path, DOI, or THREDDS URL."""
133
+ TIME_FORMAT_HELP = (
134
+ 'Time range must be [START,END] with ISO dates/times, e.g. --time "[2020-01-01,2020-12-31]"\n'
135
+ 'or "[2020-01-01T06:00,2020-03-01]". Leave a side empty for open-ended: "[2020-01-01,]".'
136
+ )
137
+
138
+ TimeRange = tuple[str | None, str | None]
139
+
140
+ _ISO_RE = re.compile(r"\d{4}(-\d\d(-\d\d([T ]\d\d(:\d\d(:\d\d(\.\d+)?)?)?)?)?)?") # naive UTC, as in EBAS files
141
+
142
+
143
+ def parse_time_range(value: "str | TimeRange") -> TimeRange:
144
+ """Parse '[START,END]' or (start, end) into validated ISO bounds; empty/None means open-ended."""
145
+ parts = value.strip(" []").split(",") if isinstance(value, str) else value
146
+ bounds = tuple(None if p is None else str(p).strip() or None for p in parts)
147
+ try:
148
+ if len(bounds) != 2 or not all(b is None or _ISO_RE.fullmatch(b) for b in bounds):
149
+ raise ValueError
150
+ lo, hi = (b and pd.Timestamp(b) for b in bounds)
151
+ if lo and hi and lo > hi:
152
+ raise ValueError
153
+ except ValueError:
154
+ raise ValueError(f"Invalid time range {value!r}.\n{TIME_FORMAT_HELP}") from None
155
+ return bounds
156
+
157
+
158
+ def _slice_time(ds: xr.Dataset, start: str | None, end: str | None) -> xr.Dataset:
159
+ """Lazily select [start, end] before any `.values` read so OPeNDAP only fetches that range."""
160
+ t = ds["time"]
161
+ if np.issubdtype(t.dtype, np.number) and "units" in t.attrs: # opened with decode_times=False
162
+ start, end = (v and date2num(pd.Timestamp(v).to_pydatetime(), t.attrs["units"], t.attrs.get("calendar", "standard"))
163
+ for v in (start, end))
164
+ ds = ds.sel(time=slice(start, end))
165
+ if not ds.sizes.get("time"):
166
+ raise ValueError("No data in the requested time range")
167
+ return ds
168
+
169
+
170
+ def open_dataset(
171
+ url: str,
172
+ token: str | None = None,
173
+ time: "str | TimeRange | None" = None,
174
+ ) -> xr.Dataset:
175
+ """Open an EBAS dataset from a local .nc path, DOI, or THREDDS URL.
176
+
177
+ `time` ('[START,END]' or (start, end), inclusive ISO dates) restricts the range; None means the whole dataset.
178
+ """
179
+ bounds = (None, None) if time is None else parse_time_range(time) # validate before any remote open
180
+ ds = _open_dataset(url, token)
181
+ return _slice_time(ds, *bounds) if any(bounds) else ds
182
+
183
+
184
+ def _open_dataset(url: str, token: str | None) -> xr.Dataset:
135
185
  if not url.startswith("http"): # local file
136
186
  ds = validate_dataset(url)
137
187
  if ds is None:
@@ -361,27 +411,6 @@ def _group_vars_by_physical_quantity(ds: xr.Dataset, plot_vars: list[str]) -> li
361
411
  return list(groups.items())
362
412
 
363
413
 
364
- def _break_heatmap_time_gaps(x_time: np.ndarray, z: np.ndarray, gap_multiplier: float = 3.0) -> tuple[np.ndarray, np.ndarray]:
365
- """Insert a NaN sentinel column at each large x_time gap.
366
-
367
- Plotly's Heatmap draws a cell spanning the midpoint to each of its
368
- neighbors, so a single big jump in x (e.g. a real data outage of weeks or
369
- months) gets rendered as one wide cell stretching the surrounding color
370
- across the whole gap instead of leaving it blank. Inserting a NaN column
371
- at the gap's midpoint gives Plotly a blank cell to render there instead.
372
- """
373
- times = pd.DatetimeIndex(x_time)
374
- diffs = np.diff(times)
375
- if not len(diffs) or (median_step := np.median(diffs)) <= pd.Timedelta(0):
376
- return x_time, z
377
- gap_idx = np.flatnonzero(diffs > gap_multiplier * median_step) + 1
378
- if not len(gap_idx):
379
- return x_time, z
380
- midpoints = times[gap_idx - 1] + diffs[gap_idx - 1] / 2
381
- return (np.insert(np.asarray(x_time), gap_idx, midpoints),
382
- np.insert(z, gap_idx, np.nan, axis=1))
383
-
384
-
385
414
  def plot_pnsd(ds: xr.Dataset) -> go.Figure:
386
415
  """Plot particle number size distribution (PNSD) as a heatmap."""
387
416
  var_name = _pnsd_var(ds)
@@ -403,11 +432,6 @@ def plot_pnsd(ds: xr.Dataset) -> go.Figure:
403
432
  x_time = get_plot_time(ds)
404
433
  y_d = ds["d_D"].values
405
434
 
406
- # Heatmap stretches a single cell across any large gap in x rather than
407
- # leaving it blank; insert a NaN sentinel column at the gap midpoint so
408
- # Plotly renders the gap as blank instead of smearing the boundary color.
409
- x_time, z = _break_heatmap_time_gaps(x_time, z)
410
-
411
435
  # Fixed logarithmic scale from -1.0 to 5.0 with 0.2 interval; APS instruments cap lower (max 3.0).
412
436
  log_min = -1.0
413
437
  log_max = 3.0 if ds.attrs.get("ebas_instrument_type", "").strip().lower() == "aps" else 5.0
@@ -860,7 +884,12 @@ def plot_timeseries_per_var(ds: xr.Dataset, *, mode: str | None = None) -> list[
860
884
  ]
861
885
 
862
886
 
863
- def plot(url: str, var_plots: bool = False, mode: str | None = None) -> "go.Figure | list[go.Figure]":
887
+ def plot(
888
+ url: str,
889
+ var_plots: bool = False,
890
+ mode: str | None = None,
891
+ time: "str | TimeRange | None" = None,
892
+ ) -> "go.Figure | list[go.Figure]":
864
893
  """Open a dataset and dispatch to the appropriate plot function.
865
894
 
866
895
  Args:
@@ -868,8 +897,10 @@ def plot(url: str, var_plots: bool = False, mode: str | None = None) -> "go.Figu
868
897
  quantity — instead of a single combined figure.
869
898
  mode: 'line' or 'scatter' to force a plot mode on standard timeseries plots
870
899
  (ignored for PNSD heatmap plots). If None, it's chosen automatically.
900
+ time: Optional inclusive time range, '[START,END]' or (start, end) ISO dates;
901
+ either side may be empty/None. If omitted, the whole dataset is plotted.
871
902
  """
872
- ds = open_dataset(url)
903
+ ds = open_dataset(url, time=time)
873
904
  if "d_D" in ds.dims or "d_D" in ds.coords:
874
905
  return plot_pnsd(ds)
875
906
  if var_plots:
@@ -883,15 +914,26 @@ def main() -> None:
883
914
  args = sys.argv[1:]
884
915
  var_plots = "--var_plots" in args
885
916
  args = [a for a in args if a != "--var_plots"]
886
- mode = None
887
- if "--mode" in args:
888
- i = args.index("--mode")
917
+
918
+ def _pop_option(flag: str) -> str | None:
919
+ nonlocal args
920
+ if flag not in args:
921
+ return None
922
+ i = args.index(flag)
889
923
  if i + 1 >= len(args):
890
- raise ValueError("--mode requires 'line' or 'scatter'")
891
- mode = args[i + 1]
924
+ raise ValueError(f"{flag} requires a value")
925
+ value = args[i + 1]
892
926
  args = args[:i] + args[i + 2:]
927
+ return value
928
+
929
+ mode = _pop_option("--mode")
930
+ try:
931
+ time = _pop_option("--time")
932
+ time = None if time is None else parse_time_range(time)
933
+ except ValueError as exc:
934
+ sys.exit(f"ERROR: {exc}" if TIME_FORMAT_HELP in str(exc) else f"ERROR: {exc}\n{TIME_FORMAT_HELP}")
893
935
  url = args[0] if args else "https://doi.nilu.no/doi/4VU2-MCJG"
894
- result = plot(url, var_plots=var_plots, mode=mode)
936
+ result = plot(url, var_plots=var_plots, mode=mode, time=time)
895
937
  if isinstance(result, list):
896
938
  for fig in result:
897
939
  fig.show()
File without changes
File without changes
File without changes