Add script to generate StationXML files from cube metadata

.gitignore

@@ -6,3 +6,6 @@
 
 # Directory that gets created when installing
 /cube_conversion.egg-info/
+
+# IRIS StationXML validator which may be downloaded
+/stationxml-validator-*.jar

README.md

@@ -1,23 +1,25 @@
 cube_conversion
 ===============
 
-This command-line tool converts [DiGOS](https://digos.eu/) DATA-CUBE<sup>3</sup>
-files into miniSEED files of a desired length of time with specified metadata.
-Output miniSEED files have units of Pa, unless the user selects to export the files in
-a form suitable for submission to EarthScope (formerly IRIS). The tool
-can differentiate between channels for 3 channel DATA-CUBE<sup>3</sup> files and
-optionally extract coordinates from the digitizer's GPS. The code only looks for
-files from digitizers defined in the `digitizer_sensor_pairs.json` file. Therefore,
-this file must be updated if pairings change or new pairings are added. The user
-can specify a custom "breakout box factor" for setups that modify the signal
-voltage via a voltage divider. This tool is currently only set up for conversion
-of infrasound data, but future updates will accommodate seismic as well.
+These command-line tools convert [DiGOS](https://digos.eu/) DATA-CUBE³ files into
+miniSEED files of a desired length of time with specified metadata, and produce
+validated StationXML files containing deployment, sensor, and digitizer information
+including sensor responses adjusted for individual sensor sensitivities. Output miniSEED
+files have units of Pa, unless the user selects to export the files in a form suitable
+for submission to EarthScope (formerly IRIS) — namely, integer counts. The miniSEED
+conversion tool can differentiate between channels for 3 channel DATA-CUBE³ files and
+optionally extract coordinates from the digitizer's GPS. The code only looks for files
+from digitizers defined in the `digitizer_sensor_pairs.json` file. Therefore, this file
+must be updated if pairings change or new pairings are added. The user can specify a
+custom "breakout box factor" for setups that modify the signal voltage via a voltage
+divider. This tool is currently only set up for conversion of infrasound data, but
+future updates could accommodate seismic as well.
 
 Installation
 ------------
 
 It's recommended that you run this script within a new or pre-existing
-[conda](https://docs.conda.io/projects/conda/en/latest/index.html) environment.
+[conda](https://docs.conda.io/projects/conda/en/stable/) environment.
 (If you choose the latter option, ensure that your environment contains all of
 the packages listed in the [Dependencies](#dependencies) section.)
 
@@ -72,45 +74,58 @@ Supplemental files
 * `digitizer_offsets.json` — Digitizer offsets in V (We have found that each
                              digitizer has a slight voltage offset from zero)
 
-* `sensor_sensitivities.json` — Infrasound sensor sensitivities in V/Pa
+* `sensor_sensitivities.json` — Infrasound sensor model, sensitivity in V/Pa,
+  and frequency of sensitivity measurement in Hz
+
+For `cube_stationxml`, you may optionally use a local copy of the Nominal Response
+Library (NRL). It can be obtained by following the instructions
+[here](https://ds.iris.edu/ds/nrl/). Be sure to unzip the downloaded file to create an
+`NRL/` directory. **Note:** Obviously, since this is offline, you may need to update
+your local copy if a key response change is made, or if a new sensor is added! Hence,
+we recommend only using this local copy option if you're working offline.
 
 Usage
 -----
 
-To print the script's help menu, execute the following terminal commands:
+To run either command-line tool first activate your conda environment, e.g.,
 ```
 conda activate uafinfra  # Or your pre-existing env
+```
+
+## `cube_convert`
+
+To print the conversion script's help menu, run:
+```
 cube_convert --help  # Or: python /path/to/cube_conversion/cube_conversion/cube_convert.py --help
 ```
 The help menu is shown below.
 ```
-usage: cube_convert [-h] [-v] [--grab-gps]
-                    [--bob-factor BREAKOUT_BOX_FACTOR] [--earthscope]
+usage: cube_convert [-h] [-v] [--grab-gps] [--bob-factor BREAKOUT_BOX_FACTOR]
+                    [--earthscope]
                     input_dir [input_dir ...] output_dir network station
                     {01,02,03,04,AUTO} {AUTO,BDF,HDF,CDF}
 
-Convert DATA-CUBE files to miniSEED files while trimming, adding metadata, and
-renaming. Optionally extract coordinates from digitizer GPS.
+Convert DATA-CUBE files to miniSEED files while trimming, adding metadata, and renaming.
+Optionally extract coordinates from digitizer GPS.
 
 positional arguments:
-  input_dir             one or more directories containing raw DATA-CUBE files
-                        (all files must originate from a single digitizer)
-                        [wildcards (*) supported]
+  input_dir             one or more directories containing raw DATA-CUBE files (all files
+                        must originate from a single digitizer) [wildcards (*) supported]
   output_dir            directory for output miniSEED and GPS-related files
   network               desired SEED network code (2 characters, A-Z)
   station               desired SEED station code (3-5 characters, A-Z & 0-9)
-  {01,02,03,04,AUTO}    desired SEED location code (if AUTO, choose
-                        automatically for 3 channel DATA-CUBE files)
-  {AUTO,BDF,HDF,CDF}    desired SEED channel code (if AUTO, determine
-                        automatically using SEED convention [preferred])
+  {01,02,03,04,AUTO}    desired SEED location code (if AUTO, choose automatically for 3
+                        channel DATA-CUBE files)
+  {AUTO,BDF,HDF,CDF}    desired SEED channel code (if AUTO, determine automatically using
+                        SEED convention [preferred])
 
 options:
   -h, --help            show this help message and exit
   -v, --verbose         enable verbosity for GIPPtools commands
   --grab-gps            additionally extract coordinates from digitizer GPS
   --bob-factor BREAKOUT_BOX_FACTOR
-                        factor by which to divide sensitivity values (for
-                        custom breakout boxes [4.5 for UAF DATA-CUBEs])
+                        factor by which to divide sensitivity values (for custom breakout
+                        boxes [4.5 for UAF DATA-CUBEs])
   --earthscope          format miniSEED files for EarthScope (formerly IRIS) data upload
 ```
 For example, the command
@@ -122,6 +137,41 @@ means "convert all files in the subdirectories of `~/data/raw/` and place in
 **01**, and an automatically determined channel code, dividing the sensitivity
 by 4.5 and extracting coordinates from the digitizer's GPS."
 
+## `cube_stationxml`
+
+To print the StationXML generation script's help menu, run:
+```
+cube_stationxml --help  # Or: python /path/to/cube_conversion/cube_conversion/cube_stationxml.py --help
+```
+The help menu is shown below.
+```
+usage: cube_stationxml [-h] [--nrl-path NRL_PATH] [--validate]
+                       input_dir station_mapping [station_mapping ...] output_filename
+
+Generate StationXML files from DATA-CUBE³ miniSEED files and metadata.
+
+positional arguments:
+  input_dir            directory containing miniSEED files and coordinate files produced
+                       by cube_convert
+  station_mapping      one or more mappings of the form
+                       STATION_CODE:CUBE_NAME:SENSOR_SERIAL, for example UAF1:AVJ:903V2
+  output_filename      filename for the output StationXML file (full path)
+
+options:
+  -h, --help           show this help message and exit
+  --nrl-path NRL_PATH  path to local copy of the NRL (Nominal Response Library)
+                       directory, if not provided makes web services call
+  --validate           run the IRIS StationXML validator on the output file
+```
+For example, the command
+```
+cube_stationxml ~/data/miniseed/ UAF1:B52:903V2 ~/data/station.xml --validate
+```
+means "process all miniSEED files in `~/data/miniseed/` assuming that station **UAF1**
+consisted of DATA-CUBE³ **B52** connected to sensor serial number **903V2**, and output
+a StationXML file to `~/data/station.xml`, validating the output file with the IRIS
+StationXML validator."
+
 A note on SEED band codes
 -------------------------
 
@@ -147,7 +197,7 @@ letter of the channel code; e.g., the "B" in "BDF".
 | R         | Extremely long-period  | ≥ 0.0001 to < 0.001 |                   |
 
 Note that the band code depends on both the sample rate of the digitizer and
-the corner period of the sensor. In `cube_convert.py` we allow for "B", "H", or
+the corner period of the sensor. In `cube_convert` we allow for "B", "H", or
 "C", which covers a range of sample rates from 10 to 1000 Hz, all for corner
 periods of 10 s or greater. While this covers most infrasound sensors, please
 confirm that your digitizer sample rate and sensor corner period fit into the

cube_conversion/cube_convert.py

@@ -161,7 +161,7 @@ def main():
     else:
         sensor = digitizer_sensor_pairs[digitizer]
         try:
-            sensitivity = sensitivities[sensor]
+            sensitivity = sensitivities[sensor]['sensitivity']
         except KeyError:
             warnings.warn('No matching sensitivities. Using default of '
                         f'{DEFAULT_SENSITIVITY} V/Pa.')