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.
Files changed (36) hide show
  1. multigas-0.2.0/PKG-INFO +517 -0
  2. multigas-0.2.0/README.md +465 -0
  3. {multigas-0.1.0 → multigas-0.2.0}/pyproject.toml +11 -1
  4. multigas-0.2.0/src/multigas/cli/__init__.py +1 -0
  5. multigas-0.2.0/src/multigas/cli/commands/__init__.py +1 -0
  6. multigas-0.2.0/src/multigas/cli/commands/extract.py +131 -0
  7. multigas-0.2.0/src/multigas/cli/commands/normalize.py +101 -0
  8. multigas-0.2.0/src/multigas/cli/commands/plot.py +201 -0
  9. multigas-0.2.0/src/multigas/cli/main.py +18 -0
  10. {multigas-0.1.0 → multigas-0.2.0}/src/multigas/core/__init__.py +0 -2
  11. multigas-0.2.0/src/multigas/core/constant.py +391 -0
  12. {multigas-0.1.0 → multigas-0.2.0}/src/multigas/core/io.py +9 -1
  13. {multigas-0.1.0 → multigas-0.2.0}/src/multigas/core/query.py +252 -27
  14. {multigas-0.1.0 → multigas-0.2.0}/src/multigas/core/types.py +96 -52
  15. {multigas-0.1.0 → multigas-0.2.0}/src/multigas/data/__init__.py +6 -2
  16. {multigas-0.1.0 → multigas-0.2.0}/src/multigas/data/loader.py +82 -81
  17. multigas-0.2.0/src/multigas/data/multigas_data.py +651 -0
  18. multigas-0.2.0/src/multigas/plot/__init__.py +59 -0
  19. multigas-0.2.0/src/multigas/plot/columns.py +503 -0
  20. multigas-0.2.0/src/multigas/plot/dimensions.py +232 -0
  21. multigas-0.2.0/src/multigas/plot/plot.py +234 -0
  22. multigas-0.2.0/src/multigas/plot/plot_completeness.py +88 -0
  23. multigas-0.2.0/src/multigas/plot/six_hours.py +844 -0
  24. {multigas-0.1.0 → multigas-0.2.0}/src/multigas/utils/cache.py +85 -20
  25. multigas-0.2.0/src/multigas/utils/dataframe.py +388 -0
  26. {multigas-0.1.0 → multigas-0.2.0}/src/multigas/utils/validation.py +3 -6
  27. multigas-0.1.0/PKG-INFO +0 -175
  28. multigas-0.1.0/README.md +0 -130
  29. multigas-0.1.0/src/multigas/utils/dataframe.py +0 -79
  30. {multigas-0.1.0 → multigas-0.2.0}/LICENSE +0 -0
  31. {multigas-0.1.0 → multigas-0.2.0}/src/multigas/__init__.py +0 -0
  32. {multigas-0.1.0 → multigas-0.2.0}/src/multigas/config/__init__.py +0 -0
  33. {multigas-0.1.0 → multigas-0.2.0}/src/multigas/core/exceptions.py +0 -0
  34. {multigas-0.1.0 → multigas-0.2.0}/src/multigas/logging.py +0 -0
  35. {multigas-0.1.0 → multigas-0.2.0}/src/multigas/utils/__init__.py +0 -0
  36. {multigas-0.1.0 → multigas-0.2.0}/src/multigas/utils/path.py +0 -0
@@ -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
+ [![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
56
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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