Noise Toolkit Microseism Energy (ME) package V.2

DESCRIPTION:

This package contains 3 Python scripts to:

• calculate power of each PSD window (by default 1 hour) over selected bins (period bands)
• calculate median power from the PSD powers (by default hourly PSD power) using a sliding window of a given length (e.g., 12 hours)
• plot median powers computed from a series of PSD powers

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:
  . matplotlib 3.3.3
  . numpy 6.2

• download the package under the installation directory.

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

Running the scripts:

If you want to go through a complete cycle of microseism computation, including PSD calculations, the steps are:

1. compute PSD for the Z-component
2. bin the hourly PSD’s
3. compute power from the PSD values
4. compute the median power using a sliding 6 hour window
5. plot the secondary microseism energy for the Z-component (see image below)

If you already have a PSD file:

with format similar to the output of either ntk_extractPsdHour.py script (see the NTK PSD/PDF package) or PQLX’s exPSDhour script, use examples provided in the following sections:

1. compute power from the PSD values by running the bin/ntk_computePower.py script
2. use the bin/ntk_medianPower.py script to obtain the median power over the desired window length from the computed PSD powers in the previous step
3. plot the median power obtained in the previous step by running the bin/ntk_plotPower.py script

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
2020-11-16 V.2.0.0: Python 3 and adoption of PEP 8 style guide.
2015-04-22 file name correction
2014-11-24 V.0.5.0: Beta release to compute power based on a combined PSD file
with format similar to output of the ntk_extractPsdHour.py script (see NTK PSD/PDF bundle)

• 2013-10-07 revision for production test
• 2013-03-14 created

USER"S GUIDE

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

Parameters

All parameters are under the param directory. The “shared.py” parameter file contains basic parameters shared by all parameter files. Please review ALL parameter to familiarize yourself with the script capabilities. For more information about this package, visit the IRIS DMC Noise Toolkit Data Product web page at:

http://ds.iris.edu/ds/products/noise-toolkit/

Script: ntk_computePower.py

calculate power of each PSD window (by default 1 hour) over selected bin period bands as defined in the parameter file

Usage:

	@python bin/ntk_computePower.py to display the usage message@
 
	  OR

	@python bin/ntk_computePower.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: computePower] the configuration file name 
	 net		[required] network code
	 sta		[required] station code
	 loc		[required] location ID
	 chan		[required] channel ID. 
	 xtype		[required, period or frequency] X-axis type for the PSD files.
	 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
	 file		[required] the "combined" PSD file (similar to the output of the ntk_extractPsdHour.py script)to read.

For more information visit:

ds.iris.edu/ds/products/noise-toolkit-me/

notes:

• In all examples it is assumed that the command is issued under the root/ directory
• The input PSD file should have the same format as the output of the ntk_extractPsdHour.py
  script (see NTK PSD/PDF bundle) or PQLX’s exPSDhour script
• Use the run in verbose mode to tune the parameters before a production run (verbose=0):

Examples:

* usage:
python bin/ntk_computePower.py

* assuming that you already have executed the following command to generate PSD files:
python bin/ntk_extractPsdHour.py net=TA sta=O18A loc=DASH chan=BHZ start=2008-08-14T12:00:00 end=2008-08-14T12:30:00 xtype=period

* compute power via:
python bin/ntk_computePower.py param=computePower net=TA sta=O18A loc=DASH chan=BHZ xtype=period verbose=1 file=TA.O18A.--.BHZ.2008-08-14.2008-08-14.period.txt

Script: ntk_medianPower.py

a Python script to calculates median power for a given window length from the computed PSD powers

Usage:

ntk_medianPower.py to display the usage message (this message)

	  OR

	ntk_medianPower.py param=FileName net=network sta=station loc=location chan=channel  start=YYYY-MM-DDTHH:MM:SS end=YYYY-MM-DDTHH:MM:SS win=hour verbose=[0|1] file=PSD_file_name
	to compute median power where:
	  param		[default: medianPower] the configuration file name 
	  net		[required] network code
	  sta		[required] station code
	  loc		[required] location ID
	  chan		[required] channel ID
	  win		[required] smoothing window length in hours 
	  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)
	 file		[required] PSD file name
	  verbose	[0 or 1, default: 0] to run in verbose mode set to 1

Input: 
	The input PSD power file is expected to be under the "POWER" directory and should have the same format as the output of ntk_computePower.py script. 
	The "computePower" parameter file can be used as the input parameter file for this script also.

Output: 
	The smooth PDFs are stored  under the corresponding "POWER"/window directory:
	Win(h)     Dir
	   6    ->  6h
	  12    -> 12h
	  24    ->  1d
	  96    ->  4d
	 384    -> 16d


h5.  Input:

 The *bin/ntk_computePower.py* output file is the input file for this script and is expected to be under the *POWER* directory. The *computePower* parameter file can be used as the input parameter file for this script.

 h5. output:

 The smoothed PDFs are stored in the 'POWER' directory under the 
 corresponding window directory:

 Win(h)     Dir
   6    ->  6h
  12    -> 12h
  24    ->  1d
  96    ->  4d
 384    -> 16d   

NOTES:

The output file name is printed at the end of the run and should be used when calling the plot script

examples:

* usage:
python bin/ntk_medianPower.py

* assuming that you have already computed power via:
python bin/ntk_computePower.py param=computePower net=TA sta=O18A loc=DASH chan=BHZ xtype=period verbose=1 file=TA.O18A.--.BHZ.2008-08-14.2008-08-14.period.txt

* then, compute median power via:
python bin/ntk_medianPower.py param=medianPower net=TA sta=O18A loc=DASH chan=BHZ xtype=period verbose=0 win=12 start=2008-08-14T00:00:00 end=2008-08-14T23:00:00 file=TA.O18A.--.BHZ.2008-08-14.2008-08-14.txt

Script: ntk_plotPower.py

A Python script to plot median power obtained from the median power file produced by ntk_medianPower.py

Usage:

                               configuration  net   station    loc     chan     start date time     end date time            smoothing window (hours)
                                    file       |        |        |       |           |                      |                       |                 bin to process(name as defined in the parameter file)
                                     |         |        |        |       |           |                      |                       |                       |     
                                     |         |        |        |       |           |                      |                       |                       |       maximum value for the y-axis
                                     |         |        |        |       |           |                      |                       |  input median PSD power file  |     
                                     |         |        |        |       |           |                      |                       |           |           |       |      | verbose mode on/off (0 or verbose)
   python ntk_plotPower.py param=plotPower net=NET sta=STA  loc=LOC chan=CHAN start=YYYY-MM-DDTHH:MI:SS end=YYYY-MM-DDTHH:MI:SS  win=12  file=fileName   bin=SM ymax=12 mode=0
  
h4. Input:
  
   The PSD median power file created by ntk_medianPower.py 
   
   The output windowed PDFs are stored under the 
   corresponding window directory as follows:
  
   Win(h)     Dir
     6    ->  6h
    12    -> 12h
    24    ->  1d
    96    ->  4d
   384    -> 16d
  
  
 period range index:
 Index    Period range
 1        1-5 local microseism
 2       5-10 secondary microseism 
 3      11-30 primary microseism
 4     50-200 Earth hum  

Notes:

The output file is save under both “PNG” and “EPS” formats.

Example:

python bin/ntk_plotPower.py param=plotPower net=IU sta=GUMO loc=00 chan=BHZ start=2014-10-01T00:00:00 end=2014-10-20T00:00:00 win=12 file=IU.GUMO.00.BHZ.2014-10-01T00:00:00.2014-10-20T00:00:00.12h.txt bin=SM mode=0 ymax=20

COPYRIGHT © 2015 Product Team, IRIS Data Management Center

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: http://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/.