Add docs directly to repository

docs/_config.yml

@@ -0,0 +1,4 @@
+name: EarthScope
+title: fetch-scripts - command line scripts for accessing seismological data
+markdown: kramdown
+auto: true

docs/fetchsyn.md

@@ -0,0 +1,68 @@
+## Python dependencies
+
+The requests library is needed.  Currently `FetchSyn` is compatible with python 2 & 3.
+
+## Executing the scripts
+
+After downloading the scripts they can be executed from the command line either by explicitly invoking python or by making the scripts executable and installing the path to python in the first line.  To explicitly invoke python to execute a script type the following:
+
+```Console
+$ python FetchSyn
+```
+
+## Help menu to list parameters
+
+To access the help menu, which lists all input parameters:
+
+```Console
+$ FetchSyn -u
+```
+
+## Examples
+
+To generate a synthetic for IU.ANMO for the Tohoku earthquake using it's GCMT origin and moment tensor:
+
+```Console
+$ FetchSyn -N IU -S ANMO -evid GCMT:M201103110546A
+```
+
+Same request, but add station KIP and make the source depth 35km and return the vertical (Z), radial (R) and transverse (T) components rather than the default ZNE components:
+
+```Console
+$ FetchSyn -N IU -S ANMO,KIP -C ZRT -evid GCMT:M201103110546A -sdepm 35000
+```
+
+
+Same request, but:
+* include all stations in the virtual network _GSN
+* use a different [model](http://ds.iris.edu/ds/products/syngine/#models)
+* change the sample rate to 0.05 sps
+* make the output miniseed rather than saczip
+* return velocity not the default (displacement)
+* cut the traces to 10 seconds before P
+* make traces 300 seconds in duration
+* add user-agent identification (helps DMC & helps you if there are problems)
+
+```Console
+$ FetchSyn -N _GSN -model prem_a_20s -dt 0.05 -format mseed -units velocity -start P-10 -end 300 -A "Joe Seismologist" -C ZRT -evid GCMT:M201103110546A -sdepm 35000
+```
+
+### Manually input source and use a file with a list of receivers
+
+Example using a text file with receiver names.  Each line of the receiver file is an example of valid formatting.  The networkcode, stationcode, locationcode in the later lines is optional.
+
+rec.txt:
+```Console
+IU ANMO 
+II *
+-89 -179
+-89 -178 S0002
+-89 -177 N2 S0003 L2
+```
+
+Manually input the origin using a double couple source (strike,dip,rake[,optional_scalar_moment_in_NM])
+
+```Console
+$ FetchSyn -recfile rec.txt -origin 2011,03,11,05,46,24 -slat 38.3 -slon 142.3 -sdepm 24400 -dc 203,10,88,5.3e22 -C Z
+```
+

docs/index.md

@@ -0,0 +1,63 @@
+# Command line scripts for accessing data via FDSN and other web services
+
+The scripts are written in Perl and Python and should run on most systems
+with that language support.
+
+## Overview of scripts
+
+**[FetchData](FetchData)** (Perl) - Fetch time series and optionally, related metadata, matching SAC Poles and Zeros and matching SEED RESP files. Time series data are returned in miniSEED format, metadata is saved as a simple ASCII list.
+
+**[FetchEvent](FetchEvent)** (Perl) - Fetch event parameters and print simple text summary.  Works with any fdsnws-event service.
+
+**[FetchSyn](FetchSyn)** (Python) - Fetch synthetics seismograms from the [EarthScope Syngine](https://service.iris.edu/irisws/syngine/1/) service.  See (FetchSyn usage)[fetchsyn.md]
+
+## Quick start
+
+1. Download the latest version of desired scripts at the links above
+1. Make the scripts executable (e.g 'chmod +x FetchData') if needed
+1. Run script to print usage message
+
+## Documentation and examples
+
+Further description and example usage can be found [in the tutorial](tutorial.md)
+
+## Using the scripts with other data centers
+
+See documentation on [using the scripts with other data centers](other-centers.md)
+
+## Perl requirements
+
+The Perl scripts should run with any relatively recent Perl interpreter.  In some cases, particularly for older Perl releases, you might need to install some required modules, namely **XML::SAX** and **Bundle::LWP** (libwww-perl).  The procedure to install these modules is system dependent, for most Unix/Linux OSes they can be installed using the package management system.  In addition to Perl only network access to the EarthScope web services is needed.
+
+For large data requests installing the **XML::SAX::ExpatXS** Perl module will significantly increase the parsing speed of XML metadata used by all scripts.
+
+## Running the Perl scripts on Windows
+
+Most Windows computers do not have Perl by default and one must be installed.  Any distribution of Perl should work as long as the required modules are included.  The [Strawberry Perl](http://strawberryperl.com/) distribution for Windows is known to work and is recommended.
+
+Once installed, the Fetch scripts may be run from a command prompt (e.g. Windows PowerShell) by typing **perl** followed by the name of the script.  For example:
+
+```Console
+PS C:\Users\username\Downloads> perl .\FetchData
+```
+
+**Note**: the Fetch scripts are command-line oriented with no GUI, double-clicking them in Explorer using does not do anything useful.
+
+## Copyright and License
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Copyright (c) 2018 EarthScope Consortium
+
+<!-- GitHub corner from https://github.com/tholman/github-corners -->
+<a href="https://github.com/EarthScope/fetch-scripts" class="github-corner" aria-label="View source on GitHub"><svg width="80" height="80" viewBox="0 0 250 250" style="fill:#70B7FD; color:#fff; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true"><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a><style>.github-corner:hover .octo-arm{animation:octocat-wave 560ms ease-in-out}@keyframes octocat-wave{0%,100%{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}@media (max-width:500px){.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:octocat-wave 560ms ease-in-out}}</style>

docs/other-centers.md

@@ -0,0 +1,64 @@
+## Overview
+
+The Fetch scripts may be used to access information at other data centers as long as the service interfaces are compatible with the versions offered by EarthScope.  Many of the services are [standardized by the FDSN](https://fdsn.org/webservices/) and offered by other data centers.  By default, the scripts are configured to fetch information from EarthScope.  Alternate locations of service interfaces may be specified.
+
+## Specifying alternate service locations using environment variables
+
+Default service locations can be overridden by setting the following environment variables:
+
+**SERVICEBASE** = the base URI of the service(s) to use (http://service.iris.edu/)
+
+**TIMESERIESWS** = complete URI of service (http://service.iris.edu/fdsnws/dataselect/1)
+
+**METADATAWS** = complete URI of service (http://service.iris.edu/fdsnws/station/1)
+
+**EVENTWS** = complete URI of service (http://service.iris.edu/fdsnws/event/1)
+
+**SACPZWS** = complete URI of service (http://service.iris.edu/irisws/sacpz/1)
+
+**RESPWS** = complete URI of service (http://service.iris.edu/irisws/resp/1)
+
+The *SERVICEBASE* variable will be used for all services if set.  The other, service-specific variables, are explicit paths to each service.  The service-specific variables are useful if the path after the hostname is different than used by the IRIS DMC, or if users wish to use services at different data centers (e.g. events from one center and time series from another).
+
+## Specifying alternate service locations using command line options
+
+Default service locations can be overridden by specifying the following command line options:
+
+`-timeseriesws`
+
+`-metadataws`
+
+`-eventws`
+
+`-sacpzws`
+
+`-respws`
+
+Obviously, each script only accepts the argument(s) appropriate for its operation.
+
+## Wrapper scripts for other accessing other data centers
+
+Simple shell wrapper scripts can be created to redirect access to alternate locations.  For example:
+
+**FetchData-IRISDMC**:
+```bash
+#!/bin/bash
+
+# Set servce base path, change to your own service host
+SERVICEBASE="http://service.iris.edu"
+
+# Set all service specific locations using the service base
+TIMESERIESWS="${SERVICEBASE}/fdsnws/dataselect/1"
+METADATAWS="${SERVICEBASE}/fdsnws/station/1"
+EVENTWS="${SERVICEBASE}/fdsnws/event/1"
+SACPZWS="${SERVICEBASE}/irisws/sacpz/1"
+RESPWS="${SERVICEBASE}/irisws/resp/1"
+
+export SERVICEBASE TIMESERIESWS METADATAWS EVENTWS SACPZWS RESPWS
+
+exec FetchData "$@"
+```
+
+The above script can be customized to redirect all traffic to an alternate data center by replacing the URLs with another location.
+
+

docs/tutorial.md

@@ -0,0 +1,155 @@
+## Executing the scripts
+
+After downloading the scripts they can be executed from the command line either by explicitly invoking Perl or by making the scripts executable and letting the OS run Perl for you. To explicitly invoke Perl to execute a script type the following:
+
+```Console
+$ perl FetchData
+```
+
+To make a script executable on the Unix-like operating system use the `chmod` command, after which the script can be run like any other program from the command line:
+
+```Console
+$ chmod +x FetchData
+$ ./FetchData
+```
+
+## Requesting miniSEED and simple metadata using `FetchData`
+
+To request the first hour of the year 2011 for BHZ channels from GSN stations, execute the following command:
+
+```Console
+$ FetchData -N _GSN -C BHZ -s 2011-01-01T00:00:00 -e 2011-01-01T01:00:00 -o GSN.mseed -m GSN.metadata
+```
+
+Note that the network specification used is a virtual network code; regular network codes may also be specified. The start and end times are specified in an ISO defined format, with a capital 'T' separating the date from the time. Commas are also permissible to separate the date and time components.
+
+The received miniSEED will be saved to the `GSN.mseed` file and simple ASCII metadata will be saved to the `GSN.metadata` file. These two files can be used to convert the data to SAC format with the [mseed2sac](https://github.com/EarthScope/mseed2sac):
+
+```Console
+$ mseed2sac GSN.mseed -m GSN.metadata
+```
+
+## Requesting event information for magnitude 6+ events within 10 degrees of location
+
+To request magnitude 6+ events within 20 degrees of the main shock of the Tohoku-Oki, Japan Earthquake on or after March 11th 2011, execute the following command:
+
+```Console
+$ FetchEvent -s 2011-03-11 --radius 38.2:142.3:20 --mag 6
+```
+
+h2. Requesting data from multiple data centers (federating)
+
+If the `-F` option is used with FetchData (version 2015.014 and later) it will first submit the request to the IRIS Federator to determine which data centers have data matching the criteria, then it will make a request to each data center to retrieve the miniSEED.
+
+For example, the request 1+ hour of global LHZ channels for the 1995 Mw 8.0 Chile earthquake a command like this may be suitable:
+
+```Console
+$ FetchData -F -C LHZ -s 1995-7-30T05:11:23 -e 1995-7-30T06:30:00 -o event.mseed -m event.meta
+```
+
+*Note*: not all FDSN data centers support the direct retrieval of metadata in SEED RESP and SAC PZ formats, consequently requesting such information when federating the request will usually fail with some data centers.  Simple metadata, as saved by the *-m* option, should always work as it only relies on a compliant fdsnws-station service.
+
+## Wildcards and lists
+
+The network, station, location and channel selections may include both wildcards and lists. The supported wildcards are *, meaning zero to many characters, and ?, meaning a single character. Example wildcard usage: 'BH*' and 'L??'. A list is specified as simple comma-separated values, for example: 'BHE,BHN,BHZ'. Illustrating both of these features using command line selections (the same applies to the selection list file):
+
+```Console
+$ FetchData -N IU -S ANMO,COLA -C 'BH*,LH*' -s 2011-01-01T00:00:00 -e 2011-01-01T01:00:00 -o ANMO-COLA.mseed
+```
+
+Note that the wildcard characters usually need to be quoted to avoid them being interpreted by the shell.
+
+## Selecting data by region
+
+The FetchData script allows data selection by geographic region in two ways: 1) specifying minimum and maximum latitude and/or longitude and 2) specifying a point and a maximum radius in degrees including the optional specification of a minimum radius to define a circular range from a point. For example, to request 10 minutes of miniSEED data for all BHZ channels available within 10 degrees of the M5 2010 Ottowa, Canada earthquake at latitude 45.88 and longitude -75.48 try the follow:
+
+```Console
+$ FetchData -radius 45.88:-75.48:10 -m OttowaM5.meta -o OttowaM5.mseed -C BHZ -s 2010-06-23T17:41 -e 2010-06-23T17:51
+```
+
+## Large data selections
+
+To specify many selections or combinations not possible using the command line options the Fetch scripts can read a file containing either a simple ASCII selection list or a BREQ_FAST formatted request.
+
+For a file containing a selection list use the -l option:
+
+```Console
+$ FetchData -l myselection.txt -o mydata.mseed
+```
+
+The expected selection list format is documented [below](#Selection-List-Format).
+
+For a file containing a legacy BREQ_FAST-formatted request use the -b option:
+
+```Console
+$ FetchData -b mybreqfast.txt -o mydata.mseed
+```
+
+## Reducing data segmentation
+
+Specific to FetchData are two options for limiting the level of segmented data returned:
+
+* `-msl _length_` :: Specify minimum segment length in seconds, no segments shorter than length will be returned
+* `-lso` :: Return only the longest segment from each distinct channel
+
+Warning: These options limit the data returned, using them incorrectly or when data is very gappy can result in no returned data. These options do not fill gaps. 
+
+## Requesting SEED RESP or SAC Poles and Zeros files with miniSEED data
+
+The `FetchData` script can collect the SEED RESP or SAC Poles and Zeros matching the requested data at the same time it collects the time series data. An individual RESP and/or SACPZ file is created for each channel requested. You must specify an existing directory to which to write the files.
+
+To collect SEED RESP with data use the -rd option (using a dot for the current directory):
+
+```Console
+$ FetchData -S COLA -C BHZ -s 2011-01-01T00:00:00 -e 2011-01-01T01:00:00 -o COLA.mseed -rd .
+```
+
+To collect SAC Poles and Zeros with data use the `-sd` option (using a dot for the current directory):
+
+```Console
+$ FetchData -S COLA -C BHZ -s 2011-01-01T00:00:00 -e 2011-01-01T01:00:00 -o COLA.mseed -sd .
+```
+
+## Selecting a blank (space-space) SEED location ID
+
+Many SEED location IDs are blank. Since these location IDs are stored as a 2-character field in the SEED format a blank location ID means the field is actually 2 ASCII space characters. To specifically select blank location IDs space characters may be used. Because spaces can sometimes be troublesome to provide exactly in scripts, in selection files, etc. the web services will also accept IDs specified as '--' (two dashes) which will be mapped to spaces.
+
+## Selection List Format
+
+All of the Fetch scripts which request information about time series channels will accept a selection list to define the request.
+
+A selection list is simply an ASCII file where each line specifies a complete data selection containing the following space-separated values:
+
+```
+Network Station Location Channel StartTime EndTime
+```
+
+For example, a selection list for a small time window for BHZ channels from the selected GSN stations would be:
+
+```
+II AAK 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+II ABKT 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+II ABPO 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+II ALE 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+II ARU 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+II ASCN 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+II BFO 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+II BORG 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+IU ADK 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+IU AFI 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+IU ANMO 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+IU ANTO 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+IU BBSR 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+IU BILL 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+IU CASY 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+IU CCM 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+IU CHTO 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+IU COLA 00 BHZ 2011-01-01T00:00:00 2011-01-01T01:00:00
+```
+
+With this selection list saved to a file name `myselection.txt` it can be used, for example, like this:
+
+```Console
+$ FetchData -l myselection.txt -o mydata.mseed
+```
+