ebas-plot 0.1.5__tar.gz → 0.2.0__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.2.0
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.2.0
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.2.0"
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:
@@ -207,9 +257,19 @@ def _dataset_title(ds: xr.Dataset) -> str:
207
257
  return station or "Unknown Site"
208
258
 
209
259
 
210
- def _var_mean(ds: xr.Dataset, name: str) -> float:
260
+ def _var_mean(
261
+ ds: xr.Dataset,
262
+ name: str,
263
+ data_cache: dict[str, np.ndarray] | None = None,
264
+ ) -> float:
211
265
  """Mean of finite values, used as a sort key."""
212
- vals = ds[name].values.ravel()
266
+ if data_cache is not None and name in data_cache:
267
+ values = data_cache[name]
268
+ else:
269
+ values = ds[name].values
270
+ if data_cache is not None:
271
+ data_cache[name] = values
272
+ vals = values.ravel()
213
273
  finite = vals[np.isfinite(vals)]
214
274
  return float(finite.mean()) if len(finite) else 0.0
215
275
 
@@ -286,7 +346,10 @@ def _dimension_with_prefix(da: xr.DataArray, prefix: str) -> str | None:
286
346
  return next((dim for dim in da.dims if dim == prefix or dim.startswith(f"{prefix}_")), None)
287
347
 
288
348
 
289
- def _plot_vars(ds: xr.Dataset) -> list[str]:
349
+ def _plot_vars(
350
+ ds: xr.Dataset,
351
+ data_cache: dict[str, np.ndarray] | None = None,
352
+ ) -> list[str]:
290
353
  """Return measurement variable names to plot for a timeseries dataset.
291
354
 
292
355
  Excludes auxiliary variables, percentile statistics, all-missing variables,
@@ -316,7 +379,13 @@ def _plot_vars(ds: xr.Dataset) -> list[str]:
316
379
  for d in ds[name].dims
317
380
  ):
318
381
  continue
319
- if not np.isfinite(ds[name].values).any():
382
+ if data_cache is not None and name in data_cache:
383
+ values = data_cache[name]
384
+ else:
385
+ values = ds[name].values
386
+ if data_cache is not None:
387
+ data_cache[name] = values
388
+ if not np.isfinite(values).any():
320
389
  continue
321
390
  result.append(name)
322
391
 
@@ -361,27 +430,6 @@ def _group_vars_by_physical_quantity(ds: xr.Dataset, plot_vars: list[str]) -> li
361
430
  return list(groups.items())
362
431
 
363
432
 
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
433
  def plot_pnsd(ds: xr.Dataset) -> go.Figure:
386
434
  """Plot particle number size distribution (PNSD) as a heatmap."""
387
435
  var_name = _pnsd_var(ds)
@@ -403,11 +451,6 @@ def plot_pnsd(ds: xr.Dataset) -> go.Figure:
403
451
  x_time = get_plot_time(ds)
404
452
  y_d = ds["d_D"].values
405
453
 
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
454
  # Fixed logarithmic scale from -1.0 to 5.0 with 0.2 interval; APS instruments cap lower (max 3.0).
412
455
  log_min = -1.0
413
456
  log_max = 3.0 if ds.attrs.get("ebas_instrument_type", "").strip().lower() == "aps" else 5.0
@@ -605,6 +648,7 @@ def plot_timeseries(
605
648
  var_color_offsets: dict[str, int] | None = None,
606
649
  wl_color_offsets: dict[str, int] | None = None,
607
650
  mode: str | None = None,
651
+ _data_cache: dict[str, np.ndarray] | None = None,
608
652
  ) -> go.Figure:
609
653
  """Plot timeseries variables in a single plot, grouped by variable in the legend.
610
654
 
@@ -629,7 +673,8 @@ def plot_timeseries(
629
673
  f"Dataset coordinates: {list(ds.coords)}"
630
674
  )
631
675
 
632
- plot_vars = subset_vars if subset_vars is not None else _plot_vars(ds)
676
+ data_cache = _data_cache if _data_cache is not None else {}
677
+ plot_vars = subset_vars if subset_vars is not None else _plot_vars(ds, data_cache)
633
678
  if not plot_vars:
634
679
  raise ValueError(
635
680
  "No plottable variables found (expected 'v_*' mean variables). "
@@ -637,7 +682,11 @@ def plot_timeseries(
637
682
  )
638
683
 
639
684
  # Pre-load all variable data once to avoid redundant OPeNDAP reads during sort, gap computation, and trace emission.
640
- _var_data: dict[str, np.ndarray] = {n: ds[n].values for n in plot_vars}
685
+ _var_data: dict[str, np.ndarray] = {}
686
+ for name in plot_vars:
687
+ if name not in data_cache:
688
+ data_cache[name] = ds[name].values
689
+ _var_data[name] = data_cache[name]
641
690
 
642
691
  # Detect whether all variables share the same unit; if so use flat legend style
643
692
  all_units = [_var_unit(ds, n) for n in plot_vars]
@@ -718,8 +767,9 @@ def plot_timeseries(
718
767
  wavelength_dim = _dimension_with_prefix(da, "d_Wavelength")
719
768
  if wavelength_dim:
720
769
  wl_values = da.coords[wavelength_dim].values
721
- for color, wl in zip(_wl_colors(name, len(wl_values)), wl_values):
722
- y = da.sel({wavelength_dim: wl}).values.copy()
770
+ wavelength_axis = da.get_axis_num(wavelength_dim)
771
+ for wavelength_index, (color, wl) in enumerate(zip(_wl_colors(name, len(wl_values)), wl_values)):
772
+ y = np.take(_var_data[name], wavelength_index, axis=wavelength_axis).copy()
723
773
  _add_timeseries_trace(fig, x_time=x_time, y=y, name=f"{float(wl):.1f} nm",
724
774
  color=color, legendgroup=group_title,
725
775
  use_scatter=use_scatter, hovertexts=hovertexts,
@@ -729,11 +779,12 @@ def plot_timeseries(
729
779
  elif "d_Tower_inlet_height" in da.dims:
730
780
  base_color = _var_color(name, _CUSTOM_COLORS_VARIABLES)
731
781
  height_values = da.coords["d_Tower_inlet_height"].values
782
+ height_axis = da.get_axis_num("d_Tower_inlet_height")
732
783
  n_heights = len(height_values)
733
784
  opacities = [1.0 - (i / max(n_heights - 1, 1)) * 0.65 for i in range(n_heights)]
734
785
  for h_idx, height in enumerate(height_values):
735
786
  color = _hex_to_rgba(base_color, opacities[h_idx])
736
- y = da.sel(d_Tower_inlet_height=height).values.copy()
787
+ y = np.take(_var_data[name], h_idx, axis=height_axis).copy()
737
788
  _add_timeseries_trace(fig, x_time=x_time, y=y, name=f"h\u1d35\u2099\u1d35={height:.0f}m",
738
789
  color=color, legendgroup=group_title,
739
790
  use_scatter=use_scatter, hovertexts=hovertexts,
@@ -804,13 +855,19 @@ def plot_timeseries(
804
855
  return fig
805
856
 
806
857
 
807
- def plot_timeseries_per_var(ds: xr.Dataset, *, mode: str | None = None) -> list[go.Figure]:
858
+ def plot_timeseries_per_var(
859
+ ds: xr.Dataset,
860
+ *,
861
+ mode: str | None = None,
862
+ _data_cache: dict[str, np.ndarray] | None = None,
863
+ ) -> list[go.Figure]:
808
864
  """Return one figure per physical quantity, preserving combined-plot colors.
809
865
 
810
866
  Variables with the same base name but different units are grouped together.
811
867
  Falls back to a single combined figure when there is only one group.
812
868
  """
813
- plot_vars = _plot_vars(ds)
869
+ data_cache = _data_cache if _data_cache is not None else {}
870
+ plot_vars = _plot_vars(ds, data_cache)
814
871
  if not plot_vars:
815
872
  raise ValueError(
816
873
  "No plottable variables found (expected 'v_*' mean variables). "
@@ -818,7 +875,7 @@ def plot_timeseries_per_var(ds: xr.Dataset, *, mode: str | None = None) -> list[
818
875
  )
819
876
  groups = _group_vars_by_physical_quantity(ds, plot_vars)
820
877
  if len(groups) <= 1:
821
- return [plot_timeseries(ds, mode=mode)]
878
+ return [plot_timeseries(ds, mode=mode, _data_cache=data_cache)]
822
879
 
823
880
  # Walk the same sorted order as the combined plot to build per-variable color offsets.
824
881
  all_units = {_var_unit(ds, n) for n in plot_vars}
@@ -832,8 +889,8 @@ def plot_timeseries_per_var(ds: xr.Dataset, *, mode: str | None = None) -> list[
832
889
  wc_map: dict[str, int] = {}
833
890
  def _group_sort_key(group: tuple[str, list[str]]) -> tuple[int, float]:
834
891
  _, names = group
835
- best = max(names, key=lambda n: _var_mean(ds, n))
836
- return (0 if best in preferred else 1, -_var_mean(ds, best))
892
+ best = max(names, key=lambda n: _var_mean(ds, n, data_cache))
893
+ return (0 if best in preferred else 1, -_var_mean(ds, best, data_cache))
837
894
 
838
895
  ordered_vars = [
839
896
  n for _, names in sorted(groups, key=_group_sort_key)
@@ -855,12 +912,18 @@ def plot_timeseries_per_var(ds: xr.Dataset, *, mode: str | None = None) -> list[
855
912
  title=f"{lbl} at {station}" if station else lbl,
856
913
  var_color_offsets={n: vc_map[n] for n in vars_ if n in vc_map},
857
914
  wl_color_offsets={n: wc_map[n] for n in vars_ if n in wc_map},
858
- mode=mode)
915
+ mode=mode,
916
+ _data_cache=data_cache)
859
917
  for lbl, vars_ in groups
860
918
  ]
861
919
 
862
920
 
863
- def plot(url: str, var_plots: bool = False, mode: str | None = None) -> "go.Figure | list[go.Figure]":
921
+ def plot(
922
+ url: str,
923
+ var_plots: bool = False,
924
+ mode: str | None = None,
925
+ time: "str | TimeRange | None" = None,
926
+ ) -> "go.Figure | list[go.Figure]":
864
927
  """Open a dataset and dispatch to the appropriate plot function.
865
928
 
866
929
  Args:
@@ -868,8 +931,10 @@ def plot(url: str, var_plots: bool = False, mode: str | None = None) -> "go.Figu
868
931
  quantity — instead of a single combined figure.
869
932
  mode: 'line' or 'scatter' to force a plot mode on standard timeseries plots
870
933
  (ignored for PNSD heatmap plots). If None, it's chosen automatically.
934
+ time: Optional inclusive time range, '[START,END]' or (start, end) ISO dates;
935
+ either side may be empty/None. If omitted, the whole dataset is plotted.
871
936
  """
872
- ds = open_dataset(url)
937
+ ds = open_dataset(url, time=time)
873
938
  if "d_D" in ds.dims or "d_D" in ds.coords:
874
939
  return plot_pnsd(ds)
875
940
  if var_plots:
@@ -883,15 +948,26 @@ def main() -> None:
883
948
  args = sys.argv[1:]
884
949
  var_plots = "--var_plots" in args
885
950
  args = [a for a in args if a != "--var_plots"]
886
- mode = None
887
- if "--mode" in args:
888
- i = args.index("--mode")
951
+
952
+ def _pop_option(flag: str) -> str | None:
953
+ nonlocal args
954
+ if flag not in args:
955
+ return None
956
+ i = args.index(flag)
889
957
  if i + 1 >= len(args):
890
- raise ValueError("--mode requires 'line' or 'scatter'")
891
- mode = args[i + 1]
958
+ raise ValueError(f"{flag} requires a value")
959
+ value = args[i + 1]
892
960
  args = args[:i] + args[i + 2:]
961
+ return value
962
+
963
+ mode = _pop_option("--mode")
964
+ try:
965
+ time = _pop_option("--time")
966
+ time = None if time is None else parse_time_range(time)
967
+ except ValueError as exc:
968
+ sys.exit(f"ERROR: {exc}" if TIME_FORMAT_HELP in str(exc) else f"ERROR: {exc}\n{TIME_FORMAT_HELP}")
893
969
  url = args[0] if args else "https://doi.nilu.no/doi/4VU2-MCJG"
894
- result = plot(url, var_plots=var_plots, mode=mode)
970
+ result = plot(url, var_plots=var_plots, mode=mode, time=time)
895
971
  if isinstance(result, list):
896
972
  for fig in result:
897
973
  fig.show()
File without changes
File without changes
File without changes