ebas-plot 0.1.4__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.4
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.4
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.4"
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:
@@ -402,11 +452,7 @@ def plot_pnsd(ds: xr.Dataset) -> go.Figure:
402
452
  z=z,
403
453
  zmin=log_min,
404
454
  zmax=log_max,
405
- # False renders each cell as its own actual value; 'best' smooths/
406
- # interpolates between cells, which can paint spurious solid-color
407
- # blocks at data gaps or resolution boundaries that don't match
408
- # the underlying data (confirmed via hover z-value mismatch).
409
- zsmooth=False,
455
+ zsmooth='best',
410
456
  colorscale=plotly_discrete_colorscale,
411
457
  showscale=True,
412
458
  colorbar=dict(
@@ -838,7 +884,12 @@ def plot_timeseries_per_var(ds: xr.Dataset, *, mode: str | None = None) -> list[
838
884
  ]
839
885
 
840
886
 
841
- 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]":
842
893
  """Open a dataset and dispatch to the appropriate plot function.
843
894
 
844
895
  Args:
@@ -846,8 +897,10 @@ def plot(url: str, var_plots: bool = False, mode: str | None = None) -> "go.Figu
846
897
  quantity — instead of a single combined figure.
847
898
  mode: 'line' or 'scatter' to force a plot mode on standard timeseries plots
848
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.
849
902
  """
850
- ds = open_dataset(url)
903
+ ds = open_dataset(url, time=time)
851
904
  if "d_D" in ds.dims or "d_D" in ds.coords:
852
905
  return plot_pnsd(ds)
853
906
  if var_plots:
@@ -861,15 +914,26 @@ def main() -> None:
861
914
  args = sys.argv[1:]
862
915
  var_plots = "--var_plots" in args
863
916
  args = [a for a in args if a != "--var_plots"]
864
- mode = None
865
- if "--mode" in args:
866
- 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)
867
923
  if i + 1 >= len(args):
868
- raise ValueError("--mode requires 'line' or 'scatter'")
869
- mode = args[i + 1]
924
+ raise ValueError(f"{flag} requires a value")
925
+ value = args[i + 1]
870
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}")
871
935
  url = args[0] if args else "https://doi.nilu.no/doi/4VU2-MCJG"
872
- result = plot(url, var_plots=var_plots, mode=mode)
936
+ result = plot(url, var_plots=var_plots, mode=mode, time=time)
873
937
  if isinstance(result, list):
874
938
  for fig in result:
875
939
  fig.show()
File without changes
File without changes
File without changes