Skip to content

Commit

Permalink
Update documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
timronan committed Apr 22, 2020
1 parent a9500fb commit 76a8e6a
Show file tree
Hide file tree
Showing 9 changed files with 67 additions and 39 deletions.
2 changes: 1 addition & 1 deletion docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# StationXML Validator

The IRIS stationxml-validator is a Java library and related command-line tool for validating FDSN-StationXML documents against a set of rules.
The IRIS stationxml-validator is a Java library and related command-line utility for validating FDSN-StationXML documents against a set of rules.

For more information please refer to the project Wiki:

Expand Down
64 changes: 43 additions & 21 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Description

The IRIS stationxml-validator is a Java library and related command-line tool for validating [FDSN StationXML](http://www.fdsn.org/xml/station/) documents. The purpose is ensure that FDSN StationXML metadata is complete and formatted sufficiently for acceptance at the [IRIS DMC](http://ds.iris.edu/).
The IRIS stationxml-validator is a Java library and related command-line utility for validating [FDSN StationXML](http://www.fdsn.org/xml/station/) 1.1 documents. The program's purpose is to ensure that FDSN StationXML metadata are complete and formatted to standards set by [IRIS DMC](http://ds.iris.edu/).

## Documentation
* [Validation tests](tests.md)
Expand All @@ -10,55 +10,77 @@ The IRIS stationxml-validator is a Java library and related command-line tool fo

### Downloading releases

Releases of the StationXML Validator can be downloaded from the project release page:
Releases of the StationXML Validator can be downloaded from the project's release page:

https://github.com/iris-edu/StationXML-Validator/releases

The compiled .jar may be used immediately.

If you wish to compile you can download the source code and follow the [instructions below](#building-the-command-line-validator-from-source).
If you wish to compile the program, the source code is available. Follow the [instructions below](#building-the-command-line-validator-from-source) to download the source code.

## Using the Validator

The command line version of the Validator requires [Java](https://www.java.com/) 8 or 11. A usage message will be printed if no arguments are supplied:
The Validator's jar runs in both [Java](https://www.java.com/) 8 or 11 enviroments. A usage message will be printed if the stationxml-validator is run with no arguments are supplied:

java -jar station-xml-validator-1.5.9.6.jar
java -jar stationxml-validator-1.7.0.jar

To validate a StationXML file provide the name of the StationXML formatted document with the file extensaion .xml on the command line:
The Validator contains arguments that output messages to help users understand its function. The Validator's --help argument prints out a list of all of the available validator arguments.

java -jar stationxml-validator-1.7.0.jar --help

java -jar station-xml-validator-1.5.9.6.jar IU.ANMO.00.BHZ.xml
The rules argument prints the list of rules that the validator uses to check metadata integrety.

java -jar stationxml-validator-1.7.0.jar --rules

The Validator accepts dataless seed files as input arguments. If dataless files are provided, the Validator automatically converters these files to station-xml and performs a validation.
The units argument prints a table of SI units names that are acceptable in stationXML metadata.

java -jar station-xml-validator-1.5.9.6.jar IU.ANMO.00.BHZ.dataless
java -jar stationxml-validator-1.7.0.jar --units

Users interested in generating StationXML formatted metadata from dataless seed files should refer to the [stationxml-seed-converter](https://github.com/iris-edu/stationxml-seed-converter).
To validate stationXML metadata, provide the path and name of a stationXML formatted document as an argument.

The Validator has options for formatting results. By default, the validator returns html. For viewing results quickly the argument `--format report` is helpful and returns text output to the terminal.
java -jar stationxml-validator-1.7.0.jar IU.ANMO.00.BHZ.xml

java -jar station-xml-validator-1.5.9.3.jar IU.ANMO.00.BHZ.xml --format report
The input argument may be prepended before the path.

Refer to the usage message for more arguments.
java -jar stationxml-validator-1.7.0.jar --input IU.ANMO.00.BHZ.xml

The Validator accepts dataless SEED metadata and directories in addation to stationXML. If dataless files are provided, the Validator automatically converters these files to stationXML and performs validation. If a directory is provided as an argument, the Validator will loop through it's contents and validate both stationXML and dataless files.

java -jar station-xml-validator-1.7.0.jar IU.ANMO.00.BHZ.dataless
java -jar stationxml-validator-1.7.0.jar /path/to/metadata

Output are printed to System.out by default. The ouput argument directs Validator messages to the full path name supplied to the argument.

java -jar stationxml-validator-1.7.0.jar /path/to/metadata --output /path/for/output.txt

Additional arguments may be provided to the Validator including: `--verbose` which provides additional output messages to the user, and `continue-on-error` which forces the validator to continue if an exception is encountered. `continue-on-error` is only useful when validating directories.

java -jar stationxml-validator-1.7.0.jar /path/to/metadata --verbose --continue-on-error --output /path/for/output.txt

Users interested in generating stationXML formatted metadata from dataless SEED files should refer to the [stationxml-seed-converter](https://github.com/iris-edu/stationxml-seed-converter).

## Validation tests

The validator performs a number of tests starting with validation of the StationXML schema followed by a number of other tests to ensure completeness sufficient for long-term archiving. All tests with descriptions are listed on the wiki pages:
The validator performs a number of tests. First, it validates the metadata against the StationXML 1.1 schema. After, a suite of test are run on the metadata to ensure completeness sufficient for long-term archiving. The test and their descriptions can be accessed using the `--rules` argument or can be found on the wiki pages:

[[Validation tests]]


## Convention for Units

The Validator includes a rule to check the unit names specified in StationXML metadata. The guidelines for unit names and the list of accepted names are available on the page below:
The Validator includes rules that check if unit names specified in StationXML metadata are SI compliant. The guidelines for unit names and the list of accepted unit names can be accessed using the `--units` argument or can be found on the wiki pages:

[[Unit name overview for IRIS StationXML validator]]

## Building the command line validator from source

To build the stationXML-validator from source code you will need a working instance of the Java Development Kit (JDK 1.8) and [Apache Maven](https://maven.apache.org/). The validator can be built using these steps:
Building the stationxml-validator from source code is dependent on the Java Development Kit (JDK 1.8) and [Apache Maven](https://maven.apache.org/). The validator can be built using these steps:

1. Download source code and untar/unzip. The code can be downloaded either from the project's [release](https://github.com/iris-edu/StationXML-Validator/releases) page or it can be cloned from the Validator's [git repository](https://github.com/iris-edu/stationxml-validator/)
1. cd to the newly created stationxml-=validator directory
1. run the command: `mvn clean install`

The resulting jar is under the target directory. e.g. stationxml-validtor-<version>.jar

1. Download source code and untar/unzip, either a [release](https://github.com/iris-edu/StationXML-Validator/releases) or clone the repository
1. Change to the created StationXML-Validator-<version> directory
1. `mvn clean install`
Pleae report any any issues to the project's [issues page](https://github.com/iris-edu/stationxml-validator/issues).

The resulting jar is under the _target_ directory, e.g. stationxml-validtor-<version>.jar
[Updated 04-2020]
6 changes: 4 additions & 2 deletions docs/orientation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,16 @@ From the SEED 2.4 (August 2012) Manual, Appendix A
**Azimuth: degrees from north, clockwise.**
**Dip: degrees from horizontal.**

The azimuth and dip describe the direction of an instrument's sensitive axis (if applicable). Motion in the same direction as this axis is positive. If instruments are reversed in the field, reverse the dip/azimuth fields. Data collection centers and data management centers should never actually modify the data, but report on its orientation.
The azimuth and dip describe the direction of an instrument's sensitive axis (if applicable). Motion in the same direction as the axis is positive. An instrument's reported dip and azimuth must reflect how an instrument is deployed. If instrument polarity is reversed in the field than the dip and azimuth must be consistent with this fact. Best practices in metadata exchange suggest that insturment orientation should never be corrected and subsquently exchanged using post processing techniques.

## Orthogonal Orientations
<br/>N — Dip 0, Azimuth 0 degrees (Reversed: Dip 0, Azimuth 180 degrees).<br/>E — Dip 0, Azimuth 90 degrees (Reversed: Dip 0, Azimuth 270 degrees).<br/>Z — Dip -90, Azimuth 0 degrees (Reversed: Dip 90, Azimuth 0 degrees).

If orthogonal instrument orientations are not within a 5 degree tolerance of N,E,Z, use non-traditional orthogonal orientations.


## Non-traditional Orthogonal Orientations

<br/>1 — Channel Azimuth is greater than 5 degrees from north (Reversed: south).<br/>2 — Channel Azimuth is greater than 5 degrees from east (Reversed: west).<br/>3 — Channel Dip is greater than 5 degrees from vertical.

[2018-08-02]
[Updated 04-2020]
6 changes: 3 additions & 3 deletions docs/restrictions.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Network
# Station
# Channel
* **[C1](https://github.com/iris-edu/StationXML-Validator/blob/master/Validator_TestSuite/Restrictions/P1_C1.xml)** : Channel:Code == "SOH", "ACE", "OCF", "LOG", "VCE", "LCE", "LCQ","VCO", "VEA", "VEC", "VEP", "VKI", "VM1", "VM2", "VM3", "VPB" does not trigger [Validation tests](https://github.com/iris-edu/StationXML-Validator/wiki/Validation-tests) that are subject to this restriction.
* **[C1](https://github.com/iris-edu/StationXML-Validator/blob/master/Validator_TestSuite/Restrictions/P1_C1.xml)** : Channel:Code =="ACE", "ATC", "BDO", "EX1", "EX2", "EX3", "EX4", "EX5", "EX6", "EX7", "EX8", "EX9", "GAN", "GEL", "GLA", "GLO", "GNS", "GPL", "GPS", "GST", "LCA", "LCB", "LCC", "LCD", "LCE", "LCF", "LCG", "LCH", "LCI", "LCJ", "LCK", "LCL", "LCM", "LCN", "LCO", "LCP", "LCQ", "LCR", "LCS", "LCT", "LCU", "LCV", "LCW", "LCX", "LCY", "LCZ", "LDE", "LDN", "LDZ", "LEE", "LED", "LEO", "LEP", "LII", "LKI", "LOG", "LPL", "OAC", "OCF", "QBD", "QBP", "QDG", "QDL", "QDR", "QEF", "QG1", "QGD", "QID", "QLD", "QPD", "QRD", "QRT", "QTP", "QTH", "QTP", "QWD", "SBT", "SCA", "SCB", "SCC", "SCD", "SCE", "SCF", "SCG", "SCH", "SCI", "SCJ", "SCK", "SCL", "SCM", "SCN", "SCO", "SCP", "SCQ", "SCR", "SCS", "SCT", "SCU", "SCV", "SCW", "SCX", "SCY", "SCZ", "SDG", "SDL", "SDT", "SIO", "SOH", "SMD", "SNI", "SPK", "SPO", "SRD", "SSL", "SSQ", "STH", "SWR", "TSA", "TSB", "TSC", "TSD", "TSE", "TSF", "TSG", "TSH", "TSI", "TSJ", "TSK", "TSL", "TSM", "TSN", "TSO", "TSP", "TSQ", "TSR", "TSS", "TST", "TSU", "TSV", "TSW", "TSX", "TSY", "TSZ", "TS0", "TS1", "TS2", "TS3", "TS4", "TS5", "TS6", "TS7", "TS8", "TS9", "VAP", "VCE", "VCO", "VCQ", "VDT", "VEA", "VEB", "VEC", "VED", "VEE", "VEF", "VEG", "VEH", "VEI", "VEJ", "VEK", "VEL", "VEM", "VEN", "VEO", "VEP", "VEQ", "VER", "VES", "VET", "VEU", "VEV", "VEW", "VEX", "VEY", "VEZ", "VFP", "VKI", "VPB", "VMA", "VMB", "VMC", "VMD", "VME", "VMF", "VMG", "VMH", "VMI", "VMJ", "VMK", "VML", "VMM", "VMN", "VMO", "VMP", "VMQ", "VMR", "VMS", "VMT", "VMU", "VMV", "VMW", "VMX", "VMY", "VMZ", "VM0", "VM1", "VM2", "VM3", "VM4", "VM5", "VM6", "VM7", "VM8", "VM9", "VPB" does not trigger [Validation tests](https://github.com/iris-edu/StationXML-Validator/wiki/Validation-tests) that are subject to this restriction.
* **[C2](https://github.com/iris-edu/StationXML-Validator/blob/master/Validator_TestSuite/Restrictions/P1_C2.xml)** : Channel:Type == "HEALTH", "FLAG", "MAINTENANCE" does not trigger [Validation tests](https://github.com/iris-edu/StationXML-Validator/wiki/Validation-tests) that are subject to this restriction.

# Response
* **[R1](https://github.com/iris-edu/StationXML-Validator/blob/master/Validator_TestSuite/Restrictions/P1_R1.xml)** : Channels containing Response:InstrumentPolynomial at stage 0 do not trigger [Validation tests](https://github.com/iris-edu/StationXML-Validator/wiki/Validation-tests) that are subject to this restriction.
u* **[R1](https://github.com/iris-edu/StationXML-Validator/blob/master/Validator_TestSuite/Restrictions/P1_R1.xml)** : Channels containing Response:InstrumentPolynomial at stage 0 do not trigger [Validation tests](https://github.com/iris-edu/StationXML-Validator/wiki/Validation-tests) that are subject to this restriction.

[As of 2018-08-24]
[As of 04-2020]

0 comments on commit 76a8e6a

Please sign in to comment.