Noise Toolkit Polarization Attributes package V.2

DESCRIPTION:

The IRIS DMC Noise Toolkit Polarization Attributes (POLAR) package is a collection of 3 Python scripts that are configurable and allow users to conveniently calculate and extract polarization attributes of 3-C seismic data. Although this package takes advantage of the FDSN Web service client for ObsPy to retrieve necessary waveform data, but it also allows users to process waveform data from their local files. This package is a standalone package that directly computes the spectra of the input waveform data in order to form the corresponding spectra covariance matrix for polarization analysis. As such, to use this package running other packages of the Noise Toolkit is not necessary.

The scripts included in this package are:

ntk_computePolarization.py – to calculate polarization parameters for a given station and time window
ntk_extractPolarHour.py – to extract polarization parameters for the given channels and bounding parameters. The output is similar to the output of the ntk_extractPsdHour.py script of the PDF/PSD package with addition of polarization attributes.
ntk_binPolarDay.py – to bin polarization attributes to daily files for a given channel tag and bounding parameters. The output is similar to that of the ntk_binPsdDay.py script of the PDF/PSD package with addition of polarization attributes.

The output of the polarization scripts also includes power as a function of frequency for the vertical component, the east-west component and the north-south component and the principal eigenvalue (λ).

QUICK START

Installation:

See also the package’s INSTALL.txt file

install Python 3.8 or higher on your computer

additional required Python modules are:
. obspy 1.2.2
. matplotlib 3.3.3
. numpy 6.2
. scipy 1.5.3

download the package under the installation directory.

Note: if you are installing this package on a PC, edit the param/chared.py file and set the namingConvention parameter to ‘WINDOWS’

Running the scripts:

under the root directory of the Noise Toolkit execute the following command to plot polarization attributes of the NM.SLM.00.BH? data for 2 one hour windows with 50% overlap starting at 2009-01-01 01:00:00.0:

python bin/ntk_computePolarization.py param=computePolarization net=NM sta=SLM loc=DASH start=2009-01-01T01:00:00 end=2009-01-01T03:00:00 type=frequency plot=1

Plot generated by the ntk_computePolarization.py script showing power and polarization parameters obtained by processing one hour of BHZ, BHN, BHE data of the NM.SLM station (St. Louis, MO station, Cooperative New Madrid Seismic Network, NM) between 2009-01-01 01:00:00.0 and 2009-01-01 02:00:00.0 UTC.

review all parameter files located under the param directory to get familiar with the script capabilities
use examples given below to run/test the scripts and become familiar with them
edit the parameter files under the param directory to change parameters based on your needs

NOTES

for more information visit the IRIS DMC Noise Toolkit Data Product web page at:
ds.iris.edu/ds/products/noise-toolkit

examples below may turn on the verbose mode. Once you have configured the script, you can turn it off (verbose=0)

COMMENTS/QUESTIONS/SUGGESTIONS:

We welcome patches and enhancements to this software. When developing patches, please pay particular attention to ease of use and maintenance and also keep dependencies to a minimum.
for issues, file a ticket under Issues

HISTORY

V.2.0.0 2016-11-16: Python 3, use of Fedcatalog and adoption of PEP 8 style guide
V.0.6.5 2017-01-18: support for reading data and metadata from files only with no Internet requirement
V.0.6.0 2016-11-01: added support for obtaining channel responses from local station XML response files by introducing the following two functions in tsLIB.py:
getResponseInventory – to build a list of response inventories under a given met directory
getResponseFromFile – to find response for a given Network, Station, Location cnd channel
added respDirectory to common.py parameter file to disable looking for response files on local drives, set this parameter to None. Otherwise, set it to the response directory path
V.0.5.1 2016-01-25: added user and password parameters to common.par and ntk_computePSD.py in support of restricted data access
V.0.5.0 2015-09-15: Beta release

USER’S GUIDE

Use below examples to run/test the scripts and become familiar with them. Edit the parameter files under the IRIS_NTK/param directory to change parameters based on your needs.

SCRIPT: ntk_computePolarization.py

compute polarization parameters for a given station and time window using command arguments and the associated parameters in the configuration files

USAGE:

	* ntk_computePolarization.py to display the usage message

	  OR

	* ntk_computePolarization.py param=FileName client=[FDSN|FILES] net=network sta=station loc=location chan=channel(s) start=YYYY-MM-DDTHH:MM:SS end=YYYY-MM-DDTHH:MM:SS xtype=[period|frequency] plot=[0|1] verbose=[0|1] timing=[0|1]

	to perform computations where:
	  param		[default: computePolarization] the configuration file name 
	  client	[default: FDSN] client to use to make data/metadata requests (FDSN or FILES) 
	  net		[required] network code
	  sta		[required] station code
	  loc		[required] location ID
	  chan		[default: BH?] channel ID(s); separate multiple channel codes by comma (no space)
	  xtype		[period or frequency, default: period] X-axis type (period or frequency for outputs and plots)
	  start		[required] start date-time (UTC) of the interval for which PSDs to be computed (format YYYY-MM-DDTHH:MM:SS)
	  end		[required] end date-time (UTC) of the interval for which PSDs to be computed (format YYYY-MM-DDTHH:MM:SS)
	  sw_width	[default: 0.25] Smoothing window width in octave
	  sw_shift	[default: 0.125] Smoothing window shift in fraction of octave
	  plot		[0 or 1, default: 0] to run in plot mode set to 1
	  plotnm	[0 or 1, default 1] plot the New High/Low Noise Models [0|1]
	  timing	[0 or 1, default: 0] to run in timing mode (set to 1 to output run times for different segments of the script)
	  verbose	[0 or 1, default: 0] to run in verbose mode set to 1

NOTES & EXAMPLES:

Use the run in plot or verbose mode to tune the parameters before a production run (verbose=0, minimum message output):

usage:
python bin/ntk_computePolarization.py

compute and output polarization parameters to files:
python bin/ntk_computePolarization.py net=TA sta=O18A loc=DASH start=2008-08-14T12:00:00 end=2008-08-14T13:30:00

compute and output polarization parameters (as a function of frequency) to files and also plot them:
python bin/ntk_computePolarization.py net=TA sta=O18A loc=DASH start=2008-08-14T12:00:00 end=2008-08-14T13:00:00 xtype=frequency plot=1

apply more smoothing:
python bin/ntk_computePolarization.py param=computePolarization net=TA sta=O18A loc=DASH start=2008-08-14T12:00:00 end=2008-08-14T13:00:00 xtype=period sw_width=0.5 sw_shift=0.25 plot=1

python bin/ntk_computePolarization.py param=computePolarization net=TA sta=O18A loc=DASH start=2008-08-14T12:00:00 end=2008-08-14T13:30:00 xtype=period sw_width=1 plot=1

python bin/ntk_computePolarization.py param=computePolarization net=TA sta=959A loc=DASH start=2013-10-01T11:00:00 end=2013-10-01T13:00:00 xtype=period plot=1

If you already have your waveform data saved on a local storage under format such as SAC, MSEED, CSS, etc.
(see #supported-formats at http://docs.obspy.org/packages/autogen/obspy.core.stream.read.html#supported-formats)
then you can instruct the script to get the waveform data from these files and connect to Web Services for the response information only. To do this you need to update two parameters in your parameter file (such pas param/computePolarization.py):

set

requestClient = "FILES" to flag the script that the waveform data are coming from file fileTag = "{IRIS_NTK_PSD}/data/TEST/SAC/W*.SAC" to tell it which files to look at

python bin/ntk_computePolarization.py net=TA sta=O18A loc=DASH start=2008-08-14T12:00:00 end=2008-08-14T13:30:00 type=period client=FILES plot=1

the most time consuming part of the process is the waveform request. Keep your requests at reasonable size. Requesting

too many stations may cause timeouts. Script will only write the timeout message and has no way of handling it. Even for
smaller requests there is a chance that data requests fail when timeout is reported. User should scan the output messages
and re-queue the timed out requests again.

for production runs run one or more instances of scripts as a background process. In our limited testing each

3-channel 1 hour time window with 50% overlap takes about 17 seconds to process.

nohup python bin/ntk_computePolarization.py param=computePolarization net=TA sta=W56A loc=DASH start=2014-03-17T04:30:00 end=2014-03-17T05:30:00 type=frequency mode=time >& /tmp/polarW56A_2014 &
for more information on FDSN WS specifications see

"www.fdsn.org/webservices/FDSN-WS-Specifications-1.1.pdf":http://www.fdsn.org/webservices/FDSN-WS-Specifications-1.1.pdf

SCRIPT: ntk_extractPolarHour.py

a Python script to extract polarization parameters for the given bounding parameters.

USAGE:

python bin/ntk_extractPolarHour.py param=extractPolarHour net=NM sta=SLM loc=DASH chandir=BHZ_BHE_BHN start=2009-01-01T00:00:00 end=2009-01-02T00:00:00 type=frequency mode=0

param: configuration file name 
net: network code
sta: station code
loc: location identifier
start: interval start date time
end: interval end date time
type: x-axis type (period or frequency)
mode:  verbose - run in verbose mode; 0 - run with minimum message output

INPUT:

The ntk_computePolarization.py output files

NOTES & EXAMPLES:

The output is similar to the output of the ntk_extractPsdHour.py script of the PDF/PSD bundle and PQLX’s exPSDhour script

with additional polarization attributes. The output path/file name are displayed at the end of the run.

python bin/ntk_extractPolarHour.py param=extractPolarHour net=NM sta=SLM loc=DASH chandir=BHZ_BHE_BHN start=2009-01-01T00:00:00 end=2009-01-02T00:00:00 type=period mode=0

SCRIPT: ntk_binPolarDay.py

A Python script to bin polarization attributes to daily files for a given channel tag and bounding parameters.

USAGE:

  <br /><br />                                                      
python bin/ntk_binPolarDay.py param=binPolarDay net=NM sta=SLM loc=DASH chandir=BHZ_BHE_BHN start=2009-01-01 end=2009-01-02 type=frequency mode=0
   
param: configuration file name 
net: network code
sta: station code
loc: location identifier
chandir: channel directory
start: interval start date time
end: interval end date time
type: x-axis type (period or frequency)
mode: plot - verbose - run in verbose mode; 0 - run with minimum message output

INPUT:

The ntk_computePolarization.py output files

NOTES & EXAMPLES:

python bin/ntk_binPolarDay.py param=binPolarDay net=NM sta=SLM loc=DASH chandir=BHZ_BHE_BHN start=2009-01-01 end=2009-01-02 type=frequency mode=0
Full path to the output data file(s) is provided at the end of the run. You may turn off hourly file output via the configuration file

This bundle is provided by the IRIS DMC Data Products Team WITHOUT ANY WARRANTY AND/OR SUPPORT This is a free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This script is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License (GNU-LGPL) for more details. The GNU-LGPL and further information can be found here: www.gnu.org You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Noise Toolkit docs:

Previous release (V.1) docs:

Legacy Noise Toolkit Overview

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Noise Toolkit Polarization Attributes package V.2

DESCRIPTION:

QUICK START

Installation:

Running the scripts:

NOTES

COMMENTS/QUESTIONS/SUGGESTIONS:

HISTORY

USER’S GUIDE

SCRIPT: ntk_computePolarization.py

USAGE:

NOTES & EXAMPLES:

SCRIPT: ntk_extractPolarHour.py

USAGE:

INPUT:

NOTES & EXAMPLES:

SCRIPT: ntk_binPolarDay.py

USAGE:

INPUT:

NOTES & EXAMPLES:

COPYRIGHT © 2015 Product Team, IRIS Data Management Center

Noise Toolkit docs:

Clone this wiki locally