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

The metadata key names should be self-explanatory and are structured as follows:
{category}.{name}, or can be nested {category1}.{categroy2}.{name} where:
  • category refers to a metadata category or level that has common parameters, such as location, which will have a latitude, longitude, and elevation \longrightarrow location.latitude, location.longitude, and location.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 <|90| and all longitude values must be <|180|.

  • 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.

Archived data should remain in measurement coordinates. Any transformation of coordinates for derived products can store the transformation angles at the channel level in
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.

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.

Acceptable String Formats

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

Email

A valid email address

person@mt.or g

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

& Name of the person or persons who acquired the data. This can be different from the project lead if a contractor or different group collected the data. & person name

acquired_by.comments

None

String

Free Form

& Any comments about aspects of how the data were collected or any inconsistencies in the data. & Lightning strike caused a time skip at 8 am UTC.

archive_id

None

String

Alpha Numeric

& Alphanumeric name provided by the archive. For IRIS this will be the FDSN providing a code. & YKN20

archive_network

None

String

Alpha Numeric

& Network code given by PASSCAL/IRIS/FDSN. This will be a two character String that describes who and where the network operates. & EM

citation_dataset.doi

None

String

URL

& The full URL of the doi Number provided by the archive that describes the raw data & http://doi.10.adfabe

citation_journal.doi

None

String

URL

& The full URL of the doi Number for a journal article(s) that uses these data. If multiple journal articles use these data provide as a comma separated String of urls. & http://doi.10.xbsfs, or http://doi.10.xbsfs, http://doi.10.xbsfs2

[tab:survey]

Attributes for Survey Continued

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]

Attributes for Survey Continued

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

Email of the project lead. This is in case there are any questions about data.

mt.guru@em.org

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]

Attributes for Survey Continued

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.

Attributes for Station

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]

Attributes for Station Continued

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.

Attributes for Station Continued

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

Attributes for Station Continued

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

Email of the person submitting the data to the archive.

mt.guru@em.org

provenance.subm itter.organization

None

String

Free Form

Name of the organization that is submitting data to the archive.

MT Gurus

Attributes for Station Continued

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.

Attributes for Run

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]

Attributes for Run Continued

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

Attributes for Run Continued

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.

Attributes for Run Continued

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.

Attributes for Run

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.

Attributes for Electric

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]

Attributes for Electric Continued

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, … ]

Attributes for Electric Continued

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.

Attributes for Electric Continued

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.

Attributes for Electric Continued

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.

Attributes for Electric Continued

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.

Attributes for Magnetic

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]

Attributes for Magnetic Continued

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.

Attributes for Magnetic Continued

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.

Attributes for Magnetic Continued

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.

Attributes for Magnetic Continued

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 \longrightarrow induction coil Number 2284

  • counts2mv \longrightarrow conversion from counts to mV

  • e_gain \longrightarrow electric field gain

  • datalogger_response_024 \longrightarrow data logger Number 24 response

  • notch_60hz \longrightarrow notch filter for 60 Hz and harmonics

  • lowpass_10hz \longrightarrow 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.

Attributes for Filter

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.

Attributes for Auxiliary

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]

Attributes for Auxiliary Continued

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.

Attributes for Auxiliary Continued

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.

Attributes for Auxiliary Continued

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

>10^{3}

BBMT

broadband magnetotellurics

10^{3}10^{0}

LPMT

long-period magnetotellurics

<10^{0}

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