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

pip install cself-tools

For development:

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:

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

Example INI-style config:

[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:

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

Plot apparent resistivity:

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

Common database options:

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

Outputs

Default outputs are written below outputs/:

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:

from cself_tools import query_data, process_and_plot_mt_data

New workflow modules are preferred:

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 lines and gray smoothed trends
• automatic line breaks across missing time intervals
• apparent resistivity labels such as rho_xy and units Ohm m

Release checklist

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