multigas 0.1.0__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.
- multigas-0.2.0/PKG-INFO +517 -0
- multigas-0.2.0/README.md +465 -0
- {multigas-0.1.0 → multigas-0.2.0}/pyproject.toml +11 -1
- multigas-0.2.0/src/multigas/cli/__init__.py +1 -0
- multigas-0.2.0/src/multigas/cli/commands/__init__.py +1 -0
- multigas-0.2.0/src/multigas/cli/commands/extract.py +131 -0
- multigas-0.2.0/src/multigas/cli/commands/normalize.py +101 -0
- multigas-0.2.0/src/multigas/cli/commands/plot.py +201 -0
- multigas-0.2.0/src/multigas/cli/main.py +18 -0
- {multigas-0.1.0 → multigas-0.2.0}/src/multigas/core/__init__.py +0 -2
- multigas-0.2.0/src/multigas/core/constant.py +391 -0
- {multigas-0.1.0 → multigas-0.2.0}/src/multigas/core/io.py +9 -1
- {multigas-0.1.0 → multigas-0.2.0}/src/multigas/core/query.py +252 -27
- {multigas-0.1.0 → multigas-0.2.0}/src/multigas/core/types.py +96 -52
- {multigas-0.1.0 → multigas-0.2.0}/src/multigas/data/__init__.py +6 -2
- {multigas-0.1.0 → multigas-0.2.0}/src/multigas/data/loader.py +82 -81
- multigas-0.2.0/src/multigas/data/multigas_data.py +651 -0
- multigas-0.2.0/src/multigas/plot/__init__.py +59 -0
- multigas-0.2.0/src/multigas/plot/columns.py +503 -0
- multigas-0.2.0/src/multigas/plot/dimensions.py +232 -0
- multigas-0.2.0/src/multigas/plot/plot.py +234 -0
- multigas-0.2.0/src/multigas/plot/plot_completeness.py +88 -0
- multigas-0.2.0/src/multigas/plot/six_hours.py +844 -0
- {multigas-0.1.0 → multigas-0.2.0}/src/multigas/utils/cache.py +85 -20
- multigas-0.2.0/src/multigas/utils/dataframe.py +388 -0
- {multigas-0.1.0 → multigas-0.2.0}/src/multigas/utils/validation.py +3 -6
- multigas-0.1.0/PKG-INFO +0 -175
- multigas-0.1.0/README.md +0 -130
- multigas-0.1.0/src/multigas/utils/dataframe.py +0 -79
- {multigas-0.1.0 → multigas-0.2.0}/LICENSE +0 -0
- {multigas-0.1.0 → multigas-0.2.0}/src/multigas/__init__.py +0 -0
- {multigas-0.1.0 → multigas-0.2.0}/src/multigas/config/__init__.py +0 -0
- {multigas-0.1.0 → multigas-0.2.0}/src/multigas/core/exceptions.py +0 -0
- {multigas-0.1.0 → multigas-0.2.0}/src/multigas/logging.py +0 -0
- {multigas-0.1.0 → multigas-0.2.0}/src/multigas/utils/__init__.py +0 -0
- {multigas-0.1.0 → multigas-0.2.0}/src/multigas/utils/path.py +0 -0
multigas-0.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,517 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: multigas
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Python package for multigas sensor
|
|
5
|
+
Keywords: multigas,volcano,gas,sensor,monitoring
|
|
6
|
+
Author: Martanto
|
|
7
|
+
Author-email: Martanto <martanto@live.com>
|
|
8
|
+
License: MIT License
|
|
9
|
+
|
|
10
|
+
Copyright (c) 2026 Martanto
|
|
11
|
+
|
|
12
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
13
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
14
|
+
in the Software without restriction, including without limitation the rights
|
|
15
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
16
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
17
|
+
furnished to do so, subject to the following conditions:
|
|
18
|
+
|
|
19
|
+
The above copyright notice and this permission notice shall be included in all
|
|
20
|
+
copies or substantial portions of the Software.
|
|
21
|
+
|
|
22
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
23
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
24
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
25
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
26
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
27
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
28
|
+
SOFTWARE.
|
|
29
|
+
Classifier: Development Status :: 3 - Alpha
|
|
30
|
+
Classifier: Intended Audience :: Science/Research
|
|
31
|
+
Classifier: Operating System :: OS Independent
|
|
32
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
33
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
34
|
+
Requires-Dist: click>=8.2.1
|
|
35
|
+
Requires-Dist: bokeh>=3.6.0
|
|
36
|
+
Requires-Dist: data-availability>=0.3.1
|
|
37
|
+
Requires-Dist: joblib>=1.5.3
|
|
38
|
+
Requires-Dist: loguru>=0.7.3
|
|
39
|
+
Requires-Dist: matplotlib>=3.11.2
|
|
40
|
+
Requires-Dist: numpy>=2.4.4
|
|
41
|
+
Requires-Dist: openpyxl>=3.1.5
|
|
42
|
+
Requires-Dist: pandas>=3.0.2
|
|
43
|
+
Requires-Dist: pandas-stubs~=3.0.2
|
|
44
|
+
Requires-Dist: python-dotenv>=1.2.2
|
|
45
|
+
Requires-Dist: python-slugify>=9.1.1
|
|
46
|
+
Requires-Dist: rich>=14.0.0
|
|
47
|
+
Requires-Dist: seaborn>=0.13.2
|
|
48
|
+
Requires-Python: >=3.11
|
|
49
|
+
Project-URL: Homepage, https://github.com/martanto/multigas
|
|
50
|
+
Project-URL: Issues, https://github.com/martanto/multigas/issues
|
|
51
|
+
Description-Content-Type: text/markdown
|
|
52
|
+
|
|
53
|
+
# multigas
|
|
54
|
+
|
|
55
|
+
[](https://www.python.org/downloads/)
|
|
56
|
+
[](https://opensource.org/licenses/MIT)
|
|
57
|
+
|
|
58
|
+
**Python package for processing, analyzing, and visualizing multi-gas volcanic monitoring data.**
|
|
59
|
+
|
|
60
|
+
Developed through collaboration between CVGHM (Center for Volcanology and Geological Hazard Mitigation) and USGS for Campbell Scientific datalogger systems measuring volcanic gas emissions (CO2, SO2, H2S) and meteorological data.
|
|
61
|
+
|
|
62
|
+
The data is inherently **time-series**: every dataset is a stream of gas / calibration / weather readings sampled over time, and every DataFrame flowing through the package is expected to carry a `pd.DatetimeIndex`.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Documentation
|
|
67
|
+
|
|
68
|
+
Full documentation lives in the [`wiki/`](wiki/) directory — start at
|
|
69
|
+
[`wiki/Home.md`](wiki/Home.md).
|
|
70
|
+
|
|
71
|
+
| Page | Purpose |
|
|
72
|
+
|---|---|
|
|
73
|
+
| [Home](wiki/Home.md) | Overview, repository map, navigation, glossary |
|
|
74
|
+
| [Getting Started](wiki/Getting-Started.md) | Install, first load, fluent queries, wind analysis, dev workflow |
|
|
75
|
+
| [API Reference](wiki/API-Reference.md) | Public methods, signatures, and parameter tables |
|
|
76
|
+
| [CLI Reference](wiki/CLI-Reference.md) | Command-line commands, source locations, and argument details |
|
|
77
|
+
| [Queries](wiki/Queries.md) | Complete `Query` method index with argument types and defaults |
|
|
78
|
+
| [Data Columns](wiki/Data-Columns.md) | Per-column dictionary for the datalogger's TOA5 / CSV output — meaning, units, and onboard processing |
|
|
79
|
+
| [Wind Analysis](wiki/Wind-Analysis.md) | Sector / quadrant tables, bearing normalisation, `add_wind_direction` / `add_wind_quadrant` contracts |
|
|
80
|
+
| [Logging](wiki/Logging.md) | Sink layout, retention, runtime toggles, `ENABLE_LOG` contract |
|
|
81
|
+
| [Exceptions](wiki/Exceptions.md) | Hierarchy, auto-log behaviour, soft vs hard failures, catching patterns |
|
|
82
|
+
| [Multi-GAS plotting](wiki/Plot.md) | Six-hour and selected-column APIs, CLI, date filters, captions, and exports |
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## Installation
|
|
87
|
+
|
|
88
|
+
### Requirements
|
|
89
|
+
|
|
90
|
+
- Python 3.11 or higher
|
|
91
|
+
- Windows, macOS, or Linux
|
|
92
|
+
- [`uv`](https://docs.astral.sh/uv/) as the package manager (no `pip install` / `python -m pip`)
|
|
93
|
+
|
|
94
|
+
### Install with uv (recommended)
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
# Install uv package manager (one time, per machine)
|
|
98
|
+
# macOS / Linux:
|
|
99
|
+
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
100
|
+
# Windows (PowerShell):
|
|
101
|
+
# powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
|
|
102
|
+
|
|
103
|
+
# Clone repository
|
|
104
|
+
git clone https://github.com/martanto/multigas.git
|
|
105
|
+
cd multigas
|
|
106
|
+
|
|
107
|
+
# Install with all dependencies
|
|
108
|
+
uv sync
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
`uv sync` creates a virtual environment under `.venv/`. Activate it before
|
|
112
|
+
running Python directly (skip if you use `uv run`, which resolves the env
|
|
113
|
+
automatically):
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
# macOS / Linux
|
|
117
|
+
source .venv/bin/activate
|
|
118
|
+
|
|
119
|
+
# Windows (PowerShell)
|
|
120
|
+
.venv\Scripts\Activate.ps1
|
|
121
|
+
|
|
122
|
+
# Windows (cmd)
|
|
123
|
+
.venv\Scripts\activate.bat
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Deactivate with `deactivate` when done.
|
|
127
|
+
|
|
128
|
+
Verify:
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
uv run python -c "import multigas; print(multigas.__version__)"
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Full walkthrough: [`wiki/Getting-Started.md`](wiki/Getting-Started.md).
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## Quick start
|
|
139
|
+
|
|
140
|
+
Load a Campbell Scientific TOA5 (or plain CSV) file and get a `MultiGasData`
|
|
141
|
+
back — a DataFrame wrapper with fluent column-selection helpers.
|
|
142
|
+
|
|
143
|
+
```python
|
|
144
|
+
from multigas import read_file
|
|
145
|
+
|
|
146
|
+
ds = read_file("data/site_a.dat", dataset_type="1min")
|
|
147
|
+
|
|
148
|
+
ds.df.head() # underlying DataFrame (datetime-indexed)
|
|
149
|
+
ds.dataset_type # <DatasetType.ONE_MINUTE: '1min'>
|
|
150
|
+
ds.source_path # absolute path to the source file
|
|
151
|
+
ds.start_date_str # e.g. '2025-01-01'
|
|
152
|
+
ds.end_date_str # e.g. '2025-01-31'
|
|
153
|
+
ds.numeric_columns # numeric-dtype column names
|
|
154
|
+
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Need full control over paths, cache behaviour, or verbosity? Use `DataLoader`
|
|
158
|
+
directly:
|
|
159
|
+
|
|
160
|
+
```python
|
|
161
|
+
from multigas import DataLoader
|
|
162
|
+
|
|
163
|
+
loader = DataLoader(
|
|
164
|
+
output_dir="output",
|
|
165
|
+
cache_dir="output/cache",
|
|
166
|
+
overwrite=False,
|
|
167
|
+
verbose=True,
|
|
168
|
+
)
|
|
169
|
+
ds = loader.load("data/site_a.dat", dataset_type="1min")
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Both entry points serve from an on-disk `joblib` cache keyed by absolute path
|
|
173
|
+
plus mtime. Stale or corrupted entries are dropped transparently.
|
|
174
|
+
|
|
175
|
+
With the default `normalize=True`, loading also replaces `"NAN"` sentinels
|
|
176
|
+
with `NaN`, collapses duplicate timestamps (keeping the last row), coerces
|
|
177
|
+
numeric columns, and — for sampling-interval datasets (`1s`, `2s`, `1min`,
|
|
178
|
+
`6h`) — keeps only rows whose spacing matches the expected interval.
|
|
179
|
+
|
|
180
|
+
Every parameter is documented in [`wiki/API-Reference.md`](wiki/API-Reference.md).
|
|
181
|
+
|
|
182
|
+
### Command-line normalization
|
|
183
|
+
|
|
184
|
+
The `multigas normalize` command provides the same normalized load from a
|
|
185
|
+
terminal. It writes `<output-dir>/normalized/<source-stem>.csv`; the default
|
|
186
|
+
output root is `./output`.
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
uv run multigas normalize data/site_a.dat --dataset-type 1min
|
|
190
|
+
uv run multigas normalize data/site_a.dat --dataset-type 1min --json
|
|
191
|
+
uv run multigas normalize data/site_a.dat --dataset-type 1min \
|
|
192
|
+
--output-dir results --index-col TIMESTAMP --no-cache
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Use `uv run multigas --help` or `uv run multigas normalize --help` for the
|
|
196
|
+
complete option list. The command requires `--dataset-type` and supports
|
|
197
|
+
`--drop-empty-columns`, `--cache-dir`, `--overwrite`, and `--verbose`.
|
|
198
|
+
See the [CLI Reference](wiki/CLI-Reference.md) for all arguments, defaults,
|
|
199
|
+
types, and source locations.
|
|
200
|
+
|
|
201
|
+
### Command-line daily extraction
|
|
202
|
+
|
|
203
|
+
Use `multigas extract` to normalize a source and write its observations as
|
|
204
|
+
one CSV per calendar day. Extraction supports the fixed-interval dataset
|
|
205
|
+
types and `zero`; `span` and `wx` are excluded because they have no defined
|
|
206
|
+
daily completeness total.
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
uv run multigas extract data/site_a.dat --dataset-type 1min
|
|
210
|
+
uv run multigas extract data/site_a.dat --dataset-type 1min \
|
|
211
|
+
--start-date 2026-01-01 --end-date 2026-01-31 --json
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Date bounds are inclusive, and either may be supplied independently. Output
|
|
215
|
+
uses the existing `extract_daily` layout under
|
|
216
|
+
`<output-dir>/daily/<dataset-type-label>/`; the command reports the effective
|
|
217
|
+
dates, extracted day and record counts, daily directory, and completeness CSV.
|
|
218
|
+
See the [CLI Reference](wiki/CLI-Reference.md#multigas-extract) for every
|
|
219
|
+
option.
|
|
220
|
+
|
|
221
|
+
### Multi-gas plotting
|
|
222
|
+
|
|
223
|
+
Both plotting commands support `--width` and `--height` in millimetres for
|
|
224
|
+
the whole figure, including titles and captions:
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
uv run multigas plot data/site_a.csv --dataset-type 6h --width 300 --height 220
|
|
228
|
+
uv run multigas plot columns Avg_SO2 --source data/site_a.csv --dataset-type 6h --width 200 --height 150
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
Python `Plot` and `plot_columns` accept optional
|
|
232
|
+
`width=None` and `height=None`. Either dimension can be set independently;
|
|
233
|
+
omitted values keep the format/layout defaults, and explicit height overrides
|
|
234
|
+
automatic height. Static output uses `mm / 25.4` inches without tight cropping
|
|
235
|
+
for custom sizes; HTML uses `round(mm * 96 / 25.4)` CSS pixels. Fonts and DPI
|
|
236
|
+
stay fixed. Sizes must be finite positive real numbers; invalid arguments
|
|
237
|
+
raise `ValueError` and undersized layouts raise `PlotError`.
|
|
238
|
+
See [Figure dimensions](wiki/Plot.md#figure-dimensions) for defaults and details.
|
|
239
|
+
|
|
240
|
+
Plot selected numeric columns from any dataset type in one figure:
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
uv run multigas plot columns Avg_CO2_lowpass Avg_SO2 \
|
|
244
|
+
--source data/site_a.csv --dataset-type 6h \
|
|
245
|
+
--start-date 2025-01-01 --end-date 2025-03-31
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
Comma-separated names are also accepted; names are trimmed and deduplicated
|
|
249
|
+
in order. Missing/nonnumeric names are reported together. Each panel shows
|
|
250
|
+
finite observations on a linear time axis, with a wrapped caption below the
|
|
251
|
+
figure describing source, dates, exclusions, and relevant gas caveats.
|
|
252
|
+
Empty columns display an explicit message. Use `--save-as PNG|PDF|HTML`,
|
|
253
|
+
`--one-column`, and optional inclusive date bounds (a date-only end includes
|
|
254
|
+
the whole day). Output is `figures/<source-stem>-columns.<extension>` beneath
|
|
255
|
+
`--output-dir` (default `./output`); `--json` returns `{"figure": "..."}`.
|
|
256
|
+
Python exposes the lazy `multigas.plot.plot_columns(source, column_names,
|
|
257
|
+
dataset_type=None, ..., layout_columns=2)` API, also accepting `MultiGasData`.
|
|
258
|
+
See [selected-column figures](wiki/Plot.md#selected-column-figures).
|
|
259
|
+
|
|
260
|
+
Render six-hour datasets into full-period and trailing-three-month figures:
|
|
261
|
+
|
|
262
|
+
```bash
|
|
263
|
+
uv run multigas plot data/site_a.csv --dataset-type 6h
|
|
264
|
+
uv run multigas plot data/site_a.csv --dataset-type 6h --one-column
|
|
265
|
+
uv run multigas plot data/site_a.csv --dataset-type 6h --save-as PDF
|
|
266
|
+
uv run multigas plot data/site_a.csv --dataset-type 6h --save-as HTML --json
|
|
267
|
+
uv run multigas plot data/site_a.csv --dataset-type 6h --start-date 2025-01-01 --end-date 2025-03-31
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
Figures are written under `<output-dir>/figures` (default `./output/figures`).
|
|
271
|
+
Use `--one-column` to stack all ten panels in one column, or set
|
|
272
|
+
`Plot(..., columns=1)` in Python. PNG, PDF, and HTML support this option;
|
|
273
|
+
two columns remain the default.
|
|
274
|
+
|
|
275
|
+
Use `--start-date` and `--end-date` to select an inclusive date range. An empty
|
|
276
|
+
range reports an explicit error. The public `multigas.plot.Plot` API also
|
|
277
|
+
accepts an already loaded `MultiGasData`.
|
|
278
|
+
|
|
279
|
+
PNG and vector PDF output use a compact, configurable Nature-inspired panel
|
|
280
|
+
layout with distinct, consistently assigned Nature Reviews palette colors,
|
|
281
|
+
parenthesized panel labels, and captions directly below the plots. The proportion
|
|
282
|
+
panel pairs orange SO2 circles with deep-blue H2S squares in PNG, PDF, and HTML.
|
|
283
|
+
The columns
|
|
284
|
+
use a compact gutter and retain outer padding. Choose `--save-as PDF` for editable
|
|
285
|
+
vector artwork. Faint dashed major gridlines sit behind the data; units are explained in the
|
|
286
|
+
caption. Each panel overlays a gap-aware 7-day rolling median on the recorded
|
|
287
|
+
points and reports its valid-reading count. Ratio panels (a)-(e) use linear
|
|
288
|
+
axes by default. Use `Plot(..., log_scale=True)` or CLI `--log-scale` to
|
|
289
|
+
request logarithmic axes for strictly positive ratios, regardless of range;
|
|
290
|
+
panels containing zero or negative ratios stay linear. Panels (f)-(j)
|
|
291
|
+
remain linear. The scale option applies to both periods and PNG/PDF/HTML.
|
|
292
|
+
Far outliers are marked on the axis edge instead of flattening the record.
|
|
293
|
+
Grey bands mark logger outages longer than two days, and the caption warns
|
|
294
|
+
when the SO2 baseline is at or below zero. PNG and PDF default to 280 mm x 190 mm
|
|
295
|
+
with two columns (fits A4 landscape with margins), or 280 mm x 380 mm
|
|
296
|
+
with `--one-column`. HTML output adds linked zooming and hover values. Gas units are reported as unassigned when the TOA5 units row is
|
|
297
|
+
blank; figure captions preserve that limitation. See the [figure guide](https://research-figure-guide.nature.com/figures/preparing-figures-our-specifications/)
|
|
298
|
+
and [artwork palette guidance](https://www.nature.com/documents/natrev-artworkguide.pdf).
|
|
299
|
+
|
|
300
|
+
### Fluent queries
|
|
301
|
+
|
|
302
|
+
See the complete [`Query` method reference](wiki/Queries.md) for every
|
|
303
|
+
method, argument type, and default.
|
|
304
|
+
|
|
305
|
+
`MultiGasData` inherits from `Query`, so column selection, filtering, and
|
|
306
|
+
inspection chain directly on the result. `Query` mutates its working
|
|
307
|
+
DataFrame in place; a pristine copy is kept in `df_original` and
|
|
308
|
+
`refresh()` restores it.
|
|
309
|
+
|
|
310
|
+
```python
|
|
311
|
+
ds.select_numeric_columns().selected_columns
|
|
312
|
+
# ['CO2', 'SO2', 'H2S', ...]
|
|
313
|
+
|
|
314
|
+
ds.select_columns(["CO2", "SO2"]).get().head()
|
|
315
|
+
|
|
316
|
+
ds.missing_columns # columns with any NaN / empty value
|
|
317
|
+
ds.empty_columns # columns that are all-NaN, all-zero, or all-empty
|
|
318
|
+
ds.refresh() # restore the pristine DataFrame and clear selection
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
Filter rows with `where(column, comparator, value)`. The comparator accepts
|
|
322
|
+
any alias from `multigas.core.constant.COMPARATOR` — symbolic (`">="`,
|
|
323
|
+
`"!="`), English (`"greater than"`, `"not equal"`), or Indonesian
|
|
324
|
+
(`"lebih besar sama dengan"`, `"tidak sama dengan"`). If `column` matches
|
|
325
|
+
the index name, the comparison runs against the DatetimeIndex instead of a
|
|
326
|
+
column.
|
|
327
|
+
|
|
328
|
+
```python
|
|
329
|
+
(
|
|
330
|
+
ds.where("CO2", ">", 1.0)
|
|
331
|
+
.where("TIMESTAMP", ">=", "2025-01-01")
|
|
332
|
+
.select_columns(["CO2", "SO2"])
|
|
333
|
+
.get() # narrows ds.df to the selected columns and returns it
|
|
334
|
+
)
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
Date and numeric-range helpers use pandas partial-string slicing so both
|
|
338
|
+
bounds are inclusive:
|
|
339
|
+
|
|
340
|
+
```python
|
|
341
|
+
ds.where_date("2025-01-15") # a single day
|
|
342
|
+
ds.where_date_between("2025-01", "2025-02") # two months, inclusive
|
|
343
|
+
ds.where_values_between("CO2", 0.5, 1.5) # inclusive numeric range
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
`get()` commits the current selection — it replaces `ds.df` with the
|
|
347
|
+
column-projected frame and recomputes `numeric_columns`, so dropped
|
|
348
|
+
columns only come back via `refresh()`.
|
|
349
|
+
|
|
350
|
+
### Wind analysis
|
|
351
|
+
|
|
352
|
+
If the dataset carries a bearings column (in degrees), `MultiGasData` can
|
|
353
|
+
attach a sector or quadrant label per row. Bearings are normalised modulo
|
|
354
|
+
360; `NaN` bearings produce `None` (no row is dropped).
|
|
355
|
+
|
|
356
|
+
```python
|
|
357
|
+
# Sector label — 4, 8, or 16 sectors
|
|
358
|
+
ds.add_wind_direction("WD_deg", as_code=True, direction_to_use=16)
|
|
359
|
+
|
|
360
|
+
# Quadrant label — 4 or 8 quadrants (default 8)
|
|
361
|
+
ds.add_wind_quadrant("WD_deg", as_code=False, quadrant_to_use=8)
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
---
|
|
365
|
+
|
|
366
|
+
## Development
|
|
367
|
+
|
|
368
|
+
```bash
|
|
369
|
+
# Lint and auto-fix
|
|
370
|
+
uv run ruff check --fix src/
|
|
371
|
+
|
|
372
|
+
# Type check (uses `ty`, not mypy)
|
|
373
|
+
uvx ty check src/
|
|
374
|
+
|
|
375
|
+
# Run all tests
|
|
376
|
+
uv run pytest tests/
|
|
377
|
+
|
|
378
|
+
# Run a single test file
|
|
379
|
+
uv run pytest tests/path/to/test_file.py
|
|
380
|
+
|
|
381
|
+
# Check for circular imports after any module change
|
|
382
|
+
uv run pytest tests/test_imports.py -v
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
---
|
|
386
|
+
|
|
387
|
+
## Package layout
|
|
388
|
+
|
|
389
|
+
The package uses the `src/` layout. Public entry points are re-exported from
|
|
390
|
+
`multigas`:
|
|
391
|
+
|
|
392
|
+
```
|
|
393
|
+
src/multigas/
|
|
394
|
+
├── __init__.py # Exposes read_file, DataLoader, version metadata
|
|
395
|
+
├── cli/ # Click CLI (`normalize`, `extract`, and `plot`)
|
|
396
|
+
├── logging.py # Loguru logger + enable/disable/level helpers
|
|
397
|
+
├── config/ # Configuration (stub)
|
|
398
|
+
├── core/
|
|
399
|
+
│ ├── __init__.py # Re-exports DatasetType, enums, type aliases, exceptions
|
|
400
|
+
│ ├── types.py # Enums and type aliases
|
|
401
|
+
│ ├── query.py # Query — fluent column/filter mixin
|
|
402
|
+
│ ├── constant.py # COMPARATOR + WIND_DIRECTIONS_* / WIND_QUADRANTS_*
|
|
403
|
+
│ ├── io.py # read_file — one-call convenience wrapper
|
|
404
|
+
│ └── exceptions.py # MultigasException hierarchy (auto-logs on raise)
|
|
405
|
+
├── data/
|
|
406
|
+
│ ├── __init__.py # Re-exports DataLoader, MultiGasData
|
|
407
|
+
│ ├── loader.py # DataLoader — file I/O, normalisation, joblib cache
|
|
408
|
+
│ └── multigas_data.py # MultiGasData — DataFrame + provenance wrapper (extends Query)
|
|
409
|
+
├── plot/
|
|
410
|
+
│ ├── __init__.py # Lazy Plot, plot_columns and plot_completeness exports
|
|
411
|
+
│ ├── columns.py # Selected-column observation-only PNG / PDF / HTML
|
|
412
|
+
│ ├── dimensions.py # Backend-free size validation and shared layout budgets
|
|
413
|
+
│ ├── plot.py # Standard six-hour plotting API
|
|
414
|
+
│ ├── six_hours.py # Ten-panel styling and renderers
|
|
415
|
+
│ └── plot_completeness.py # plot_completeness — daily-completeness PNG from the summary CSV
|
|
416
|
+
└── utils/
|
|
417
|
+
├── path.py # ensure_dir helper
|
|
418
|
+
├── cache.py # get_cache_key / get_cache_path / save_cache / load_cache / clear_cache
|
|
419
|
+
├── validation.py # check_columns_exist, validate_dataframe_column, check_sampling_consistency
|
|
420
|
+
└── dataframe.py # datetime indexing/range selection, wind conversion, completeness, CSV row counts
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
### Core types (`multigas.core.types`)
|
|
424
|
+
|
|
425
|
+
| Name | Kind | Description |
|
|
426
|
+
|---|---|---|
|
|
427
|
+
| `MultiGasData` | class (subclass of `Query`) | Wraps a loaded DataFrame with `dataset_type`, `source_path`, `index_col`, and the fluent `Query` API. Adds `add_wind_direction` / `add_wind_quadrant` for compass-label columns, `to_csv` / `to_excel` for tabular export, and `extract_daily` for per-day CSV splits with completeness stats (also writes `<source_slug>-completeness.csv` next to the daily folder, renders it to `<source_slug>-completeness.png` via `multigas.plot.plot_completeness` unless `plot=False`, and adds `<source_slug>.json` when `return_as_list=True`). Lives in `multigas.data.multigas_data` (re-exported from `multigas.data`) |
|
|
428
|
+
| `DatasetType` | `StrEnum` | Sampling intervals as pandas frequency aliases: `ONE_SECOND="1s"`, `TWO_SECONDS="2s"`, `ONE_MINUTE="1min"`, `SIX_HOURS="6h"`, plus categorical modes `ZERO="zero"`, `SPAN="span"`, `WX="wx"`. Exposes `.total_data` (expected records per day for sampling-interval members) and `.label` (hyphenated form such as `"one-minute"`, used as a path segment by `extract_daily`) |
|
|
429
|
+
| `SensorStatus` | `IntEnum` | Datalogger status codes (e.g. `WARMING_UP=-1`, `SAMPLE_ACQUISITION=1`, `SPAN_CO2_SO2=4`), each with a `.description` property |
|
|
430
|
+
| `FileFormat` | `StrEnum` | `CSV`, `EXCEL`, `PARQUET`, `JSON` |
|
|
431
|
+
| `LogLevel` | `StrEnum` | `DEBUG`, `INFO`, `WARN`, `ERROR` |
|
|
432
|
+
| `DatasetMetadataDict` | `TypedDict` | Optional TOA5 header fields (`station`, `logger_type`, `firmware`, …) |
|
|
433
|
+
| `DateLike` | type alias | `str \| datetime \| pd.Timestamp` |
|
|
434
|
+
| `ColumnName` | type alias | `str` |
|
|
435
|
+
| `Comparator` | type alias | `str` (e.g. `">="`, `"=="`) |
|
|
436
|
+
|
|
437
|
+
Full parameter tables for every public callable: [`wiki/API-Reference.md`](wiki/API-Reference.md).
|
|
438
|
+
|
|
439
|
+
### Exceptions (`multigas.core.exceptions`)
|
|
440
|
+
|
|
441
|
+
Every subclass auto-logs on construction — do **not** add a manual
|
|
442
|
+
`logger.error(...)` before `raise`. Override the class-level `_log_level`
|
|
443
|
+
attribute (default `"ERROR"`) to lower severity.
|
|
444
|
+
|
|
445
|
+
```
|
|
446
|
+
MultigasException
|
|
447
|
+
├── DatasetError
|
|
448
|
+
│ ├── FilterError
|
|
449
|
+
│ ├── ColumnError
|
|
450
|
+
│ └── DateRangeError
|
|
451
|
+
├── ValidationError
|
|
452
|
+
├── CacheError
|
|
453
|
+
├── LoaderError
|
|
454
|
+
├── MetadataError
|
|
455
|
+
├── PlotError
|
|
456
|
+
└── ConfigError
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
Full per-class raise conditions, catching patterns, and the soft-vs-hard
|
|
460
|
+
failure convention: [`wiki/Exceptions.md`](wiki/Exceptions.md).
|
|
461
|
+
|
|
462
|
+
### Logging (`multigas.logging`)
|
|
463
|
+
|
|
464
|
+
The package ships a preconfigured `loguru` logger. Handlers are only
|
|
465
|
+
registered when the `ENABLE_LOG` environment variable is `"true"` (set it in
|
|
466
|
+
`.env` or export it before running).
|
|
467
|
+
|
|
468
|
+
```python
|
|
469
|
+
from multigas.logging import (
|
|
470
|
+
logger,
|
|
471
|
+
enable_logging,
|
|
472
|
+
disable_logging,
|
|
473
|
+
set_log_level,
|
|
474
|
+
set_log_directory,
|
|
475
|
+
)
|
|
476
|
+
|
|
477
|
+
logger.info("hello") # no-op unless ENABLE_LOG=true
|
|
478
|
+
enable_logging() # register console + file sinks
|
|
479
|
+
set_log_level("DEBUG") # console-only; file sinks stay at DEBUG/ERROR
|
|
480
|
+
set_log_directory("./logs") # rotate to a new directory
|
|
481
|
+
disable_logging() # remove all handlers
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
When enabled, two rotating files are written to `logs/`:
|
|
485
|
+
|
|
486
|
+
- `multigas_YYYY-MM-DD.log` — `DEBUG+`, 30-day retention, zipped on rotation
|
|
487
|
+
- `errors_YYYY-MM-DD.log` — `ERROR+`, 90-day retention, zipped on rotation
|
|
488
|
+
|
|
489
|
+
Sink formats, the auto-log contract for exceptions, and the
|
|
490
|
+
`ENABLE_LOG` worker-inheritance semantics live in
|
|
491
|
+
[`wiki/Logging.md`](wiki/Logging.md).
|
|
492
|
+
|
|
493
|
+
---
|
|
494
|
+
|
|
495
|
+
## Dependencies
|
|
496
|
+
|
|
497
|
+
| Package | Purpose |
|
|
498
|
+
|---|---|
|
|
499
|
+
| `pandas` | DataFrame operations |
|
|
500
|
+
| `numpy` | Numerical computing |
|
|
501
|
+
| `openpyxl` | Excel file I/O |
|
|
502
|
+
| `joblib` | On-disk DataFrame cache |
|
|
503
|
+
| `loguru` | Structured logging |
|
|
504
|
+
| `python-dotenv` | `.env` loading for `ENABLE_LOG` |
|
|
505
|
+
| `python-slugify` | File-name-safe slugs for output paths |
|
|
506
|
+
| `click` | Command-line parsing and command registration |
|
|
507
|
+
| `rich` | CLI spinner and result summary |
|
|
508
|
+
| `matplotlib` | Figure rendering (imported lazily by `multigas.plot`) |
|
|
509
|
+
| `bokeh` | Interactive HTML figure rendering by `multigas.plot.Plot` |
|
|
510
|
+
| `seaborn` | Scoped plot styling for `plot_completeness` |
|
|
511
|
+
| `data-availability` | Daily-completeness chart used by `plot_completeness` |
|
|
512
|
+
|
|
513
|
+
---
|
|
514
|
+
|
|
515
|
+
## License
|
|
516
|
+
|
|
517
|
+
[MIT](LICENSE) — Copyright (c) 2026, Martanto
|