A Standard for Exchangeable Magnetotelluric Metadata¶
- Author
Working Group for Data Handling and Software - PASSCAL
Magnetotelluric Program :Date: Version 0.0.16 – July 2020 1
Introduction¶
Researchers using magnetotelluric (MT) methods lack a standardized format for storing time series data and metadata. Commercially available MT instruments produce data in formats that range from proprietary binary to ASCII, whereas recent datasets from the U.S. MT community have utilized institutional formats or heavily adapted formats like miniSEED. In many cases, the available metadata for MT time series are incomplete and loosely standardized; and overall, these datasets are not “user friendly”. This lack of a standardized resource impedes the exchange and broader use of these data beyond a small community of specialists.
The IRIS PASSCAL MT facility maintains a pool of MT instruments that are freely available to U.S. Principal Investigators (PIs). Datasets collected with these instruments are subject to data sharing requirements, and an IRIS working group advises the development of sustainable data formats and workflows for this facility. Following in the spirit of the standard created for MT transfer function datasets, this document outlines a new metadata standard for level 0,1,and 2 MT time series data (Data Levels). Following community approval of these standards, MTH5 (an HDF5 MT specific format) will be developed later in 2020.
The Python 3 module written for these standards and MTH5 is being developed at https://github.com/kujaku11/MTarchive/tree/tables.
General Structure¶
The metadata for a full MT dataset are structured to cover details from
single channel time series to a full survey. For simplicity, each of the
different scales of an MT survey and measurements have been categorized
starting from largest to smallest (Figure 1). These
categories are: Survey
, Station
, Run
, DataLogger
,
Electric Channel
, Magnetic Channel
, and Auxiliary Channel
.
Each category is described in subsequent sections. Required keywords are
labeled as and suggested keywords are labeled as . A user should use as
much of the suggested metadata as possible for a full description of the
data.
Metadata Keyword Format¶
{category}.{name}
, or can be nested
{category1}.{categroy2}.{name}
where:category
refers to a metadata category or level that has common parameters, such aslocation
, which will have a latitude, longitude, and elevationlocation.latitude
,location.longitude
, andlocation.elevation
. These can be nested, for example,station.location.latitude
name
is a descriptive name, where words should be separated by an underscore. Note that only whole words should be used and abbreviations should be avoided, e.g.data_quality
.
A ‘.’ represents the separator between different categories. The metadata can be stored in many different forms. Common forms are XML or JSON formats. See examples below for various ways to represent the metadata.
Formatting Standards¶
Specific and required formatting standards for location, time and date, and angles are defined below and should be adhered to.
Time and Date Format¶
All time and dates are given as an ISO formatted date-time String in the
UTC time zone. The ISO Date Time format is
YYYY-MM-DDThh:mm:ss.ms+00:00
, where the UTC time zone is represented
by +00:00
. UTC can also be denoted by Z
at the end of the
date-time string YYYY-MM-DDThh:mm:ss.msZ
. Note that Z
can also
represent Greenwich Mean Time (GMT) but is an acceptable representation
of UTC time. If the data requires a different time zone, this can be
accommodated but it is recommended that UTC be used whenever possible to
avoid confusion of local time and local daylight savings. Milliseconds
can be accurate to 9 decimal places. ISO dates are formatted
YYYY-MM-DD
. Hours are given as a 24 hour number or military time,
e.g. 4:00 PM is 16:00.
Location¶
All latitude and longitude locations are given in decimal degrees in the
well known datum specified at the Survey
level. NOTE: The entire
survey should use only one datum that is specified at the Survey
level.
All latitude values must be and all longitude values must be .
Elevation and other distance values are given in meters.
Datum should be one of the well known datums, WGS84 is preferred, but others are acceptable.
Angles¶
All angles of orientation are given in decimal degrees. Orientation of
channels should be given in a geographic or a geomagnetic reference
frame where the right-hand coordinates are assumed to be North = 0, East
= 90, and vertical is positive downward (Figure 2).
The coordinate reference frame is given at the station level
station.orientation.reference_frame
. Two angles to describe the
orientation of a sensor is given by channel.measurement_azimuth
and
channel.measurement_tilt
. In a geographic or geomagnetic reference
frame, the azimuth refers to the horizontal angle relative to north
positive clockwise, and the tilt refers to the vertical angle with
respect to the horizontal plane. In this reference frame, a tilt angle
of 90 points downward, 0 is parallel with the surface, and -90 points
upwards.
channel.transformed_azimuth
and channel.transformed_tilt
, the
transformed reference frame can then be recorded in
station.orientation.transformed_reference_frame
.Units¶
Acceptable units are only those from the International System of Units (SI). Only long names in all lower case are acceptable. Table 1 summarizes common acceptable units.
Measurement Type |
Unit Name |
---|---|
Angles |
decimal degrees |
Distance |
meter |
Electric Field |
millivolt |
Latitude/Longitude |
decimal degrees |
Magnetic Field |
nanotesla |
Resistance |
ohms |
Resistivity |
ohm-meter |
Temperature |
celsius |
Time |
second |
Voltage |
volt |
[tab:units]
String Formats¶
Each metadata keyword can have a specific string style, such as date and time or alpha-numeric. These are described in Table 2. Note that any list should be comma separated.
Style |
Description |
Example |
---|---|---|
Free Form |
An unregulated string that can contain {a-z, A-Z, 0-9} and special characters |
This is Free Form! |
Alpha Numeric |
A string that contains no spaces and only characters {a-z, A-Z, 0-9, -, /, _} |
WGS84 or GEOMAG-USGS |
Controlled Vocabulary |
Only certain names or words are allowed. In this case, examples of acceptable values are provided in the documentation as [ option01 option02 … ]. The … indicates that other options are possible but have not been defined in the standards yet |
reference_frame = geographic |
List |
List of entries using a comma separator |
Ex, Ey, Hx, Hy, Hz, T |
Number |
A number according to the data type; number of decimal places has not been implemented yet |
10.0 (float) or 10 (integer) |
Date |
ISO formatted date YYYY-MM-DD in UTC |
2020-02-02 |
Date Time |
ISO formatted date time YYYY-MM- DDThh:mm:ss.ms+00:00 in UTC |
2020-02-02T1 2:20:45.123456+00:00 |
A valid email address |
||
URL |
A full URL that a user can view in a web browser |
https:// www.passcal.nmt.edu/ |
[tab:values]
Survey¶
A survey describes an entire data set that covers a specific time span
and region. This may include multiple PIs in multiple data collection
episodes but should be confined to a specific experiment or project. The
Survey
metadata category describes the general parameters of the
survey.
Metadata Key | Description | Example |+======================+======================+======================+
acquired_by.author
None
String
Free Form
acquired_by.comments
None
String
Free Form
archive_id
None
String
Alpha Numeric
archive_network
None
String
Alpha Numeric
citation_dataset.doi
None
String
URL
citation_journal.doi
None
String
URL
[tab:survey]
Metadata Key |
Description |
Example |
---|---|---|
comments None String Free Form |
Any comments about the survey that are important for any user to know. |
Solar activity low. |
country None String Free Form |
Country or countries that the survey is located in. If multiple input as comma separated names. |
USA, Canada |
datum None String Controlled Vocabulary |
The reference datum for all geographic coordinates throughout the survey. It is up to the user to be sure that all coordinates are projected into this datum. Should be a well-known datum: [ WGS84 NAD83 OSGB36 GDA94 ETRS89 PZ-90.11 … ] |
WGS84 |
geographic_name None String Free Form |
Geographic names that encompass the survey. These should be broad geographic names. Further information can be found at https://www .usgs.gov/core-scien ce-systems/ngp/board -on-geographic-names |
Eastern Mojave, Southwestern USA |
name None String Free Form |
Descriptive name of the survey, similar to the title of a journal article. |
MT Characterization of Yukon Terrane |
northwe st_corner.latitude decimal degrees Float Number |
Latitude of the northwest corner of the survey in the datum specified. |
|
northwes t_corner.longitude decimal degrees Float Number |
Longitude of the northwest corner of the survey in the datum specified. |
[tab:survey2]
Metadata Key |
Description |
Example |
---|---|---|
project None String Free Form |
Alphanumeric name for the project. This is different than the archive_id in that it describes a project as having a common project lead and source of funding. There may be multiple surveys within a project. For example if the project is to estimate geomagnetic hazards that project = GEOMAG but the archive_id = YKN20. |
GEOMAG |
project_lead.author None String Free Form |
Name of the project lead. This should be a person who is responsible for the data. |
Magneto |
project_lead.email None String |
Email of the project lead. This is in case there are any questions about data. |
|
proj ect_lead.organization None String Free Form |
Organization name of the project lead. |
MT Gurus |
release_license None String Controlled Vocabulary |
How the data can be used. The options are based on Creative Commons licenses. Options: [ CC 0 CC BY CC BY-SA CC BY-ND CC BY-NC-SA CC BY-NC-ND]. For details visit https://creati vecommons.org/licenses/ |
CC 0 |
sout heast_corner.latitude decimal degrees Float Number |
Latitude of the southeast corner of the survey in the datum specified. |
|
south east_corner.longitude decimal degrees Float Number |
Longitude of the southeast corner of the survey in the datum specified. |
[tab:survey3]
Metadata Key |
Description |
Example |
---|---|---|
summary None String Free Form |
Summary paragraph of the survey including the purpose; difficulties; data quality; summary of outcomes if the data have been processed and modeled. |
Long project of characterizing mineral resources in Yukon |
ti me_period.end_date None String Date |
End date of the survey in UTC. |
-02-01 |
time _period.start_date None String Date |
Start date of the survey in UTC. |
-06-21 |
[tab:survey4]
Example Survey XML Element¶
<?xml version="1.0" ?>
<survey>
<acquired_by>
<author>MT Graduate Students</author>
<comments>Multiple over 5 years</comments>
</acquired_by>
<archive_id>SAM1990</archive_id>
<archive_network>EM</archive_network>
<citation_dataset>
<doi>https://doi.###</doi>
</citation_dataset>
<citation_journal>
<doi>https://doi.###</doi>
</citation_journal>
<comments>None</comments>
<country>USA, Canada</country>
<datum>WGS84</datum>
<geographic_name>Yukon</geographic_name>
<name>Imaging Gold Deposits of the Yukon Province</name>
<northwest_corner>
<latitude type="Float" units="decimal degrees">-130</latitude>
<longitude type="Float" units="decimal degrees">75.9</longitude>
</northwest_corner>
<project>AURORA</project>
<project_lead>
<Email>m.tee@mt.org</Email>
<organization>EM Ltd.</organization>
<author>M. Tee</author>
</project_lead>
<release_license>CC0</release_license>
<southeast_corner>
<latitude type="Float" units="decimal degrees">-110.0</latitude>
<longitude type="Float" units="decimal degrees">65.12</longitude>
</southeast_corner>
<summary>This survey spanned multiple years with graduate students
collecting the data. Lots of curious bears and moose,
some interesting signal from the aurora. Modeled data
image large scale crustal features like the
"fingers of god" that suggest large mineral deposits.
</summary>
<time_period>
<end_date>2020-01-01</end_date>
<start_date>1995-01-01</start_date>
</time_period>
</survey>
Station¶
A station encompasses a single site where data are collected. If the
location changes during a run, then a new station should be created and
subsequently a new run under the new station. If the sensors, cables,
data logger, battery, etc. are replaced during a run but the station
remains in the same location, then this can be recorded in the Run
metadata but does not require a new station entry.
Metadata Key |
Description |
Example |
---|---|---|
** acquired_by.author** None String Free Form |
Name of person or group that collected the station data and will be the point of contact if any questions arise about the data. |
person name |
ac quired_by.comments None String Free Form |
Any comments about who acquired the data. |
Expert diggers. |
archive_id None String Alpha Numeric |
Station name that is archived a-z;A-Z;0-9. For IRIS this is a 5 character String. |
MT201 |
channel_layout None String Controlled Vocabulary |
How the dipoles and magnetic channels of the station were laid out. Options: [ L + … ] |
|
channels_recorded* None String Controlled Vocabulary |
List of components recorded by the station. Should be a summary of all channels recorded dropped channels will be recorded in Run. Options: [ Ex Ey Hx Hy Hz T Battery … ] |
Ex, Ey, Hx, Hy, Hz, T |
comments None String Free Form |
Any comments on the station that would be important for a user. |
Pipeline near by. |
[tab:station]
Metadata Key |
Description |
Example |
---|---|---|
data_type None String Controlled Vocabulary |
All types of data recorded by the station. If multiple types input as a comma separated list. Options: [ RMT AMT BBMT LPMT ULPMT … ] |
BBMT |
geographic_name None String Free Form |
Closest geographic name to the station, should be rather general. For further details about geographic names see https://www .usgs.gov/core-scien ce-systems/ngp/board -on-geographic-names |
“Whitehorse, YK” |
id None String Free Form |
Station name. This can be a longer name than the archive_id name and be a more explanatory name. |
bear hallabaloo |
location.de clination.comments None String Free Form |
Any comments on declination that are important to an end user. |
Different than recorded declination from data logger. |
location .declination.model None String Controlled Vocabulary |
Name of the geomagnetic reference model as {m odel_name}{-}{YYYY}. Model options: |
WMM-2016 |
location .declination.value decimal degrees Float Number |
Declination angle relative to geographic north positive clockwise estimated from location and geomagnetic model. |
|
** location.elevation** meters Float Number |
Elevation of station location in datum specified at survey level. |
Metadata Key |
Description |
Example |
---|---|---|
location.latitude* decimal degrees Float Number |
Latitude of station location in datum specified at survey level. |
|
** location.longitude** decimal degrees Float Number |
Longitude of station location in datum specified at survey level. |
|
** orientation.method** None String Controlled Vocabulary |
Method for orienting station channels. Options: [ compass GPS theodolite electric_compass … ] |
compass |
orientati on.reference_frame None String Controlled Vocabulary |
Reference frame for station layout. There are only 2 options geographic and geomagnetic. Both assume a right-handed coordinate system with North=0, E=90 and vertical positive downward. Options: [ geographic geomagnetic ] |
geomagnetic |
o rientation.transform ed_reference_frame None Float Number |
Reference frame rotation angel relative to orienta tion.reference_frame assuming positive clockwise. Should only be used if data are rotated. |
|
p rovenance.comments None String Free Form |
Any comments on provenance of the data. |
From a graduated graduate student. |
proven ance.creation_time None String Date Time |
Date and time the file was created. |
-02-08 T12:23:40.324600 +00:00 |
Metadata Key |
Description |
Example |
---|---|---|
provenance.log None String Free Form |
A history of any changes made to the data. |
-02-10 T14:24:45+00:00 updated station metadata. |
provenan ce.software.author None String Free Form |
Author of the software used to create the data files. |
programmer 01 |
proven ance.software.name None String Free Form |
Name of the software used to create data files |
mtrules |
provenanc e.software.version None String Free Form |
Version of the software used to create data files |
12.01a |
provenanc e.submitter.author None String Free Form |
Name of the person submitting the data to the archive. |
person name |
provenan ce.submitter.email None String |
Email of the person submitting the data to the archive. |
|
provenance.subm itter.organization None String Free Form |
Name of the organization that is submitting data to the archive. |
MT Gurus |
Metadata Key |
Description |
Example |
---|---|---|
time_period.end None String Date Time |
End date and time of collection in UTC. |
-02-04 T16:23:45.453670 +00:00 |
time_period.start* None String Date Time |
Start date and time of collection in UTC. |
-02-01 T09:23:45.453670 +00:00 |
Example Station JSON¶
{ "station": {
"acquired_by": {
"author": "mt",
"comments": null},
"archive_id": "MT012",
"channel_layout": "L",
"channels_recorded": "Ex, Ey, Hx, Hy",
"comments": null,
"data_type": "MT",
"geographic_name": "Whitehorse, Yukon",
"id": "Curious Bears Hallabaloo",
"location": {
"latitude": 10.0,
"longitude": -112.98,
"elevation": 1234.0,
"declination": {
"value": 12.3,
"comments": null,
"model": "WMM-2016"}},
"orientation": {
"method": "compass",
"reference_frame": "geomagnetic"},
"provenance": {
"comments": null,
"creation_time": "1980-01-01T00:00:00+00:00",
"log": null,
"software": {
"author": "test",
"version": "1.0a",
"name": "name"},
"submitter": {
"author": "name",
"organization": null,
"email": "test@here.org"}},
"time_period": {
"end": "1980-01-01T00:00:00+00:00",
"start": "1982-01-01T16:45:15+00:00"}
}
}
Run¶
A run represents data collected at a single station with a single sampling rate. If the dipole length or other such station parameters are changed between runs, this would require adding a new run. If the station is relocated then a new station should be created. If a run has channels that drop out, the start and end period will be the minimum time and maximum time for all channels recorded.
Metadata Key |
Description |
Example |
---|---|---|
** acquired_by.author** None String Free Form |
Name of the person or persons who acquired the run data. This can be different from the station.acquired_by and survey.acquired_by. |
M.T. Nubee |
ac quired_by.comments None String Free Form |
Any comments about who acquired the data. |
Group of undergraduates. |
channels_ recorded_auxiliary None String name list |
List of auxiliary channels recorded. |
T, battery |
channels _recorded_electric None String name list |
List of electric channels recorded. |
Ex, Ey |
channels _recorded_magnetic None String name list |
List of magnetic channels recorded. |
Hx, Hy, Hz |
comments None String Free Form |
Any comments on the run that would be important for a user. |
Badger attacked Ex. |
[tab:run]
Metadata Key |
Description |
Example |
---|---|---|
comments None String Free Form |
Any comments on the run that would be important for a user. |
cows chewed cables at 9am local time. |
data_logg er.firmware.author None String Free Form |
Author of the firmware that runs the data logger. |
instrument engineer |
data_lo gger.firmware.name None String Free Form |
Name of the firmware the data logger runs. |
mtrules |
data_logge r.firmware.version None String Free Form |
Version of the firmware that runs the data logger. |
12.01a |
data_logger.id None String Free Form |
Instrument ID Number can be serial Number or a designated ID. |
mt01 |
data_l ogger.manufacturer None String Free Form |
Name of person or company that manufactured the data logger. |
MT Gurus |
data_logger.model* None String Free Form |
Model version of the data logger. |
falcon5 |
Metadata Key |
Description |
Example |
---|---|---|
data_logger.pow er_source.comments None String Name |
Any comment about the power source. |
Used a solar panel and it was cloudy. |
data_logg er.power_source.id None String name |
Battery ID or name |
battery01 |
data_logger .power_source.type None String name |
Battery type |
pb-acid gel cell |
data_logger.power_ source.voltage.end volts Float Number |
End voltage |
|
** data_logger.power_so urce.voltage.start** volts Float Number |
Starting voltage |
|
data_logger.timi ng_system.comments None String Free Form |
Any comment on timing system that might be useful for the user. |
GPS locked with internal quartz clock |
data_logger.t iming_system.drift seconds Float Number |
Estimated drift of the timing system. |
Metadata Key |
Description |
Example |
---|---|---|
data_logger. timing_system.type None String Free Form |
Type of timing system used in the data logger. |
GPS |
data_logger.timing_ system.uncertainty* seconds Float Number |
Estimated uncertainty of the timing system. |
|
data_logger.type None String Free Form |
Type of data logger, this should specify the bit rate and any other parameters of the data logger. |
broadband 32-bit |
data_type None String Controlled Vocabulary |
Type of data recorded for this run. Options: [ RMT AMT BBMT LPMT ULPMT … ] |
BBMT |
id None String Alpha Numeric |
Name of the run. Should be station name followed by an alphabet letter for the run. |
MT302b |
** metadata_by.author** None String Free Form |
Person who input the metadata. |
Metadata Zen |
me tadata_by.comments None String Free Form |
Any comments about the metadata that would be useful for the user. |
Undergraduate did the input. |
Metadata Key |
Description |
Example |
---|---|---|
p rovenance.comments None String Free Form |
Any comments on provenance of the data that would be useful to users. |
all good |
provenance.log None String Free Form |
A history of changes made to the data. |
-02-10 T14:24:45 +00:00 updated metadata |
sampling_rate samples per second Float Number |
Sampling rate for the recorded run. |
|
time_period.end None String Date Time |
End date and time of collection in UTC. |
-02-04 T16:23:45.453670 +00:00 |
time_period.start* None String Date Time |
Start date and time of collection in UTC. |
-02-01 T09:23:45.453670 +00:00 |
[tab:]
Example Run JSON¶
{
"run": {
"acquired_by.author": "Magneto",
"acquired_by.comments": "No hands all telekinesis.",
"channels_recorded_auxiliary": ["temperature", "battery"],
"channels_recorded_electric": ["Ex", "Ey"],
"channels_recorded_magnetic": ["Hx", "Hy", "Hz"],
"comments": "Good solar activity",
"data_logger.firmware.author": "Engineer 01",
"data_logger.firmware.name": "MTDL",
"data_logger.firmware.version": "12.23a",
"data_logger.id": "DL01",
"data_logger.manufacturer": "MT Gurus",
"data_logger.model": "Falcon 7",
"data_logger.power_source.comments": "Used solar panel but cloudy",
"data_logger.power_source.id": "Battery_07",
"data_logger.power_source.type": "Pb-acid gel cell 72 Amp-hr",
"data_logger.power_source.voltage.end": 14.1,
"data_logger.power_source.voltage.start": 13.7,
"data_logger.timing_system.comments": null,
"data_logger.timing_system.drift": 0.000001,
"data_logger.timing_system.type": "GPS + internal clock",
"data_logger.timing_system.uncertainty": 0.0000001,
"data_logger.type": "Broadband 32-bit 5 channels",
"data_type": "BBMT",
"id": "YKN201b",
"metadata_by.author": "Graduate Student",
"metadata_by.comments": "Lazy",
"provenance.comments": "Data found on old hard drive",
"provenance.log": "2020-01-02 Updated metadata from old records",
"sampling_rate": 256,
"time_period.end": "1999-06-01T15:30:00+00:00",
"time_period.start": "1999-06-5T20:45:00+00:00"
}
}
Electric Channel¶
Electric channel refers to a dipole measurement of the electric field for a single station for a single run.
Metadata Key |
Description |
Example |
---|---|---|
ac.end volts Float Number |
Ending AC value; if more than one measurement input as a list of Number [1 2 …] |
, 49.5 |
ac.start volts Float Number |
Starting AC value; if more than one measurement input as a list of Number [1 2 …] |
, 55.8 |
channel_number None Integer Number |
Channel number on the data logger of the recorded channel. |
|
comments None String Free Form |
Any comments about the channel that would be useful to a user. |
Lightning storm at 6pm local time |
component None String Controlled Vocabulary |
Name of the component measured. Options: |
Ex |
cont act_resistance.end ohms Float Number list |
Starting contact resistance; if more than one measurement input as a list [1, 2, … ] |
, 1.8 |
[tab:electric]
Metadata Key |
Description |
Example |
---|---|---|
contac t_resistance.start ohms Float Number list |
Starting contact resistance; if more than one measurement input as a list [1, 2, … ] |
, 1.4 |
data_qua lity.rating.author None String Free Form |
Name of person or organization who rated the data. |
graduate student ace |
data_qua lity.rating.method None String Free Form |
The method used to rate the data. Should be a descriptive name and not just the name of a software package. If a rating is provided, the method should be recorded. |
standard deviation |
data_qu ality.rating.value None Integer Number |
Rating from 1-5 where 1 is bad, 5 is good, and 0 is unrated. Options: [ 0 1 2 3 4 5 ] |
|
da ta_quality.warning None String Free Form |
Any warnings about the data that should be noted for users. |
periodic pipeline noise |
dc.end volts Float Number |
Ending DC value; if more than one measurement input as a list [1, 2, … ] |
|
dc.start volts Float Number |
Starting DC value; if more than one measurement input as a list [1, 2, … ] |
Metadata Key |
Description |
Example |
---|---|---|
dipole_length meters Float Number |
Length of the dipole |
|
filter.applied None Boolean List |
Boolean if filter has been applied or not. If more than one filter, input as a comma separated list. Needs to be the same length as filter.name. If only one entry is given, it is assumed to apply to all filters listed. |
True, True |
filter.comments None String Free Form |
Any comments on filters that is important for users. |
low pass is not calibrated |
filter.name None String List |
Name of filter applied or to be applied. If more than one filter, input as a comma separated list. |
counts2mv, lowpass_electric |
m easurement_azimuth decimal degrees Float Number |
Azimuth angle of the channel in the specified survey.orientat ion.reference_frame. |
|
measurement_tilt decimal degrees Float Number |
Tilt angle of channel in survey.orientat ion.reference_frame. |
|
** negative.elevation** meters Float Number |
Elevation of negative electrode in datum specified at survey level. |
Metadata Key |
Description |
Example |
---|---|---|
negative.id None String Free Form |
Negative electrode ID Number, can be serial number or a designated ID. |
electrode01 |
negative.latitude decimal degrees Float Number |
Latitude of negative electrode in datum specified at survey level. |
|
negative.longitude decimal degrees Float Number |
Longitude of negative electrode in datum specified at survey level. |
|
** negative.manufacturer** None String Free Form |
Person or organization that manufactured the electrode. |
Electro-Dudes |
negative.model None String Free Form |
Model version of the electrode. |
falcon5 |
negative.type None String Free Form |
Type of electrode, should specify the chemistry. |
Ag-AgCl |
positive.elevation meters Float Number |
Elevation of the positive electrode in datum specified at survey level. |
Metadata Key |
Description |
Example |
---|---|---|
positive.id None String Free Form |
Positive electrode ID Number, can be serial Number or a designated ID. |
electrode02 |
positive.latitude decimal degrees Float Number |
Latitude of positive electrode in datum specified at survey level. |
|
positive.longitude decimal degrees Float Number |
Longitude of positive electrode in datum specified at survey level. |
|
** positive.manufacturer** None String Free Form |
Name of group or person that manufactured the electrode. |
Electro-Dudes |
positive.model None String Free Form |
Model version of the electrode. |
falcon5 |
positive.type None String Free Form |
Type of electrode, should include chemistry of the electrode. |
Pb-PbCl |
sample_rate samples per second Float Number |
Sample rate of the channel. |
Metadata Key |
Description |
Example |
---|---|---|
time_period.end None String Date Time |
End date and time of collection in UTC |
-02-04 T16:23:45.453670 +00:00 |
time_period.start* None String Date Time |
Start date and time of collection in UTC. |
-02-01T 09:23:45.453670 +00:00 |
t ransformed_azimuth decimal degrees Float Number |
Azimuth angle of channel that has been transformed into a specified coordinate system. Note this value is only for derivative products from the archived data. |
|
transformed_tilt decimal degrees Float Number |
Tilt angle of channel that has been transformed into a specified coordinate system. Note this value is only for derivative products from the archived data. |
|
type None String Free Form |
Data type for the channel. |
electric |
units None String Controlled Vocabulary |
Units of the data, if archived data should always be in counts. Options: [ counts millivolts ] |
counts |
Example Electric Channel JSON¶
{
"electric": {
"ac.end": 10.2,
"ac.start": 12.1,
"channel_number": 2,
"comments": null,
"component": "EX",
"contact_resistance.end": 1.2,
"contact_resistance.start": 1.1,
"data_quality.rating.author": "mt",
"data_quality.rating.method": "ml",
"data_quality.rating.value": 4,
"data_quality.warning": null,
"dc.end": 1.0,
"dc.start": 2.0,
"dipole_length": 100.0,
"filter.applied": [false],
"filter.comments": null,
"filter.name": [ "counts2mv", "lowpass"],
"measurement_azimuth": 90.0,
"measurement_tilt": 20.0,
"negative.elevation": 100.0,
"negative.id": "a",
"negative.latitude": 12.12,
"negative.longitude": -111.12,
"negative.manufacturer": "test",
"negative.model": "fats",
"negative.type": "pb-pbcl",
"positive.elevation": 101.0,
"positive.id": "b",
"positive.latitude": 12.123,
"positive.longitude": -111.14,
"positive.manufacturer": "test",
"positive.model": "fats",
"positive.type": "ag-agcl",
"sample_rate": 256.0,
"time_period.end": "1980-01-01T00:00:00+00:00",
"time_period.start": "2020-01-01T00:00:00+00:00",
"type": "electric",
"units": "counts"
}
}
Magnetic Channel¶
A magnetic channel is a recording of one component of the magnetic field at a single station for a single run.
Metadata Key |
Description |
Example |
---|---|---|
channel_number None Integer Number |
Channel Number on the data logger. |
|
comments None String Free Form |
Any comments about the channel that would be useful to a user. |
Pc1 at 6pm local time. |
component None String Controlled Vocabulary |
Name of the component measured. Options: |
Hx |
data_qua lity.rating.author None String Free Form |
Name of person or organization who rated the data. |
graduate student ace |
data_qua lity.rating.method None String Free Form |
The method used to rate the data. Should be a descriptive name and not just the name of a software package. If a rating is provided, the method should be recorded. |
standard deviation |
data_qu ality.rating.value None Integer Number |
Rating from 1-5 where 1 is bad, 5 is good, and 0 is unrated. Options: [ 0 1 2 3 4 5 ] |
[tab:magnetic]
Metadata Key |
Description |
Example |
---|---|---|
da ta_quality.warning None String Free Form |
Any warnings about the data that should be noted for users. |
periodic pipeline noise |
filter.applied None Boolean List |
Boolean if filter has been applied or not. If more than one filter, input as a comma separated list. Needs to be the same length as filter.name. If only one entry is given, it is assumed to apply to all filters listed. |
True, True |
filter.comments None String Free Form |
Any comments on filters that is important for users. |
low pass is not calibrated |
filter.name None String List |
Name of filter applied or to be applied. If more than one filter, input as a comma separated list. |
counts2mv, lowpass_electric |
h_field_max.end nanotesla Float Number |
Maximum magnetic field strength at end of measurement. |
|
h_field_max.start* nanotesla Float Number |
Maximum magnetic field strength at beginning of measurement. |
|
h_field_min.end nanotesla Float Number |
Minimum magnetic field strength at end of measurement. |
Metadata Key |
Description |
Example |
---|---|---|
h_field_min.start nt Float Number |
Minimum magnetic field strength at beginning of measurement. |
|
location.elevation meters Float Number |
elevation of magnetometer in datum specified at survey level. |
|
location.latitude decimal degrees Float Number |
Latitude of magnetometer in datum specified at survey level. |
|
location.longitude decimal degrees Float Number |
Longitude of magnetometer in datum specified at survey level. |
|
measurement_azimuth decimal degrees Float Number |
Azimuth of channel in the specified survey.orie ntation.reference_frame. |
|
measurement_tilt decimal degrees Float Number |
Tilt of channel in survey.orie ntation.reference_frame. |
|
sample_rate samples per second Float Number |
Sample rate of the channel. |
Metadata Key |
Description |
Example |
---|---|---|
sensor.id None String Free Form |
Sensor ID Number or serial Number. |
mag01 |
s ensor.manufacturer None String Free Form |
Person or organization that manufactured the magnetic sensor. |
Magnets |
sensor.model None String Free Form |
Model version of the magnetic sensor. |
falcon5 |
sensor.type None String Free Form |
Type of magnetic sensor, should describe the type of magnetic field measurement. |
induction coil |
time_period.end None String Date Time |
End date and time of collection in UTC. |
-02-04 T16:23:45.453670 +00:00 |
time_period.start* None String Date Time |
Start date and time of collection in UTC. |
-02-01 T09:23:45.453670 +00:00 |
t ransformed_azimuth decimal degrees Float Number |
Azimuth angle of channel that has been transformed into a specified coordinate system. Note this value is only for derivative products from the archived data. |
Metadata Key |
Description |
Example |
---|---|---|
transformed_tilt decimal degrees Float Number |
Tilt angle of channel that has been transformed into a specified coordinate system. Note this value is only for derivative products from the archived data. |
|
type None String Free Form |
Data type for the channel |
magnetic |
units None String Controlled Vocabulary |
Units of the data. if archiving should always be counts. Options: [ counts nanotesla ] |
counts |
Example Magnetic Channel JSON¶
{ "magnetic": {
"comments": null,
"component": "Hz",
"data_logger": {
"channel_number": 2},
"data_quality": {
"warning": "periodic pipeline",
"rating": {
"author": "M. Tee",
"method": "Machine Learning",
"value": 3}},
"filter": {
"name": ["counts2nT", "lowpass_mag"],
"applied": [true, false],
"comments": null},
"h_field_max": {
"start": 40000.,
"end": 420000.},
"h_field_min": {
"start": 38000.,
"end": 39500.},
"location": {
"latitude": 25.89,
"longitude": -110.98,
"elevation": 1234.5},
"measurement_azimuth": 0.0,
"measurement_tilt": 180.0,
"sample_rate": 64.0,
"sensor": {
"id": 'spud',
"manufacturer": "F. McAraday",
"type": "tri-axial fluxgate",
"model": "top hat"},
"time_period": {
"end": "2010-01-01T00:00:00+00:00",
"start": "2020-01-01T00:00:00+00:00"},
"type": "magnetic",
"units": "nT"
}
}
Filters¶
Filters
is a table that holds information on any filters that need
to be applied to get physical units, and/or filters that were applied to
the data to analyze the signal. This includes calibrations, notch
filters, conversion of counts to units, etc. The actual filter will be
an array of numbers contained within an array named name
and
formatted according to type
. The preferred format for a filter is a
look-up table which programatically can be converted to other formats.
It is important to note that filters will be identified by name and must be consistent throughout the file. Names should be descriptive and self evident. Examples:
coil_2284
induction coil Number 2284counts2mv
conversion from counts to mVe_gain
electric field gaindatalogger_response_024
data logger Number 24 responsenotch_60hz
notch filter for 60 Hz and harmonicslowpass_10hz
low pass filter below 10 Hz
In each channel there are keys to identify filters that can or have been
applied to the data to get an appropriate signal. This can be a list of
filter names or a single filter name. An applied
key also exists for
the user to input whether that filter has been applied. A single Boolean
can be provided True
if all filters have been applied, or False
if none of the filters have been applied. Or applied
can be a list
the same length as names
identifying if the filter has been applied.
For example name: "[counts2mv, notch_60hz, e_gain]"
and
applied: "[True, False, True]
would indicate that counts2mv
and
e_gain
have been applied but noth_60hz
has not.
Metadata Key |
Description |
Example |
---|---|---|
type None String Controlled Vocabulary |
Filter type. Options: [look up poles zeros converter FIR …] |
lookup |
name None String Alpha Numeric |
Unique name for the filter such that it is easy to query. See above for some examples. |
counts2mv |
units_in None String Controlled Vocabulary |
The input units for the filter. Should be SI units or counts. |
counts |
units_out None String Controlled Vocabulary |
The output units for the filter. Should be SI units or counts. |
millivolts |
calibration_date None String Date Time |
If the filter is a calibration, include the calibration date. |
-01-01 T00:00:00 +00:00 |
[tab:filter]
Example Filter JSON¶
{
"filter":{
"type": "look up",
"name": "counts2mv",
"units_in": "counts",
"units_out": "mV",
"calibration_date": "2015-07-01",
"comments": "Accurate to 0.001 mV"
}
}
Auxiliary Channels¶
Auxiliary channels include state of health channels, temperature, etc.
Metadata Key |
Description |
Example |
---|---|---|
channel_number None Integer Number |
Channel Number on the data logger. |
|
comments None String Free Form |
Any comments about the channel that would be useful to a user. |
Pc1 at 6pm local time. |
component None String Controlled Vocabulary |
Name of the component measured. Options: [ temperature battery … ] |
temperature |
data_qua lity.rating.author None String Free Form |
Name of person or organization who rated the data. |
graduate student ace |
data_qua lity.rating.method None String Free Form |
The method used to rate the data. Should be a descriptive name and not just the name of a software package. If a rating is provided, the method should be recorded. |
standard deviation |
data_qu ality.rating.value None Integer Number |
Rating from 1-5 where 1 is bad, 5 is good, and 0 is unrated. Options: [ 0 1 2 3 4 5 ] |
[tab:auxiliary]
Metadata Key |
Description |
Example |
---|---|---|
da ta_quality.warning None String Free Form |
Any warnings about the data that should be noted for users. |
periodic pipeline noise |
filter.applied None Boolean List |
Boolean if filter has been applied or not. If more than one filter, input as a comma separated list. Needs to be the same length as filter.name. If only one entry is given, it is assumed to apply to all filters listed. |
True, True |
filter.comments None String Free Form |
Any comments on filters that is important for users. |
low pass is not calibrated |
filter.name None String List |
Name of filter applied or to be applied. If more than one filter, input as a comma separated list. |
counts2mv, lowpass_auxiliary |
** location.elevation** meters Float Number |
Elevation of channel location in datum specified at survey level. |
|
location.latitude* decimal degrees Float Number |
Latitude of channel location in datum specified at survey level. |
|
** location.longitude** decimal degrees Float Number |
Longitude of channel location in datum specified at survey level. |
Metadata Key |
Description |
Example |
---|---|---|
m easurement_azimuth decimal degrees Float Number |
Azimuth of channel in the specified survey.orientat ion.reference_frame. |
|
measurement_tilt decimal degrees Float Number |
Tilt of channel in survey.orientat ion.reference_frame. |
|
sample_rate samples per second Float Number |
Sample rate of the channel. |
|
time_period.end None String time |
End date and time of collection in UTC. |
-02-04 T16:23:45.453670 +00:00 |
time_period.start* None String time |
Start date and time of collection in UTC. |
-02-01 T09:23:45.453670 +00:00 |
t ransformed_azimuth decimal degrees Float Number |
Azimuth angle of channel that has been transformed into a specified coordinate system. Note this value is only for derivative products from the archived data. |
|
transformed_tilt decimal degrees Float Number |
Tilt angle of channel that has been transformed into a specified coordinate system. Note this value is only for derivative products from the archived data. |
Metadata Key |
Description |
Example |
---|---|---|
type None String Free Form |
Data type for the channel. |
temperature |
units None String Controlled Vocabulary |
Units of the data. Options: SI units or counts. |
celsius |
Example Auxiliary XML¶
<auxiliary>
<comments>great</comments>
<component>Temperature</component>
<data_logger>
<channel_number type="Integer">1</channel_number>
</data_logger>
<data_quality>
<warning>None</warning>
<rating>
<author>mt</author>
<method>ml</method>
<value type="Integer">4</value>
</rating>
</data_quality>
<filter>
<name>
<i>lowpass</i>
<i>counts2mv</i>
</name>
<applied type="boolean">
<i type="boolean">True</i>
</applied>
<comments>test</comments>
</filter>
<location>
<latitude type="Float" units="degrees">12.324</latitude>
<longitude type="Float" units="degrees">-112.03</longitude>
<elevation type="Float" units="degrees">1234.0</elevation>
</location>
<measurement_azimuth type="Float" units="degrees">0.0</measurement_azimuth>
<measurement_tilt type="Float" units="degrees">90.0</measurement_tilt>
<sample_rate type="Float" units="samples per second">8.0</sample_rate>
<time_period>
<end>2020-01-01T00:00:00+00:00</end>
<start>2020-01-04T00:00:00+00:00</start>
</time_period>
<type>auxiliary</type>
<units>celsius</units>
</auxiliary>
Option Definitions¶
use the closest definition.
Data Type
Definition
Sample Rate [samples/s]
AMT
radio magnetotellurics
BBMT
broadband magnetotellurics
–
LPMT
long-period magnetotellurics
[tab:em]
added.
Channel Type
Definition
E
electric field measurement
H
magnetic field measurement
T
temperature
Battery
battery
SOH
state-of-health
[tab:channel_types]
right-hand-rule (Figure 2) with X in the northern direction, Y in the eastern direction, and Z positive down. If the setup has multiple channels in the same direction, they can be labeled with a Number. For instance, if you measure multiple electric fields Ex01, Ey01, Ex02, Ey02.
Direction
Definition
x
north direction
y
east direction
z
vertical direction
# {0–9}
variable directions
[tab:diretions]
- 1
Corresponding Authors:
Jared Peacock (jpeacock@usgs.gov)
Andy Frassetto (andy.frassetto@iris.edu)