Differences

This shows you the differences between two versions of the page.

--- wphase:documentation [2014/03/19 01:00]
wphase
+++ wphase:documentation [2022/01/10 07:39] (current)
wphase [Extracting data from a gzipped tar archive]
@@ Line 1: / Line 1: @@
-===== W-phase documentation =====
+====== W-phase documentation ======
-==== Installation ====
+In addition to this page, you should probably have a look to [[wphase:tutorial|this tutorial page]].
+===== Installation =====
+==== Getting the code ====
+Currently, the W-phase package is hosted as a github repository. To check out the W-phase repository:
+<code>
+git clone https://github.com/eost/wphase.git wphase_package
+</code>
+To update your W-phase repository (pull changes)
+<code>
+cd /to/the/wphase/directory/
+git pull origin master
+</code>
+For more details on using git for W-phase, [[wphase:repository|you can read this page.]]
+==== Dependencies ====
+The w-phase package have only been tested on Unix and Linux computers. You will need the following:
+  - csh shell
+  - gcc and gfortran
+  - python2.7 (or later)
+  - You have to install numpy, matplotlib, cartopy and netCDF4 to run some python scripts which make figures.
+  - rdseed
+To install these dependencies on MacOs, [[wphase:macos|you can refer to this page]].
+==== Building the code ====
 To install the code, we must first setup a few environment variables. If you use csh or tcsh:
 <code>
-setenv GMT_BIN      /path/to/gmt/bin
 setenv RDSEED       /path/to/rdseed/executable
 setenv GF_PATH      /path/to/greens/functions/database
-setenv WPHASE_HOME  /path/to/wphase/package
+setenv WPHASE_HOME  /path/to/wphase
 </code>
 If you use bash:
 <code>
-export GMT_BIN=/path/to/gmt/bin
 export RDSEED=/path/to/rdseed/executable
 export GF_PATH=/path/to/greens/functions/database
@@ Line 37: / Line 64: @@
 -----
+===== How to run W-phase  =====
+You should also have a look to [[wphase:tutorial|the W-phase tutorial page]].
 ==== Preparing directories, i_master and CMTSOLUTION ====
@@ Line 43: / Line 74: @@
   * i_master: a file containing other parameters such as the band-pass filter parameters,  minimum and maximum distances, etc.
-The format of these files are described in [[wphase#Notes on file formats|notes on file formats]].
+The format of these files are described in [[wphase:documentation#Data formats|the file formats section]].
 Path to SEED file(s) must be correctly specified after the keyword 'SEED:' in the i_master file. If multiple SEED files are used for the same inversion, each of them must be referenced properly in i_master using one 'SEED:' line per file.
@@ Line 49: / Line 80: @@
 -----
-==== Extracting data from (mini)SEED file(s) ====
+==== Extracting data from SEED ====
 Once the i_master and CMTSOLUTION files are created, we can extract waveforms and instrument response parameters and perform a rough screening by epicentral distance. This can be done using:
 <code>${WPHASE_HOME}/bin/extract.csh</code>
@@ Line 57: / Line 88: @@
 -----
+==== Extracting data from a gzipped tar archive ====
+As SEED volumes are no longer supported, waveforms and instrument response can also be extracted from a gzipped tar archive (hereafter referred to as "tgz") including both SAC and SAC_PZ (poles and zeros) files.
+Instead of using the "extract.csh" script to extract data from SEED, we can then extract data from a tgz archive using:
+<code>${WPHASE_HOME}/bin/tgz2DATA_org.py path_to_tgz_archive.tgz</code>
+where "path_to_tgz_archive.tgz" is the path to the tgz archive including SAC and SAC_PZ files. This script will extract SAC and SAC_PZ files a the directory named "DATA_org".
+Two tgz archive formats are supported: WILBER (default) and NIED.
+Using the WILBER format, the tgz archive should include SAC files named with a ".SAC" or ".sac" extension and SAC_PZ file names starting with "SAC_PZ". If data is ordered using the [[https://ds.iris.edu/wilber3|IRIS Wilber 3 system]], this format can be obtained directly by selecting "Output format: SAC binary" (little or big-endian)  and "Bundle As: gzipped tar archive" in the final Request Data page (see below).
+{{:wilber3_screenshot.png?300|{{:wphase:wilber3_screenshot.png?300|}}
+Once the tgz archive is prepared, extraction from a WILBER formatted archive is done by running:
+<code>${WPHASE_HOME}/bin/tgz2DATA_org.py path_to_tgz_archive.tgz wilber</code>
+As this is the default format, the "wilber" option can be removed from the command line.
+Using the NIED tgz archive format, SAC_PZ files should end with ".zp" and SAC file names can have any format (but should not end with ".zp"). Extraction from a NIED archive can be done using
+<code>${WPHASE_HOME}/bin/tgz2DATA_org.py path_to_tgz_archive.tgz nied</code>
+---
 ==== Calculating Synthetics, deconvolution and filtering ====
@@ Line 92: / Line 144: @@
 $WPHASE_HOME/bin/wpinversion -ifil o_wpinv.th1.3 -ofil o_wpinv.th0.9 -th 0.9
 </code>
-  - Finally, it is possible to remove the channels showing a large rms ratios (observed/predicted and predicted/observed) using the option –nr (e.g. –nr 2.0): <code>
+  - Finally, it is possible to remove the channels showing a large rms amplitude ratios (observed/predicted and predicted/observed) using the option –nr (e.g. –nr 2.0): <code>
 $WPHASE_HOME/bin/wpinversion -ifil o_wpinv.th0.9 -ofil o_wpinv.th1.3 -nr 2.0
 </code>
@@ Line 104: / Line 156: @@
 -----
 ==== RUNA scripts ====
-Data extraction, screening and inversion described above can be performed by running one of the RUNA3*csh scripts (usually in bin). These scripts perform data extraction/screening and calculate a moment tensor solution after median data screening and after rejecting  traces associated with large misfit using the threshold 5.0 3.0 0.9 (i.e. -th, see 2. in section 4):
+Data screening and inversion can all be done at once using the RUNA3_lite.csh script:
+<code>
+${WPHASE_HOME}/bin/RUNA3_lite.csh
+</code>
+This script can be used after data extraction in "DATA_org" using either "tgz2DATA_org.py" or "extract.csh" to extract data from a tgz archive or a SEED volume, respectively (see above). Once the "DATA_org" directory is populated, the "RUNA3_lite.csh" script will perform data screening and calculate a moment tensor solution after median data screening and after rejecting  traces associated with large misfit using the threshold 5.0 3.0 0.9 (i.e. -th, see 2. in the "Inversion" section above).
+If data is extracted directly from SEED volume(s), data extraction/screening and inversion can be done directly by running:
 <code>
 ${WPHASE_HOME}/bin/RUNA3.csh
 </code>
-will perform median and rms misfit screening for Z, N, E, 1 and 2  channels,
+To do the inversion on "Z" components only (i.e., not using the horizontals), use:
 <code>
 ${WPHASE_HOME}/bin/RUNA3_only_Z.csh
 </code>
-will perform median and rms misfit screening for Z channels only.
-These two scripts don’t perform the “ratio screening” (i.e. 3. above). To run the same routines with an additional screening based on the ratio (observed/predicted and predicted/observed), the following scripts can be used:
+These two scripts don’t perform the “ratio screening” (i.e. 3. in the "Inversion" section above). To run the same routines with an additional screening based on the rms amplitude ratio (observed/predicted and predicted/observed), the following script can be used:
 <code>
 ${WPHASE_HOME}/bin/RUNA3r.csh
 </code>
 will perform median, rms misfit and rms ratio for channels Z, N, E, 1, 2 channels,
+Warning: RUNAr.csh is not yet fully tested.
-Remark: RUNAr.csh is not yet fully tested.
-Several optional parameters can be used when running RUNA3*csh scripts. These parameters will apply to the wpinversion program. They are described when running wpinversion -h.
-e.g.:  RUNA3.csh -wz 1.0 -wn 0.3 -we 0.5  will give a weights of 1.0, 0.3 and 0.5 for Z, N, E components respectively.
-To perform data screening and inversion only, using previously extracted SAC data, it is possible to use:
-<code>
-${WPHASE_HOME}/bin/RUNA3_lite.csh
-</code>
-that is designed for Z, N ,Z ,1, 2 channels
 -----
@@ Line 146: / Line 193: @@
 ==== Plot routines ====
-All the plotting scripts are coded using python and the module pylab which have to be installed before using them. The module basemap is also needed for plotting maps but it is optional (even if we recommend to install it).
+All the plotting scripts are coded using python and the module pylab which have to be installed before using them. The module cartopy is also needed for plotting maps but it is optional (even if we recommend to install it).
 There are 3 script which can be used to plot the W phase inversion results:
    * The first script is <code>${WPHASE_HOME}/bin/make_grids.py</code> which be used to display grid-searches results. Use <code>${WPHASE_HOME}/bin/make_grids.py -h</code> to have more details on available options and arguments. The 2 other scripts plot observed and synthetic seismograms after W phase inversion.
-   * In order to plot complete seismograms individually and place station on a map: <code>${WPHASE_HOME}/bin/traces_global.py</code> which draw complete seismograms and show station location on a map (if basemap is available). Please use <code>${WPHASE_HOME}/bin/traces_global.py -h</code> for more details on available options.
+   * In order to plot complete seismograms individually and place station on a map: <code>${WPHASE_HOME}/bin/traces.py</code> which draw complete seismograms and show station location on a map (if cartopy is available). Please use <code>${WPHASE_HOME}/bin/traces.py -h</code> for more details on available options.
    * To plot concatenated waveforms:<code>${WPHASE_HOME}/bin/make_cwp.py</code> For more details on available options and arguments see <code>${WPHASE_HOME}/bin/make_cwp.py -h</code> to see the options.
 -------
+===== Using ETOPO01 Global Relief Model =====
+ETOPO01 is a 1 arc-minute global relief model of the Earth's surface
+provided by Amante et al. (2009):
+<http://www.ngdc.noaa.gov/mgg/global/global.html>
+If Cartopy is installed, you can optionally draw ETOPO01 topography and
+bathymetry. To do so, the path to the ETOPO01 netCDF file must be
+assigned to the environment variable $ETOPOFILE which can be
+done in your .tcshrc fil (or .bachrc, .cshrc, etc.). The make_grids.py
+script have been tested only for grid-registered netCDF file of the
+ETOPO1 bedrock file available at:
+<http://www.ngdc.noaa.gov/mgg/global/relief/ETOPO1/data/bedrock/grid_registered/netcdf/ETOPO1_Bed_g_gmt4.grd.gz>
+-------
+===== Data formats =====
+You can also have a look to [[wphase:tutorial|the W-phase tutorial page]].
+=== CMTSOLUTION FILE ===
+example:
+<code>
+ PDE 2003  9 25 19 50  6.40  41.8100  143.9100  27.0 6.9 8.1 HOKKAIDO, JP
+event name:     092503C
+time shift:     19.8100
+half duration:  33.5000
+latitude:       42.2100
+longitude:     143.8400
+depth:          28.2400
+Mrr:       7.770000e+27
+Mtt:      -4.110000e+27
+Mpp:      -3.660000e+27
+Mrt:       1.320000e+28
+Mrp:       2.590000e+28
+Mtp:      -6.620000e+27
+</code>
+The first line of this file is the PDE.
+  * The first 4 characters of this line (including the first white space in the example above) generaly indicates the agency which provide the origin time, the hypocenter location and preliminary magnitude estimates.
+  * Characters from 6 to 27 correspond to the PDE origin time
+  * Characters from 29 to 52 are the PDE latitude, longitude and depth. This hypocenter location will be used to define the time window in order to select the part of the waveform which will be inverted
+  * Characters from 54 to 60 are PDE magnitude estimates The rest of the line provides some details on epicenter location (region, country, ...)
+The second line, 'event name' correspond to the event id
+Lines 3 and 4 are the parameters of the STF.
+Lines 5, 6 and 7 are the 'latitude', 'longitude' and 'depth' of the centroïd wich will be used for the rotation of horizontal components and for the computation of synthetic kernel functions.
+The last 6 lines are optional, they correspond to a moment tensor solution (e.g. a reference GCMT for comparision with the W phase inversion).
+=== i_master file ===
+This file is composed of several fields (some of them are optional):
+   * EVNAME: Arbitrary event name
+   * SEED:  path to SEED file. This field must be used several times if there are multiple SEED files.
+   * DMAX:  Maximum distance to be used.
+   * DMIN:  Minimum distance to be used (optional).  If omitted, it is defaulted to 0.
+   * CMTFILE: Path to the CMTSOLUTION file
+   * filt_order: order of the butterworth filter.
+   * filt_cf1:  low-frequency cut –off.
+   * filt_cf2:  high-frequency cut –off.
+   * filt_pass: unused parameter (let it to 1).
+   * IDEC_2: the second number is the number of seconds just before P wave over which the baseline is defined (let the other parameters to 2 and 0.1) .
+   * IDEC_3: Instrument response fit parameters for the deconvolution. The two first parameters define the frequency band in which the fit is measured. The third parameter is the number of samples used in this frequency range and the last parameter is a maximum misfit above which the channel is rejected.
+   * WP_WIN: time window definition.
+     * If one value $B$ (eg. WP_WIN: 15) is used, then the window is defined by $[P_{tt},P_{tt}+B\times\Delta]$ where $P_{tt}$ is the P-wave travel-time.
+     * If two values $A$ $B$ are specified (e.g., WP_WIN: 0. 15.), then the window is $[P_{tt}+A\times\Delta,P_{tt}+B\times\Delta]$.
+     * If three values $A$, $B$ and $C$ are used (e.g., WP_WIN: 0. 15. 12.) the time window is defined as:
+        * $[P_{tt}+A\times\Delta,P_{tt}+B\times\Delta]$ if $\Delta>C$
+        * $[P_{tt}+A\times C,P_{tt}+B\times C]$ if $\Delta<C$
+     * If Four values, $A$, $B$, $C$ and $D$ are given (e.g., WP_WIN: 0. 15. 12. 50.) then the window is:
+        * $[P_{tt}+A\times \Delta,P_{tt}+B\times\Delta]$ if $C<\Delta<D$
+        * $[P_{tt}+A\times C,P_{tt}+B\times C]$ if $\Delta<C$
+        * $[P_{tt}+A\times D,P_{tt}+B\times D]$ if $\Delta>D$
+   * GFDIR: Name of the Green's function directory (optional)
+example:
+<code>
+EVNAME:   Tokachi-Oki_2003
+SEED:    ../../WP6/SEEDS/2003_tokachi_oki_LH.SEED
+DMAX:    90.
+DMIN:    0.
+CMTFILE: CMTSOLUTION
+# data deconvolution
+filt_order: 4
+filt_cf1  : 0.001
+filt_cf2  : 0.005
+filt_pass : 1
+IDEC_2:  2  280   0.1
+IDEC_3:  0.001   0.1  100  0.03
+#inversion
+WP_WIN: 15.
+GFDIR: ./GF
+</code>
+=== Grid-search output files: grid_search_ts_out and grid_search_xy_out ===
+grid_search_ts_out corresponds to the time-shift grid-search.
+Example:
+<code>
+.0000   0.20140377
+.7621   0.32070120
+000     1.0000    81.7621   -35.8500   -72.7100    44.8000   0.60186830   1.83279165
+000     5.0000    81.7621   -35.8500   -72.7100    44.8000   0.58186860   1.60449952
+000     9.0000    81.7621   -35.8500   -72.7100    44.8000   0.55865993   1.40553383
+000    13.0000    81.7621   -35.8500   -72.7100    44.8000   0.53241366   1.23245105
+000    17.0000    81.7621   -35.8500   -72.7100    44.8000   0.50339138   1.08142045
+(…)
+000    57.0000    81.7621   -35.8500   -72.7100    44.8000   0.20380139   0.31131967
+000    61.0000    81.7621   -35.8500   -72.7100    44.8000   0.20198340   0.30827735
+000    65.0000    81.7621   -35.8500   -72.7100    44.8000   0.21088280   0.32324637
+000    69.0000    81.7621   -35.8500   -72.7100    44.8000   0.22888998   0.35415847
+000    73.0000    81.7621   -35.8500   -72.7100    44.8000   0.25358477   0.39808714
+(…)
+000   157.0000    81.7621   -35.8500   -72.7100    44.8000   0.65903444   3.48513694
+000   161.0000    81.7621   -35.8500   -72.7100    44.8000   0.65708573   3.35654281
+000   165.0000    81.7621   -35.8500   -72.7100    44.8000   0.65410621   3.18301823
+001    59.0000    81.7621   -35.8500   -72.7100    44.8000   0.20151331   0.30749196
+001    63.0000    81.7621   -35.8500   -72.7100    44.8000   0.20516181   0.31360143
+001    67.0000    81.7621   -35.8500   -72.7100    44.8000   0.21889318   0.33689015
+002    58.0000    81.7621   -35.8500   -72.7100    44.8000   0.20231439   0.30883067
+002    60.0000    81.7621   -35.8500   -72.7100    44.8000   0.20140377   0.30730901
+002    62.0000    81.7621   -35.8500   -72.7100    44.8000   0.20324196   0.31038266
+002    64.0000    81.7621   -35.8500   -72.7100    44.8000   0.20771868   0.31790207
+</code>
+The two first lines correspond respectively to the optimum and to the initial centroid time-shifts, the first column being the time-shift itself and the second column being the associated rms misfit.
+The following lines provide some details on the grid-search :
+st col. : index for this time-shift value,
+nd col. : iteration number,
+rd col. : time-shift
+rd col. : centroid latitude
+th col. : centroid longitude
+th col. : centroid depth
+th col. : rms
+th col. : normalized rms
+In the example above you can see that a global grid-search is performed from 1 to 165 sec (until computation 41) at the 0th iteration with a time step of 4sec. The 1st iteration corresponds to computations 42-44 which extend the grid-search to unexplored time-shift between 57sec and 69sec with a sampling interval of 2sec. The 2nd iteration perform an even finer sampling to guarantee a 1sec grid-search between 57sec and 65sec. Once this file is available to us (after running the time-shift grid-search), we can run
+<code>
+${WPHASE_HOME}/bin/make_grids.py –t
+</code>
+to create the file grid_search_ts.pdf containing Fig. 1 which corresponds to the above example.
+The output centroid position grid-search file grid_search_xy_out as a quite similar same structure replacing the time-shit in the 2 first lines by optimum and initial latitudes, longitudes and depth.
+<code>
+  -35.4500   -72.8325    25.5000   0.19118874
+  -35.2500   -72.7100    25.5000   0.19314386
+000    60.0000    60.0000   -36.4500   -74.1794    25.5000   0.24214954   0.37750789
+000    60.0000    60.0000   -36.4500   -73.6896    25.5000   0.22150727   0.34137918
+000    60.0000    60.0000   -36.4500   -73.1998    25.5000   0.20980594   0.32142471
+000    60.0000    60.0000   -36.4500   -72.7100    25.5000   0.20938393   0.32071163
+(…)
+001    60.0000    60.0000   -35.6500   -72.4651    25.5000   0.19798867   0.30161961
+001    60.0000    60.0000   -35.8500   -72.4651    25.5000   0.19830051   0.30213800
+001    60.0000    60.0000   -35.8500   -72.7100    25.5000   0.19640545   0.29899114
+001    60.0000    60.0000   -34.6500   -72.9549    25.5000   0.19787217   0.30142600
+(…)
+002    60.0000    60.0000   -35.3500   -72.5875    25.5000   0.19326491   0.29379393
+002    60.0000    60.0000   -35.3500   -72.7100    25.5000   0.19296721   0.29330241
+002    60.0000    60.0000   -35.5500   -72.7100    25.5000   0.19360157   0.29435001
+</code>
+The first line corresponds to the optimum centroid location and the second line indicates the a priori location specified in the CMTSOLUTION file. In these two lines, the 1st, 2nd and 3rd column correspond respectively to the centroid latitute, longitude and depth. The 4th column presents the associated rms misfits.
+The following lines provide some details on the grid-search :
+st col. : index of the explorated centroid position,
+nd col. : iteration number,
+rd col. : time-shift
+th col. : half duration
+th col. : centroid latitude
+th col. : centroid longitude
+th col. : centroid depth
+th col. : rms
+th col. : normalized rms
+Once the grid-search is performed, the grid_search_xy_out is available to us (after running the time-shift grid-search), we can run
+<code>
+${WPHASE_HOME}/bin/make_grids.py –p -b
+</code>
+to create the file grid_search_xy.pdf containing Fig. 1 which corresponds to the above example. The option –b is optional: it allows to use the cartopy module in order to plot coastlines and topography.

Seismo Wiki

User Tools

Site Tools

Differences

Page Tools