Merge branch 'master' into fix_issue_105

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.2.6
-files = setup.py mth5/__init__.py README.md
+current_version = 0.3.1
+files = setup.py mth5/__init__.py README.md docs/README.rst
 commit = True
 tag = True

.github/workflows/tests.yml

@@ -33,6 +33,7 @@ jobs:
         source activate mth5-test
         conda install pytest
         conda install pytest-cov
+        conda install pytest-subtests
         pip install git+https://github.com/kujaku11/mt_metadata.git
         
     - name: Install Our Package

AUTHORS.rst

@@ -4,6 +4,8 @@ Credits
 
 This project is in cooperation with the Incorporated Research Institutes of Seismology, the U.S. Geological Survey, and other collaborators.  Facilities of the IRIS Consortium are supported by the National Science Foundation’s Seismological Facilities for the Advancement of Geoscience (SAGE) Award under Cooperative Support Agreement EAR-1851048.  USGS is partially funded through the Community for Data Integration and IMAGe through the Minerals Resources Program. 
 
+**Suggested Citation**: Peacock, J. R., Kappler, K., Ronan, T., Heagy, L.,  Kelbert, A., Frassetto, A. (2022) MTH5: An archive and exchangeable data format for magnetotelluric time series data, *Computers & Geoscience*, **162**, doi:10.1016/j.cageo.2022.105102
+
 Development Lead
 ----------------
 
@@ -15,6 +17,7 @@ Contributors
 * Karl Kappler
 * Lindsey Heagy 
 * Tim Ronan
-* Anna Kelbert 
+* Anna Kelbert
+* Laura Keyson 
 
 

HISTORY.rst

@@ -1,4 +1,5 @@
-# History
+History
+=========
 
 0.1.0 (2021-06-30)
 ------------------
@@ -15,10 +16,47 @@
 
 0.2.5 (2022-04-07)
 ----------------------
+
 * fixed bugs
 * Added TransferFunctions and TransferFunction groups at the station level that can now hold transfer functions
 * Added channel_summary and tf_summary tables that are updated upon close if the file is in 'w' mode
 * Updated tests
 * Updated documentation
 * Note: tests for make_mth5 from IRIS are currently not working as there has been some reorganization with data at the DMC
 
+0.2.6 (2022-07-01)
+-----------------------
+
+* Added calibration functions
+* minor bug fixes
+* updated tests
+* updated documentation
+
+0.2.7 (2022-09-14)
+------------------------
+
+* Rebased IO module to make a module for each data logger type
+* Updated tests
+* Updated documentation
+* Factored `make_mth5`
+
+0.3.0 (2022-09-25)
+------------------------
+
+* change default initialize_mth5 to use append mode, issue #92 by @kkappler in #94
+* Fix issue 105 by @kkappler in PR #106
+* adding in parallel mth5 tutorial by @nre900 in #110
+* adding in new tutorial and modifications to mth5_in_parallel.ipynb by @nre900 in issue #112
+* Add phoenix reader by @kujaku11 in PR #103
+* Remove response by @kujaku11 in PR #100 
+
+0.3.1 (2023-01-18)
+------------------------
+
+* Speed up station and survey validataion by 
+* Tutorial updates by @nre900 
+* remove kwarg specifying default value 
+* update initialize_mth5 
+* Have a single metadata object for ChannelTS and RunTS 
+* Use h5 Paths to get groups and datasets
+* Bump wheel from 0.33.6 to 0.38.1

README.md

@@ -15,7 +15,7 @@ MTH5 uses [h5py](https://www.h5py.org/) to interact with the HDF5 file, [xarray]
 This project is in cooperation with the Incorporated Research Institutes of Seismology, the U.S. Geological Survey, and other collaborators.  Facilities of the IRIS Consortium are supported by the National Science Foundation’s Seismological Facilities for the Advancement of Geoscience (SAGE) Award under Cooperative Support Agreement EAR-1851048.  USGS is partially funded through the Community for Data Integration and IMAGe through the Minerals Resources Program.  
 
 
-* **Version**: 0.2.6
+* **Version**: 0.3.1
 * **Free software**: MIT license
 * **Documentation**: https://mth5.readthedocs.io.
 * **Examples**: Click the `Binder` badge above and Jupyter Notebook examples are in **docs/examples/notebooks**

docs/README.rst

@@ -0,0 +1,179 @@
+.. image:: https://img.shields.io/pypi/v/mth5.svg
+    :target: https://pypi.python.org/pypi/mth5
+
+.. image:: https://img.shields.io/conda/v/conda-forge/mth5.svg
+    :target: https://anaconda.org/conda-forge/mth5
+
+.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
+    :target: https://code.chs.usgs.gov/jpeacock/mth5/-/new/master/LICENSE
+
+.. image:: https://readthedocs.org/projects/mth5/badge/?version=latest
+    :target: https://mth5.readthedocs.io/en/latest/?badge=latest)
+
+.. image:: https://codecov.io/gh/kujaku11/mth5/branch/master/graph/badge.svg?token=XU5QSRM1ZO
+    :target: https://codecov.io/gh/kujaku11/mth5
+
+.. image:: https://zenodo.org/badge/283883448.svg
+    :target: https://zenodo.org/badge/latestdoi/283883448
+
+.. image:: https://mybinder.org/badge_logo.svg
+    :target: https://mybinder.org/v2/gh/kujaku11/mth5/master
+
+MTH5
+====
+
+MTH5 is an HDF5 data container for magnetotelluric time series data, but could be extended to other data types.  This package provides tools for reading/writing/manipulating MTH5 files.
+
+MTH5 uses `h5py <https://www.h5py.org/>`_ to interact with the HDF5 file, `xarray <http://xarray.pydata.org/en/stable/>`_ to interact with the data in a nice way, and all metadata use `mt_metadata <https://github.com/kujaku11/mt_metadata>`_. 
+
+This project is in cooperation with the Incorporated Research Institutes of Seismology, the U.S. Geological Survey, and other collaborators.  Facilities of the IRIS Consortium are supported by the National Science Foundation’s Seismological Facilities for the Advancement of Geoscience (SAGE) Award under Cooperative Support Agreement EAR-1851048.  USGS is partially funded through the Community for Data Integration and IMAGe through the Minerals Resources Program.  
+
+* **Version**: 0.3.1
+* **Free software**: MIT license
+* **Documentation**: `<https://mth5.readthedocs.io>`_.
+* **Examples**: Click the `Binder` badge above and Jupyter Notebook examples are in **docs/examples/notebooks**
+* **Suggested Citation**: Peacock, J. R., Kappler, K., Ronan, T., Heagy, L.,  Kelbert, A., Frassetto, A. (2022) MTH5: An archive and exchangeable data format for magnetotelluric time series data, *Computers & Geoscience*, **162**, doi:10.1016/j.cageo.2022.105102
+
+
+Features
+--------
+
+* Read and write HDF5 files formated for magnetotelluric time series.
+* From MTH5 a user can create an MTH5 file, get/add/remove stations, runs, channels and filters and all associated metadata.
+* Data is contained as an `xarray <http://xarray.pydata.org/en/stable/index.html>`_ which can house the data and metadata together, and data is indexed by time.
+* Readers for some data types are included as plugins, namely
+
+	=============== =============
+	Instrument      File Types   
+	=============== =============
+	NIMS            [.bin, .bnn] 
+	LEMI424         [.txt]        
+	USGS ASCII      [.asc, .gzip]
+	Zonge ZEN       [.z3d]       
+	Phoenix         [.td_*, .bin]
+	miniseed        [.mseed]
+	=============== =============
+
+Introduction
+-------------
+
+The goal of **MTH5** is to provide a self describing heirarchical data format for working, sharing, and archiving.  **MTH5** was cooperatively developed with community input and follows logically how magnetotelluric data are collected.  This module provides open-source tools to interact with an **MTH5** file.  
+
+
+The metadata follows the standards proposed by the `IRIS-PASSCAL MT Software working group <https://www.iris.edu/hq/about_iris/governance/mt_soft>`_ and
+documented in `MT Metadata Standards <https://doi.org/10.5066/P9AXGKEV>`_
+**Note**: If you would like to comment or contribute checkout `Issues <https://github.com/kujaku11/mth5/issues>`_ or `Slack <simpeg.slack.com>`_.   
+
+MTH5 Format
+-----------
+
+-  The basic format of MTH5 is illustrated below, where metadata is attached at each level.
+
+MTH5 File Version 0.1.0
+------------------------
+
+.. image:: source/images/example_mt_file_structure.svg
+
+MTH5 file version **0.1.0** was the original file version where `Survey` was the highest level of the file.  This has some limitations in that only one `Survey` could be saved in a single file, but if you have mulitple `Surveys` that you would like to store we need to add a higher level `Experiment`.  
+
+**Important**: Some MTH5 **0.1.0** files have already been archived on `ScienceBase <https://www.sciencebase.gov/catalog/>`_ and has been used as the working format for Aurora and is here for reference.  Moving forward the new format will be **0.2.0** as described below.
+
+
+MTH5 File Version 0.2.0
+-------------------------
+
+.. image:: source/images/example_mt_file_structure_v2.svg
+
+
+MTH5 file version **0.2.0** has `Experiment` as the top level.  This allows for multiple `Surveys` to be included in a single file and therefore allows for more flexibility.  For example if you would like to remote reference stations in a local survey with stations from a different survey collected at the same time you can have all those surveys and stations in the same file and make it easier for processing.
+
+.. hint:: MTH5 is comprehensively logged, therefore if any problems arise you can always check the mth5_debug.log (if you are in debug mode, change the mode in the mth5.__init__) and the mth5_error.log, which will be written to your current working directory.
+
+Examples
+-----------
+
+Make a simple MTH5 with one station, 2 runs, and 2 channels (version 0.2.0)
+
+.. code-block:: python
+
+	from mth5.mth5 import MTH5
+
+	mth5_object = MTH5()
+	mth5_object.open_mth5(r"/home/mt/example_mth5.h5", "a")
+
+	# add a survey
+	survey_group = mth5_object.add_survey("example")
+
+	# add a station with metadata
+	station_group = m.add_station("mt001", survey="example")
+	station_group = survey_group.stations_group.add_station("mt002")
+	station_group.metadata.location.latitude = "40:05:01"
+	station_group.metadata.location.longitude = -122.3432
+	station_group.metadata.location.elevation = 403.1
+	station_group.metadata.acquired_by.author = "me"
+	station_group.metadata.orientation.reference_frame = "geomagnetic"
+
+	# IMPORTANT: Must always use the write_metadata method when metadata is updated.
+	station_group.write_metadata()
+
+	# add runs
+	run_01 = m.add_run("mt002", "001", survey="example")
+	run_02 = station_group.add_run("002")
+
+	# add channels
+	ex = m.add_channel("mt002", "001", "ex", "electric", None, survey="example")
+	hy = run_01.add_channel("hy", "magnetic", None)
+
+	print(mth5_object)
+
+	/:
+	====================
+		|- Group: Experiment
+		--------------------
+			|- Group: Reports
+			-----------------
+			|- Group: Standards
+			-------------------
+				--> Dataset: summary
+				......................
+			|- Group: Surveys
+			-----------------
+				|- Group: example
+				-----------------
+					|- Group: Filters
+					-----------------
+						|- Group: coefficient
+						---------------------
+						|- Group: fap
+						-------------
+						|- Group: fir
+						-------------
+						|- Group: time_delay
+						--------------------
+						|- Group: zpk
+						-------------
+					|- Group: Reports
+					-----------------
+					|- Group: Standards
+					-------------------
+						--> Dataset: summary
+						......................
+					|- Group: Stations
+					------------------
+						|- Group: mt001
+						---------------
+						|- Group: mt002
+						---------------
+							|- Group: 001
+							-------------
+								--> Dataset: ex
+								.................
+								--> Dataset: hy
+								.................
+							|- Group: 002
+							-------------
+
+Credits
+-------
+
+This project is in cooperation with the Incorporated Research Institutes of Seismology, the U.S. Geological Survey, and other collaborators.  Facilities of the IRIS Consortium are supported by the National Science Foundation’s Seismological Facilities for the Advancement of Geoscience (SAGE) Award under Cooperative Support Agreement EAR-1851048.  USGS is partially funded through the Community for Data Integration and IMAGe through the Minerals Resources Program. 

docs/conf.py

@@ -81,7 +81,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.