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.
- {ebas_plot-0.1.5 → ebas_plot-0.1.6}/PKG-INFO +15 -1
- {ebas_plot-0.1.5 → ebas_plot-0.1.6}/README.md +14 -0
- {ebas_plot-0.1.5 → ebas_plot-0.1.6}/ebas_plot.egg-info/PKG-INFO +15 -1
- {ebas_plot-0.1.5 → ebas_plot-0.1.6}/ebas_plot.py +80 -38
- {ebas_plot-0.1.5 → ebas_plot-0.1.6}/LICENSE +0 -0
- {ebas_plot-0.1.5 → ebas_plot-0.1.6}/ebas_plot.egg-info/SOURCES.txt +0 -0
- {ebas_plot-0.1.5 → ebas_plot-0.1.6}/ebas_plot.egg-info/dependency_links.txt +0 -0
- {ebas_plot-0.1.5 → ebas_plot-0.1.6}/ebas_plot.egg-info/entry_points.txt +0 -0
- {ebas_plot-0.1.5 → ebas_plot-0.1.6}/ebas_plot.egg-info/requires.txt +0 -0
- {ebas_plot-0.1.5 → ebas_plot-0.1.6}/ebas_plot.egg-info/top_level.txt +0 -0
- {ebas_plot-0.1.5 → ebas_plot-0.1.6}/pyproject.toml +0 -0
- {ebas_plot-0.1.5 → ebas_plot-0.1.6}/setup.cfg +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: ebas-plot
|
|
3
|
-
Version: 0.1.
|
|
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.
|
|
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.
|
|
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
|
-
|
|
134
|
-
|
|
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(
|
|
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
|
-
|
|
887
|
-
|
|
888
|
-
|
|
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("
|
|
891
|
-
|
|
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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|