Noise Toolkit Polarization Attributes package V.2

DESCRIPTION (V.2.0):

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

SCRIPT: ntk_extractPolarHour.py

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

USAGE:

	* python bin/ntk_extractPolarHour.py to display the usage message (this message)

	  OR

	* python bin/ ntk_extractPolarHour.py param=FileName net=network sta=station loc=location chandir=channel_directory start=YYYY-MM-DDTHH:MM:SS end=YYYY-MM-DDTHH:MM:SS xtype=[period|frequency] verbose=[0|1]

	to perform extraction where:
	  param		[default: extractPolarHour] the configuration file name 
	  net		[required] network code
	  sta		[required] station code
	  loc		[required] location ID
	  chandir	[default: BHZ_BHE_BHN] is the channel directory under polarDb where the polarization output files are stored
	  xtype		[period or frequency, default: period] X-axis type (period or frequency for outputs and plots)
	  start		[required] start date-time (UTC) for extraction (format YYYY-MM-DDTHH:MM:SS)
	  end		[required] end date-time (UTC) for extraction (format YYYY-MM-DDTHH:MM:SS)
	  verbose	[0 or 1, default: 0] to run in verbose mode set to 1

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.

usage:
python bin/ntk_extractPolarHour.py

assuming that you already have executed the following command to generate polarization files:
python bin/ntk_computePolarization.py net=NM sta=SLM loc=DASH start=2009-01-01T01:00:00 end=2009-01-01T03:00:00 xtype=frequency verbose=0

you can perform extraction via:
python bin/ntk_extractPolarHour.py param=extractPolarHour net=NM sta=SLM loc=DASH chandir=BHZ_BHE_BHN start=2009-01-01T01:00:00 end=2009-01-01T0:00:00 xtype=frequency verbose=0

SCRIPT: ntk_binPolarDay.py

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

USAGE:

                                                     
	* python bin/ntk_binPolarDay.py display the usage message

	  OR

	* python bin/ntk_binPolarDay.py param=FileName net=network sta=station loc=location chandir=channel_directory start=YYYY-MM-DDTHH:MM:SS end=YYYY-MM-DDTHH:MM:SS xtype=[period|frequency] verbose=[0|1]

	to perform extraction where:
	  param		[default: binPolarDay] the configuration file name 
	  net		[required] network code
	  sta		[required] station code
	  loc		[required] location ID
	  chandir	[default: BHZ_BHE_BHN] is the channel directory under polarDb where the polarization output files are stored.
	  xtype		[period or frequency, default: period] X-axis type (period or frequency for outputs and plots)
	  start		[required] start date-time (UTC) for extraction (format YYYY-MM-DDTHH:MM:SS)
	  end		[required] end date-time (UTC) for extraction (format YYYY-MM-DDTHH:MM:SS)
	  verbose	[0 or 1, default: 0] to run in verbose mode set to 1

INPUT:

The ntk_computePolarization.py output files

OUTPUT:

Full paths to the daily and hourly output data files are provided at the end of the run. You may turn off hourly file output via the configuration file.

The daily and hourly output file names have the following form respectively:
D?.bin and H?.bin (??? represents 3-digit day of the year)
for example:
D227.bin and H227.bin

NOTES & EXAMPLES:

usage:
python bin/ntk_binPolarDay.py

assuming that you already have executed the following command to generate polarization files:
python bin/python ntk_computePolarization.py net=NM sta=SLM loc=DASH start=2009-01-01T01:00:00 end=2009-01-01T03:00:00 xtype=frequency verbose=0

you can bin the polarization parameters into daily files:
python bin/ntk_binPolarDay.py param=binPolarDay net=NM sta=SLM loc=DASH start=2009-01-01T01:00:00 end=2009-01-01T03:00:00 xtype=frequency verbose=0

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 (V.2.0):

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:

NOTES & EXAMPLES:

SCRIPT: ntk_binPolarDay.py

USAGE:

INPUT:

OUTPUT:

NOTES & EXAMPLES:

COPYRIGHT © 2020 Product Team, IRIS Data Management Center

Noise Toolkit docs:

Clone this wiki locally