Skip to content

Noise Toolkit Microseism Energy (ME) package V.2

Jump to bottom
Manoch Bahavar edited this page Nov 12, 2020 · 11 revisions

DESCRIPTION (V.2.0):

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

  • V.2.0.0 2016-11-16: Python 3 and adoption of PEP 8 style guide
  • V.0.6.0 2015-04-30: release with more uniform output file names
  • 2015-02-20: addressed the output file naming issue
  • V.0.5.0 2014-11-24: Beta release
  • 2014-11-24: release compatible with the PDF/PSD bundle format
  • 2014-03-07: Initial Alpha release
  • 2014-03-19: Added data file input option

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:

	ntk_plotPower.py to display the usage message (this message)
	  OR
	ntk_plotPower.py param=FileName net=network sta=station loc=location chandir=channel _irectory start=YYYY-MM-DDTHH:MM:SS end=YYYY-MM-DDTHH:MM:SS xtype=[period|frequency] verbose=[0|1] xtype=[period|frequency]

	to perform extraction where:
	  param		[default: plotPower] the configuration file name 
	  net		[required] network code
	  sta		[required] station code
	  loc		[required] location ID
	  chan		[required] channel ID
	  bin		[required] bin to process(name as defined in the parameter file)
	  ymax		maximum value for the y-axis
	  file		[required] the median PSD power file 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 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.

Examples:

* usage:
python bin/ntk_plotPower.py

* to plot power (note: the following example requires NM.SLM.--.BHZ.2009-03-01.2009-03-31.12h.txt as the input file. If this file does not exist):
# Generate PSDs:
python bin/ntk_computePSD.py param=computePSD net=NM sta=SLM loc=DASH chan=BHZ start=2009-03-01T00:00:00 end=2009-03-31T00:00:00 xtype=period plot=0 verbose=0
# Combine PSD files using the ntk_extractPsdHour.py script and note the output file name:
python bin/ntk_extractPsdHour.py net=NM sta=SLM loc=DASH chan=BHZ start=2009-03-01T00:00:00 end=2009-03-31T00:00:00 xtype=period verbose=0
# Compute power using the combined PSD file generated at step 2 above:
python bin/ntk_computePower.py net=NM sta=SLM loc=DASH chan=BHZ start=2009-03-01T00:00:00 end=2009-03-31T00:00:00 xtype=period file=NM.SLM.--.BHZ.2009-03-01.2009-03-31.period.txt verbose=0
# Compute 12-hour median power using the power file generated at step 3 above:
python bin/ntk_medianPower.py param=medianPower net=NM sta=SLM loc=DASH chan=BHZ start=2009-03-01T00:00:00 end=2009-03-31T00:00:00 xtype=period win=12 file=NM.SLM.--.BHZ.2009-03-01.2009-03-31.txt verbose=0

* Now, plot the Secondary Microseism, SM :
python bin/ntk_plotPower.py param=plotPower param=plotPower net=NM sta=SLM loc=DASH chan=BHZ start=2009-03-01T00:00:00 end=2009-03-31T00:00:00 win=12 bin=SM ymax=3 file=NM.SLM.--.BHZ.2009-03-01.2009-03-31.12h.txt ymax=0.06 bin=SM

COPYRIGHT © 2020 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/.

Noise Toolkit docs:

Previous release (V.1) docs:

Clone this wiki locally