multigas 0.1.0__py3-none-any.whl
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/__init__.py +36 -0
- multigas/config/__init__.py +5 -0
- multigas/core/__init__.py +50 -0
- multigas/core/exceptions.py +215 -0
- multigas/core/io.py +71 -0
- multigas/core/query.py +412 -0
- multigas/core/types.py +290 -0
- multigas/data/__init__.py +18 -0
- multigas/data/loader.py +417 -0
- multigas/logging.py +170 -0
- multigas/utils/__init__.py +13 -0
- multigas/utils/cache.py +171 -0
- multigas/utils/dataframe.py +79 -0
- multigas/utils/path.py +33 -0
- multigas/utils/validation.py +156 -0
- multigas-0.1.0.dist-info/METADATA +175 -0
- multigas-0.1.0.dist-info/RECORD +18 -0
- multigas-0.1.0.dist-info/WHEEL +4 -0
multigas/__init__.py
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
#!/usr/bin/env python
|
|
2
|
+
"""multigas — Python package for processing multi-gas volcanic monitoring data.
|
|
3
|
+
|
|
4
|
+
Provides :class:`DataLoader` for reading, normalising, and caching CSV/Excel
|
|
5
|
+
files produced by Campbell Scientific dataloggers, and :func:`read_file` as a
|
|
6
|
+
convenient one-call entry point.
|
|
7
|
+
|
|
8
|
+
Example:
|
|
9
|
+
>>> from multigas import read_file
|
|
10
|
+
>>> ds = read_file("data/site_a.dat", dataset_type="1min")
|
|
11
|
+
>>> ds.df.head()
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from importlib.metadata import version
|
|
15
|
+
|
|
16
|
+
from multigas.core.io import read_file
|
|
17
|
+
from multigas.data.loader import DataLoader
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
__version__ = version("multigas")
|
|
21
|
+
__author__ = "Martanto"
|
|
22
|
+
__author_email__ = "martanto@live.com"
|
|
23
|
+
__license__ = "MIT"
|
|
24
|
+
__copyright__ = "Copyright (c) 2026, Martanto"
|
|
25
|
+
__url__ = "https://github.com/martanto/multigas"
|
|
26
|
+
|
|
27
|
+
__all__ = [
|
|
28
|
+
"__version__",
|
|
29
|
+
"__author__",
|
|
30
|
+
"__author_email__",
|
|
31
|
+
"__license__",
|
|
32
|
+
"__copyright__",
|
|
33
|
+
"__url__",
|
|
34
|
+
"read_file",
|
|
35
|
+
"DataLoader",
|
|
36
|
+
]
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"""Core types, exceptions, and query infrastructure for multigas."""
|
|
2
|
+
|
|
3
|
+
from multigas.core.types import (
|
|
4
|
+
DateLike,
|
|
5
|
+
LogLevel,
|
|
6
|
+
ColumnName,
|
|
7
|
+
Comparator,
|
|
8
|
+
FileFormat,
|
|
9
|
+
DatasetType,
|
|
10
|
+
MultiGasData,
|
|
11
|
+
DatasetMetadataDict,
|
|
12
|
+
)
|
|
13
|
+
from multigas.core.exceptions import (
|
|
14
|
+
PlotError,
|
|
15
|
+
CacheError,
|
|
16
|
+
ColumnError,
|
|
17
|
+
ConfigError,
|
|
18
|
+
FilterError,
|
|
19
|
+
LoaderError,
|
|
20
|
+
DatasetError,
|
|
21
|
+
MetadataError,
|
|
22
|
+
DateRangeError,
|
|
23
|
+
ValidationError,
|
|
24
|
+
MultigasException,
|
|
25
|
+
)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
__all__ = [
|
|
29
|
+
# Types
|
|
30
|
+
"DateLike",
|
|
31
|
+
"LogLevel",
|
|
32
|
+
"ColumnName",
|
|
33
|
+
"Comparator",
|
|
34
|
+
"FileFormat",
|
|
35
|
+
"DatasetType",
|
|
36
|
+
"DatasetMetadataDict",
|
|
37
|
+
"MultiGasData",
|
|
38
|
+
# Exceptions
|
|
39
|
+
"PlotError",
|
|
40
|
+
"CacheError",
|
|
41
|
+
"ColumnError",
|
|
42
|
+
"ConfigError",
|
|
43
|
+
"FilterError",
|
|
44
|
+
"LoaderError",
|
|
45
|
+
"DatasetError",
|
|
46
|
+
"MetadataError",
|
|
47
|
+
"DateRangeError",
|
|
48
|
+
"ValidationError",
|
|
49
|
+
"MultigasException",
|
|
50
|
+
]
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
"""Exception hierarchy for the multigas package.
|
|
2
|
+
|
|
3
|
+
All exceptions derive from :class:`MultigasException` so callers can catch the
|
|
4
|
+
entire family with a single ``except MultigasException`` clause. Dataset-level
|
|
5
|
+
failures share a common :class:`DatasetError` ancestor, letting callers narrow
|
|
6
|
+
handling to filter / column / date-range problems without listing each type.
|
|
7
|
+
|
|
8
|
+
Every exception in this module auto-logs its message on construction via the
|
|
9
|
+
shared :mod:`multigas.logging` logger. The recorded frame points at the
|
|
10
|
+
``raise`` site, not this file, so log lines remain useful, and when an
|
|
11
|
+
exception is being handled at raise-time (i.e. ``raise ... from e``) the log
|
|
12
|
+
includes the full traceback with the ``__cause__`` chain. When
|
|
13
|
+
``ENABLE_LOG`` is unset the logger has no handlers and the auto-log is a
|
|
14
|
+
no-op.
|
|
15
|
+
|
|
16
|
+
The default log level is ``ERROR``. A subclass can override the class-level
|
|
17
|
+
``_log_level`` attribute to log at a different loguru level — useful for
|
|
18
|
+
soft-failure exceptions where ``WARNING`` is more honest than ``ERROR``.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
import sys
|
|
22
|
+
|
|
23
|
+
from multigas.logging import logger
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class MultigasException(Exception):
|
|
27
|
+
"""Base class for every exception raised by the multigas package.
|
|
28
|
+
|
|
29
|
+
Catch this to intercept any package-specific failure without swallowing
|
|
30
|
+
unrelated built-in exceptions. On construction the message is
|
|
31
|
+
automatically logged through :mod:`multigas.logging` at the level named
|
|
32
|
+
by the class-level :attr:`_log_level` attribute (``"ERROR"`` by
|
|
33
|
+
default); every subclass inherits this behaviour and may override the
|
|
34
|
+
level.
|
|
35
|
+
|
|
36
|
+
Attributes:
|
|
37
|
+
_log_level (str): Loguru level name used for the auto-log —
|
|
38
|
+
``"DEBUG"``, ``"INFO"``, ``"WARNING"``, ``"ERROR"``, or
|
|
39
|
+
``"CRITICAL"``. Defaults to ``"ERROR"``. Override at the
|
|
40
|
+
subclass level to change severity without touching call sites.
|
|
41
|
+
|
|
42
|
+
Example:
|
|
43
|
+
>>> try:
|
|
44
|
+
... raise LoaderError("bad file")
|
|
45
|
+
... except MultigasException as exc:
|
|
46
|
+
... print(type(exc).__name__)
|
|
47
|
+
LoaderError
|
|
48
|
+
"""
|
|
49
|
+
|
|
50
|
+
_log_level: str = "ERROR"
|
|
51
|
+
|
|
52
|
+
def __init__(self, *args: object) -> None:
|
|
53
|
+
"""Initialise the exception and emit an auto-log line.
|
|
54
|
+
|
|
55
|
+
Delegates to :class:`Exception` for the standard ``args`` handling,
|
|
56
|
+
then logs the formatted message at :attr:`_log_level` via
|
|
57
|
+
:mod:`multigas.logging`. ``logger.opt(depth=1, exception=True)``
|
|
58
|
+
shifts the recorded frame one level up the stack so the log's
|
|
59
|
+
``{name}:{function}:{line}`` slot points at the ``raise`` site
|
|
60
|
+
rather than this ``__init__``, and attaches the current exception's
|
|
61
|
+
traceback (including the ``__cause__`` chain from
|
|
62
|
+
``raise ... from e``) when one is being handled. When no exception
|
|
63
|
+
is active the ``exception=True`` flag is a no-op.
|
|
64
|
+
|
|
65
|
+
Args:
|
|
66
|
+
*args (object): Positional arguments forwarded to
|
|
67
|
+
:class:`Exception`. The first argument, if any, becomes the
|
|
68
|
+
exception message.
|
|
69
|
+
|
|
70
|
+
Returns:
|
|
71
|
+
None
|
|
72
|
+
"""
|
|
73
|
+
super().__init__(*args)
|
|
74
|
+
# Only attach a traceback when an exception is genuinely being
|
|
75
|
+
# handled; otherwise loguru prints a bare "NoneType: None" tail.
|
|
76
|
+
attach_traceback = sys.exc_info()[0] is not None
|
|
77
|
+
logger.opt(depth=1, exception=attach_traceback).log(
|
|
78
|
+
self._log_level, f"{type(self).__name__}: {self}"
|
|
79
|
+
)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
class DatasetError(MultigasException):
|
|
83
|
+
"""Raised for dataset-level operations that cannot complete.
|
|
84
|
+
|
|
85
|
+
Parent of :class:`FilterError`, :class:`ColumnError`, and
|
|
86
|
+
:class:`DateRangeError` — catch this to handle any dataset manipulation
|
|
87
|
+
failure regardless of subclass.
|
|
88
|
+
|
|
89
|
+
Example:
|
|
90
|
+
>>> raise DatasetError("dataset is empty")
|
|
91
|
+
Traceback (most recent call last):
|
|
92
|
+
...
|
|
93
|
+
multigas.core.exceptions.DatasetError: dataset is empty
|
|
94
|
+
"""
|
|
95
|
+
|
|
96
|
+
pass
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
class ValidationError(MultigasException):
|
|
100
|
+
"""Raised when input data fails a validation check.
|
|
101
|
+
|
|
102
|
+
Example:
|
|
103
|
+
>>> raise ValidationError("index is not monotonic")
|
|
104
|
+
Traceback (most recent call last):
|
|
105
|
+
...
|
|
106
|
+
multigas.core.exceptions.ValidationError: index is not monotonic
|
|
107
|
+
"""
|
|
108
|
+
|
|
109
|
+
pass
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
class CacheError(MultigasException):
|
|
113
|
+
"""Raised when reading from or writing to the on-disk cache fails.
|
|
114
|
+
|
|
115
|
+
Typically wraps a lower-level joblib or filesystem error.
|
|
116
|
+
|
|
117
|
+
Example:
|
|
118
|
+
>>> raise CacheError("cache file is corrupted")
|
|
119
|
+
Traceback (most recent call last):
|
|
120
|
+
...
|
|
121
|
+
multigas.core.exceptions.CacheError: cache file is corrupted
|
|
122
|
+
"""
|
|
123
|
+
|
|
124
|
+
pass
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
class LoaderError(MultigasException):
|
|
128
|
+
"""Raised when a source file cannot be located, parsed, or normalised.
|
|
129
|
+
|
|
130
|
+
Example:
|
|
131
|
+
>>> raise LoaderError("File not found: data/site_a.dat")
|
|
132
|
+
Traceback (most recent call last):
|
|
133
|
+
...
|
|
134
|
+
multigas.core.exceptions.LoaderError: File not found: data/site_a.dat
|
|
135
|
+
"""
|
|
136
|
+
|
|
137
|
+
pass
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
class MetadataError(MultigasException):
|
|
141
|
+
"""Raised when TOA5 (or equivalent) metadata cannot be extracted.
|
|
142
|
+
|
|
143
|
+
Example:
|
|
144
|
+
>>> raise MetadataError("missing station name in header")
|
|
145
|
+
Traceback (most recent call last):
|
|
146
|
+
...
|
|
147
|
+
multigas.core.exceptions.MetadataError: missing station name in header
|
|
148
|
+
"""
|
|
149
|
+
|
|
150
|
+
pass
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
class FilterError(DatasetError):
|
|
154
|
+
"""Raised when a filter expression is invalid or produces no rows.
|
|
155
|
+
|
|
156
|
+
Example:
|
|
157
|
+
>>> raise FilterError("unknown comparator '~='")
|
|
158
|
+
Traceback (most recent call last):
|
|
159
|
+
...
|
|
160
|
+
multigas.core.exceptions.FilterError: unknown comparator '~='
|
|
161
|
+
"""
|
|
162
|
+
|
|
163
|
+
pass
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
class ColumnError(DatasetError):
|
|
167
|
+
"""Raised for column-level failures — missing, duplicated, or wrong dtype.
|
|
168
|
+
|
|
169
|
+
Example:
|
|
170
|
+
>>> raise ColumnError("column 'CO2' is missing")
|
|
171
|
+
Traceback (most recent call last):
|
|
172
|
+
...
|
|
173
|
+
multigas.core.exceptions.ColumnError: column 'CO2' is missing
|
|
174
|
+
"""
|
|
175
|
+
|
|
176
|
+
pass
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
class DateRangeError(DatasetError):
|
|
180
|
+
"""Raised when a requested date range cannot be applied to the dataset.
|
|
181
|
+
|
|
182
|
+
Example:
|
|
183
|
+
>>> raise DateRangeError("start date is after end date")
|
|
184
|
+
Traceback (most recent call last):
|
|
185
|
+
...
|
|
186
|
+
multigas.core.exceptions.DateRangeError: start date is after end date
|
|
187
|
+
"""
|
|
188
|
+
|
|
189
|
+
pass
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
class PlotError(MultigasException):
|
|
193
|
+
"""Raised when a plotting routine cannot render its output.
|
|
194
|
+
|
|
195
|
+
Example:
|
|
196
|
+
>>> raise PlotError("no numeric columns to plot")
|
|
197
|
+
Traceback (most recent call last):
|
|
198
|
+
...
|
|
199
|
+
multigas.core.exceptions.PlotError: no numeric columns to plot
|
|
200
|
+
"""
|
|
201
|
+
|
|
202
|
+
pass
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
class ConfigError(MultigasException):
|
|
206
|
+
"""Raised when the package configuration is missing or invalid.
|
|
207
|
+
|
|
208
|
+
Example:
|
|
209
|
+
>>> raise ConfigError("cache_dir must be an absolute path")
|
|
210
|
+
Traceback (most recent call last):
|
|
211
|
+
...
|
|
212
|
+
multigas.core.exceptions.ConfigError: cache_dir must be an absolute path
|
|
213
|
+
"""
|
|
214
|
+
|
|
215
|
+
pass
|
multigas/core/io.py
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
"""Convenience wrappers for one-call file loading."""
|
|
2
|
+
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
|
|
5
|
+
from multigas.core import MultiGasData
|
|
6
|
+
from multigas.core.types import DatasetType
|
|
7
|
+
from multigas.data.loader import DataLoader
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def read_file(
|
|
11
|
+
file_path: Path | str,
|
|
12
|
+
dataset_type: DatasetType | str,
|
|
13
|
+
drop_empty_columns: bool = False,
|
|
14
|
+
normalize: bool = True,
|
|
15
|
+
use_cache: bool = True,
|
|
16
|
+
output_dir: Path | str | None = None,
|
|
17
|
+
cache_dir: Path | str | None = None,
|
|
18
|
+
overwrite: bool = False,
|
|
19
|
+
verbose: bool = False,
|
|
20
|
+
) -> MultiGasData:
|
|
21
|
+
"""Load a data file and return a :class:`MultiGasData` result.
|
|
22
|
+
|
|
23
|
+
A thin wrapper around :class:`DataLoader` that constructs the loader,
|
|
24
|
+
calls :meth:`DataLoader.load`, and returns the result in one call.
|
|
25
|
+
|
|
26
|
+
Args:
|
|
27
|
+
file_path: Path to the source CSV or dat file.
|
|
28
|
+
dataset_type: Dataset type identifier — a :class:`DatasetType` member
|
|
29
|
+
or its string value (e.g. ``"1min"``).
|
|
30
|
+
drop_empty_columns: Drop columns that are entirely NaN after
|
|
31
|
+
normalisation. Defaults to ``False``.
|
|
32
|
+
normalize: Replace NAN sentinel strings with ``np.nan`` and coerce
|
|
33
|
+
object columns to numeric. Defaults to ``True``.
|
|
34
|
+
use_cache: Read from and write to the on-disk joblib cache when
|
|
35
|
+
``normalize`` is also ``True``. Defaults to ``True``.
|
|
36
|
+
output_dir: Root output directory. String values are coerced to
|
|
37
|
+
:class:`~pathlib.Path`. Defaults to ``<cwd>/output``.
|
|
38
|
+
cache_dir: Directory for cached files. Defaults to
|
|
39
|
+
``<output_dir>/cache``.
|
|
40
|
+
overwrite: Ignore any existing cache entry and re-load from source.
|
|
41
|
+
Defaults to ``False``.
|
|
42
|
+
verbose: Emit informational log messages during loading. Defaults to
|
|
43
|
+
``False``.
|
|
44
|
+
|
|
45
|
+
Returns:
|
|
46
|
+
A :class:`MultiGasData` instance containing the DataFrame, dataset
|
|
47
|
+
type, and absolute source path.
|
|
48
|
+
|
|
49
|
+
Raises:
|
|
50
|
+
LoaderError: If the file does not exist or cannot be parsed.
|
|
51
|
+
|
|
52
|
+
Example:
|
|
53
|
+
>>> from multigas.core.io import read_file
|
|
54
|
+
>>> ds = read_file("data/site_a.dat", dataset_type="1min")
|
|
55
|
+
>>> ds.df.shape
|
|
56
|
+
(1440, 10)
|
|
57
|
+
"""
|
|
58
|
+
mutigas_data = DataLoader(
|
|
59
|
+
output_dir=output_dir,
|
|
60
|
+
cache_dir=cache_dir,
|
|
61
|
+
overwrite=overwrite,
|
|
62
|
+
verbose=verbose,
|
|
63
|
+
).load(
|
|
64
|
+
file_path=file_path,
|
|
65
|
+
dataset_type=dataset_type,
|
|
66
|
+
drop_empty_columns=drop_empty_columns,
|
|
67
|
+
normalize=normalize,
|
|
68
|
+
use_cache=use_cache,
|
|
69
|
+
)
|
|
70
|
+
|
|
71
|
+
return mutigas_data
|