Metadata-Version: 2.4
Name: mtpy-v2
Version: 2.0.13
Summary: Python toolkit for standard magnetotelluric data processing.
Author: Alison Kirkby, Fei Zhang, Rakib Hassan, Lars Krieger, Stephan Thiel
Author-email: Jared Peacock <jpeacock@usgs.gov>
License: MIT License
        
        Copyright (c) 2023 Magnetotellurics Geophysics
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/MTgeophysics/mtpy-v2
Project-URL: Repository, https://github.com/MTgeophysics/mtpy-v2
Keywords: magnetotellurics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: xarray
Requires-Dist: matplotlib
Requires-Dist: pyproj
Requires-Dist: configparser
Requires-Dist: mt_metadata
Requires-Dist: mth5
Requires-Dist: geopandas
Requires-Dist: rasterio
Requires-Dist: contextily
Requires-Dist: pyevtk
Requires-Dist: simpeg
Requires-Dist: aurora
Provides-Extra: test
Requires-Dist: pytest>=3; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Requires-Dist: pytest-subtests; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Dynamic: license-file

# MTpy-v2: A Python Toolbox for working with Magnetotelluric (MT) Data

[![PyPi version](https://img.shields.io/pypi/v/mtpy-v2.svg)](https://pypi.python.org/pypi/mtpy-v2)
[![Latest conda|conda-forge version](https://img.shields.io/conda/v/conda-forge/mtpy-v2.svg)](https://anaconda.org/conda-forge/mtpy-v2)
[![codecov](https://codecov.io/gh/MTgeophysics/mtpy-v2/graph/badge.svg?token=TQPFBFMYDQ)](https://codecov.io/gh/MTgeophysics/mtpy-v2)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation Status](https://readthedocs.org/projects/mtpy-v2/badge/?version=latest)](https://mtpy-v2.readthedocs.io/en/latest/?badge=latest)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/MTgeophysics/mtpy-v2/main)

## Version 2.0.13

# Description
 
`mtpy` provides tools for working with magnetotelluric (MT) data.  MTpy-v2 is an updated version of [mtpy](https://github.com/MTgeophysics/mtpy). Many things have changed under the hood and usage is different from mtpy v1. The main difference is that there is a central data type that can hold transfer functions and then read/write to your modeling program, plot, and analyze your data.  No longer will you need a directory of EDI files and then read them in everytime you want to do something.  You only need to build a project once and save it to an MTH5 file and you are ready to go. All metadata uses [mt-metadata](https://github.com/kujaku11/mt-metadata).



# Installation

## Using Pip

`> pip install mtpy-v2`

## Using conda

`> conda install -c conda-forge mtpy-v2`

### Pardiso Solver

`mtpy-v2` now include some tools to model and invert using `simpeg`. If you want to use the Pardiso solver you will need to install it separately. See the https://github.com/simpeg/pydiso for more information.  Below is a snippet from their recommendations. 

#### Installing from source

The wrapper is written in cython and links to the mkl libraries dynamically. Therefore,
it needs to find the necessary header files associated with the MKL installation to compile.
The meson build backend uses pkg-config to identify the locations of the mkl header files
and library dynamic libraries. Most development installations of MKL should provide the
necessary pkg-config files for this. For example, conda users can be install the necessary
configuration information with `mkl-devel` package that is available on the default channel,
conda-forge channel, the intel channel, or others, e.g.

`conda install mkl-devel`

If you have installed the configuration files to a non-standard location, you will need to set
`PKG_CONFIG_PATH` to point to that location.

After the necessary MKL files are accessible, you should be able to install by running

`pip install .`

in the installation directory. 


# Functionality

- Read/write transfer function files (EDI, EMTFXML, J-file, Z-file, AVG-file) using [mt-metadata](https://github.com/kujaku11/mt-metadata)
- Read/write [MTH5](https://github.com/kujaku11/mth5) files for full surveys/project in a single file
- Utility functions for GIS
 
## Plotting

- Single transfer function 
  - apparent resistivity and phase
  - induction vectors
  - phase tensors
  - strike
  - depth of investigation
- Survey of transfer functions
  - station map
  - phase tensor and induction vector map and pseudosection
  - apparent resistivity and phase maps and pseudosections
  - depth of investigation map	

## Processing
  - Read/write files for time series processing
    - BIRRP
    - [Aurora](https://github.com/simpeg/aurora)

## Modeling

- Read/Write files for modeling programs
  - ModEM
  - Occam 1D and 2D
  - Mare2DEM (?)
  - Pek 1D and 2D

# What's been Updated in version 2

The main updates in `mtpy-v2` are:

  - Remove dependence on EDI files, can be any type of transfer function file
      - Supports (or will support) to/from:
          - **EDI** (most common format)
          - **ZMM** (Egberts EMTF output)
          - **JFILE** (BIRRP output)
          - **EMTFXML** (Kelbert's format)
          - **AVG** (Zonge output)
  - Uses [mt-metadata](https://github.com/kujaku11/mt_metadata>) to read and write transfer function files where the transfer function data are stored in an [xarray](https://docs.xarray.dev/en/stable/index.html)
  - The workflow is more centralized by introducing `MTCollection` and `MTData` objects which are the databases to hold a collection of transfer functions and manipulate them
    - Includes plotting methods, `to/from` data file types for modeling, rotations, interpolations, static shifts, etc.
	- Can store a collection as an MTH5 using [mth5](https://github.com/kujaku11/mth5)

# Quick Example

Typically MT data are collected as surveys and each station produces a single transfer function.  These are provided in various formats like EDI, EMTF XML, etc.

One benefit of mtpy-v2 is reading all these in only needs to be done once and places them in a single MTH5 file.

```
from pathlib import Path
from mtpy import MTCollection

transfer_function_path = Path("/home/survey_00/transfer_functions")

# write directly to an MTH5 file and close when finished loading TFs
with MTCollection() as mc:
    mc.open_collection(transfer_function_path.joinpath("tf_collection.h5"))
    mc.add_tf(
        mc.make_file_list(
            transfer_function_path,
            file_types=["edi", "xml", "j", "zmm", "zss", "avg"],
        )
    )
 
```

Now when you want to access your data again, you just need to open a single file.

```
mc = MTCollection()
mc.open_collection(r"/home/survey_00/transfer_functions/tf_collection.h5")

# plot station locations
station_locations = mc.plot_stations()
```

# How to Cite

If you use this software in a scientific publication, we'd very much appreciate if you could cite the following papers:

- Kirkby, A.L., Zhang, F., Peacock, J., Hassan, R., Duan, J., 2019. The MTPy software package for magnetotelluric data analysis and visualisation. Journal of Open Source Software, 4(37), 1358. https://doi.org/10.21105/joss.01358
   
- Krieger, L., and Peacock, J., 2014. MTpy: A Python toolbox for magnetotellurics. Computers and Geosciences, 72, p167-175. https://doi.org/10.1016/j.cageo.2014.07.013



# Contacts

| **Jared Peacock**
| peacock.jared@gmail.com

| **Alison Kirkby**
| alkirkby@gmail.com


# System Requirements

-  Python 3.8+


# License

MTpy is licensed under the MIT license

The license agreement is contained in the repository and should be kept together with the code.


