A collection of Jupyter notebooks demonstrating how to use the mth5 package to create, manipulate, and analyze MTH5 files from various magnetotelluric (MT) instruments.
Click the "launch binder" badge above to run these tutorials in your browser without installing anything! Binder will create a live Jupyter environment with all dependencies pre-installed.
MTH5 is a Python package for working with magnetotelluric (MT) time series data in the HDF5 format. It provides a structured, standardized way to store, access, and manage MT data along with comprehensive metadata following IRIS-PASSCAL MT metadata standards.
An MTH5 file is an HDF5-based container format specifically designed for magnetotelluric time series data. Key features include:
- Hierarchical Structure: Organizes data by Survey → Station → Run → Channel
- Standardized Metadata: Follows community-established metadata standards for MT data
- Efficient Storage: Leverages HDF5's compression and chunking for large datasets
- Self-Describing: All metadata is stored within the file itself
- Interoperable: Compatible with other MT analysis tools and workflows
- Version Controlled: Supports schema versioning for data format evolution
MTH5 files are ideal for archiving MT time series data, facilitating data sharing, and ensuring long-term data preservation with complete provenance.
For a simple MATLAB based reader see: https://github.com/castro-cesar/mth5_viewer/
This repository contains tutorial notebooks demonstrating how to:
-
Phoenix Systems
make_mth5_from_phoenix_legacy_mtu.ipynb- Legacy MTU formatmake_mth5_from_phoenix_real.ipynb- Phoenix .td_* format
-
Zonge Systems
make_mth5_from_z3d.ipynb- Z3D format data
-
NIMS Systems
make_mth5_from_nims.ipynb- NIMS format data
-
LEMI Systems
make_mth5_from_lemi.ipynb- LEMI format data
-
Metronix Systems
make_mth5_from_metronix.ipynb- Metronix format data
-
Geomag Systems
make_mth5_from_geomag.ipynb- Geomagnetic data
make_mth5_driver_v0.1.0.ipynb- Working with MTH5 v0.1.0 formatmake_mth5_driver_v0.2.0.ipynb- Working with MTH5 v0.2.0 formatrun_ts_example.ipynb- Working with time series datatransfer_function_example.ipynb- Working with transfer functionsremove_instrument_response_example.ipynb- Instrument response correction
mth5_in_parallel.ipynb- Parallel processing of MTH5 filesmth5_in_parallel_one_file_per_station.ipynb- Multi-file parallel workflows
Easiest way to get started - Click the Binder badge at the top of this README to launch an interactive Jupyter environment in your browser. All dependencies are pre-installed and notebooks are ready to run immediately. No local installation required!
All example notebooks are located in /src/notebooks.
Choose your preferred environment manager below:
First, clone this repository:
git clone https://github.com/MTgeophysics/mth5_tutorial.git
cd mth5_tutorialBest for most users - Uses Python's built-in virtual environment manager.
# Create a virtual environment
python -m venv mth5_env
# Activate the environment
# On Windows:
mth5_env\Scripts\activate
# On macOS/Linux:
source mth5_env/bin/activate
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
# Launch Jupyter
jupyter notebook src/notebooks/To deactivate when done:
deactivateGood for managing Python versions - Uses Anaconda/Miniconda.
# Create a conda environment
conda create -n mth5_tutorial python=3.13
# Activate the environment
conda activate mth5_tutorial
# Install dependencies
pip install -r requirements.txt
# OR install from conda-forge if available:
# conda install -c conda-forge mth5 jupyter
# Launch Jupyter
jupyter notebook src/notebooks/To deactivate when done:
conda deactivateFastest installation - Modern Python package manager with speed optimizations.
# Install uv if you don't have it (https://github.com/astral-sh/uv)
# On Windows (PowerShell):
# irm https://astral.sh/uv/install.ps1 | iex
# On macOS/Linux:
# curl -LsSf https://astral.sh/uv/install.sh | sh
# Create and activate virtual environment
uv venv
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate
# Install dependencies
uv pip install -r requirements.txt
# Launch Jupyter
jupyter notebook src/notebooks/After installation with any method above:
- Launch Jupyter: The command
jupyter notebook src/notebooks/will open Jupyter in your browser - Navigate to notebooks: Click on any
.ipynbfile to open a tutorial - Run cells: Use
Shift+Enterto execute cells or click the "Run" button - Follow along: Each notebook contains detailed explanations and examples
Import errors: Make sure your virtual environment is activated before running Jupyter
Jupyter not found: Install it explicitly with pip install jupyter or conda install jupyter
Module not found: Reinstall dependencies with pip install -r requirements.txt
- MTH5 Documentation: https://mth5.readthedocs.io
- MT Metadata Standards: https://doi.org/10.5066/P9AXGKEV
- GitHub Repository: https://github.com/kujaku11/mth5
Contributions are welcome! If you have examples or tutorials you'd like to share:
- Fork the repository
- Create a new branch for your notebook
- Add your notebook with clear documentation
- Submit a pull request
For questions or issues:
- Open an issue on GitHub
- Consult the documentation
This tutorial repository follows the same license as the mth5 package. See LICENSE file for details.
If you use mth5 in your research, please cite:
Peacock, J.R., Kappler, K., Ronan, T., Heagy, L., Kelbert, A., Frassetto, A., 2022, MTH5: An HDF5 data container for magnetotelluric time series data: U.S. Geological Survey software release, https://doi.org/10.5066/P9FQQARB