Metadata-Version: 2.4
Name: cself-tools
Version: 0.5.4
Summary: Magnetic and apparent resistivity data download, processing, and plotting tools.
Author-email: WANG Qinglin <chd_wql@qq.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/chdwql/cself_tools
Project-URL: Issues, https://github.com/chdwql/cself_tools/issues
Keywords: geomagnetic,resistivity,oracle,plotting
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cx_Oracle>=8.3.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Provides-Extra: qzad
Requires-Dist: pyarrow>=8.0.0; extra == "qzad"
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# cself_tools

`cself_tools` is a Python package for downloading, processing, and plotting
geomagnetic and very-low-frequency apparent resistivity data from irregular
Oracle tables.

The package focuses on two workflows:

- **Magnetic data**: download F/H/D/I/X/Y/Z components, split by station,
  point, and FINSTR, and export CSV/TXT/PNG outputs.
- **Apparent resistivity**: query RXY/RYX/RXX/RYY components, filter outliers,
  compute moving averages, save raw CSV data, and generate report-ready plots.

## Installation

```powershell
pip install cself-tools
```

For development:

```powershell
pip install -e .[dev,qzad]
```

Oracle access requires `cx_Oracle` and an Oracle Instant Client compatible with
the target database.

## Database configuration

Named connections are loaded directly from `.adder`-style configuration files,
so `addereq` is no longer required.

By default, the package searches:

```text
~/.adder/conf
~/.adder/config
~/.adder/connections.ini
~/.adder/connections.json
```

Example INI-style config:

```ini
[China]
username = qzdata
password = pass#word
dsn = 127.0.0.1:1521/orcl
```

Passwords are read as plain values, so special characters such as `#` are
preserved.

## Command line usage

After installation, use the `cself-tools` command.

Download magnetic data:

```powershell
cself-tools magnetic download --connection China --start 2000-01-01 --components F H D I X Y Z
```

Plot apparent resistivity:

```powershell
cself-tools resistivity plot --connection DB-Shandong-12 --station-id 37022 --point-id E --components RXY --frequencies 22 74
```

Common database options:

```powershell
--connection China
--oracle-client-lib C:\oracle\instantclient_19_22
--config-dir C:\Users\you\.adder
```

## Outputs

Default outputs are written below `outputs/`:

```text
outputs/
  magnetic/
    csv/
    txt/
    plots/
    manifest.csv
  resistivity/
    csv/
    plots/
```

The magnetic manifest records station, point, FINSTR, row count, date range,
file path, and same-day duplicate counts.

## Python API

Legacy APIs are still available:

```python
from cself_tools import query_data, process_and_plot_mt_data
```

New workflow modules are preferred:

```python
from cself_tools.resistivity import ResistivityRequest, load_resistivity, plot_resistivity
from cself_tools.magnetic import MagneticDownloadRequest, download_magnetic
```

## Plot style

Plots use a consistent report-ready style:

- 300 dpi PNG output
- compact multi-panel time-series layout
- blue observed scatter points and gray smoothed trends
- automatic line breaks across missing time intervals
- apparent resistivity labels such as `rho_xy` and units `Ohm m`

## Release checklist

```powershell
python -m build
twine check dist/*
pip install dist/*.whl
cself-tools --help
```
