Noise Toolkit Microseism Energy (ME) bundle V.1

DESCRIPTION (V.1.0):

This bundle 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 bundle’s INSTALL.txt file

• install Python on your computer
• additional required Python modules are:
  . matplotlib
  . numpy
  . scipy
• download the package under the installation directory.
• untar the bundle where you want to install (if you are also installing or have installed the PDF/PSD bundle of the Noise toolkit,
  it is recommended to install them both under the same directory.)
  WARNING: untaring this bundle over an existing installation will overwrite the files. Make sure to save any changes you have made to scripts or parameter files,
  including param/common.py used also by PDF/PSD bundle.

Note: if you are installing this bundle on a PC, edit the param/common.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 bundle includes an example script (run_Example.bat for the Windows users and run_Example.csh for others) under the top directory to get you started (requires the NTK PSD/PDF bundle). Script processes the BHZ channel of the CU.GTBY station with location code of 00 between 2012-10-24 00:00:00 UTC and 2012-10-27 00:00:00 UTC. This time window coincides with Hurricane Sandy . At each step pay attention to the COMMAND output line that tells you the command it is using for that step:

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 bundle) 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

• R 0.6.0 2015-04-30 Manoch: Beta release
• 2014-10-07 Manoch: 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 Manoch: revision for production test
• 2013-03-14 Manoch: created

USER"S GUIDE

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

Parameters

All parameters are under the param directory. The “common.py” parameter file contains basic parameters shared by all parameter files. Please review ALL parameter to TO familiarize yourself with the script capabilities. For more information about this bundle, 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:

                         configuration file name           net     sta      loc    chan     PSD file type  mode=0       run with minimum message output
                                         |                 |       |        |        |        |            | = verbose run in verbose mode
                                         |                 |       |        |        |        |            |
                                         |                 |       |        |        |        |            |          'combined' PSD file to read
                                         |                 |       |        |        |        |            |              |
 python bin/ntk_computePower.py   param=computePower   net=NM sta=SLM loc=DASH chan=BHZ  type=period mode=verbose  file=NM.SLM.--.BHZ.2009-01-01T00:00:00.2010-01-01T00:00:00_period.txt

For more information visit:

ds.iris.edu/ds/products/noise-toolkit-pdf-psd

notes:

• In all examples it is assumed that the command is issued under the IRIS_NTK/ 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 (mode=0):

Example:

• example below may turn the verbose mode one. Once you have configured the script, you can turn it off by setting mode=0

python bin/ntk_computePower.py param=computePower net=IU sta=GUMO loc=00 chan=BHZ type=period mode=verbose file=IU.GUMO.00.BHZ.2014-09-30T00:00:00.2014-10-21T00:00:00.period.txt

Script: ntk_medianPower.py

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

Usage:

                           parameter file         net    sta     loc      chan     start                      end             smoothing window
                                     |             |      |       |         |         |                        |                    (hours)   
                                     |             |      |       |         |         |                        |                       |      verbose mode (0 or verbose)
                                     |             |      |       |         |         |                        |                       |        |
                                     |             |      |       |         |         |                        |                       |        |            PSD power file name
                                     |             |      |       |         |         |                        |                       |        |            |
                                     |             |      |       |         |         |                        |                       |        |            |
 python ntk_medianPower.py param=medianPower  net=NM sta=SLM loc=DASH chan=BHZ start=2009-02-27T00:00:00 end=2009-04-02T00:00:00  win=12 mode=verbose file=NM.SLM.--.BHZ.2009-02-27T00:00:00.2009-04-02T00:00:00.txt

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

example:

python bin/ntk_medianPower.py param=medianPower net=IU sta=GUMO loc=00 chan=BHZ start=2014-10-01T00:00:00 end=2014-10-20T00:00:00 win=12 mode=0 file=IU.GUMO.00.BHZ.2014-10-01T00:00:00.2014-10-20T00:00:00.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/.