[cig-commits] r12033 - seismo/3D/automeasure/latex
alessia at geodynamics.org
alessia at geodynamics.org
Tue May 27 08:09:17 PDT 2008
Author: alessia
Date: 2008-05-27 08:09:17 -0700 (Tue, 27 May 2008)
New Revision: 12033
Modified:
seismo/3D/automeasure/latex/Makefile
seismo/3D/automeasure/latex/flexwin_manual.tex
seismo/3D/automeasure/latex/flexwin_paper.pdf
seismo/3D/automeasure/latex/manual_technical.tex
seismo/3D/automeasure/latex/manual_tuning.tex
Log:
Written skeleton manual
Modified: seismo/3D/automeasure/latex/Makefile
===================================================================
--- seismo/3D/automeasure/latex/Makefile 2008-05-27 12:05:43 UTC (rev 12032)
+++ seismo/3D/automeasure/latex/Makefile 2008-05-27 15:09:17 UTC (rev 12033)
@@ -15,6 +15,7 @@
introduction.tex \
manual_introduction.tex \
manual_method.tex \
+manual_tuning.tex \
manual_technical.tex \
method.tex \
results.tex
Modified: seismo/3D/automeasure/latex/flexwin_manual.tex
===================================================================
--- seismo/3D/automeasure/latex/flexwin_manual.tex 2008-05-27 12:05:43 UTC (rev 12032)
+++ seismo/3D/automeasure/latex/flexwin_manual.tex 2008-05-27 15:09:17 UTC (rev 12033)
@@ -22,9 +22,9 @@
\input{manual_introduction}
\input{manual_technical}
-\input{manual_method}
+%\input{manual_method}
\input{manual_tuning}
-\input{figures_manual}
+%\input{figures_manual}
\bibliographystyle{plainnat}
\bibliography{AM-allcitations}
Modified: seismo/3D/automeasure/latex/flexwin_paper.pdf
===================================================================
(Binary files differ)
Modified: seismo/3D/automeasure/latex/manual_technical.tex
===================================================================
--- seismo/3D/automeasure/latex/manual_technical.tex 2008-05-27 12:05:43 UTC (rev 12032)
+++ seismo/3D/automeasure/latex/manual_technical.tex 2008-05-27 15:09:17 UTC (rev 12033)
@@ -1,29 +1,29 @@
-\chapter{Obtaining and installing FLEXWIN\label{sec:install}}
-Here is where you find basic information for obtaining and installing the code.
-For details of the algorithm, see chapter~\ref{sec:algorithm}. For details of
-how to tune the algorithm to your system, see chapter~\ref{sec:tuning}.
+\chapter{Getting started\label{sec:install}}
+Here is where you find basic information for obtaining and installing the FLEXWIN package.
+For details of how to tune the algorithm to your system, see chapter~\ref{sec:tuning}.
+
\section{System requirements}
-In order to run, FLEXWIN requires:
+In order to install and run, FLEXWIN requires:
\begin{itemize}
\item UNIX operating system (Linux, Solaris, MacOS \ldots)
-\item [TODO] Memory requirements (measure what is needed!)
-\item [TODO] Other code (sac / saclib / etc?)
+\item Other code : SAC / SacLib / libtau )
\end{itemize}
-Note: The barebones of this code is not dependent on any input format for data. In order to use a different data format, just write your own i/o routines.
+SAC - more specifically the SAC library libsac.a - is required in order to for FLEXWIN to be able to read and write sac seismogram files. Note that the bare bones of the code is not dependent on any input or output format for the data. Should you prefer to use another seismogram format, you can write your own versions of {\tt read\_sac\_files(file\_s,file\_o)} in {\tt seismo\_subs.f90} and {\tt write\_lp\_sac(basename)} in {\tt io\_subs.f90}.
-Note: The filtering and enveloping functionality used in this code comes from
-SacLib - this should be distributed with the code or made available separately.
+The filtering and enveloping functionality used in this code comes from
+SacLib - {\bf should this be distributed with the code or made available separately?}
+Travel-time prediction using IASPEI91 (not an essential feature of the code, but it can be useful for setting time-dependence of user parameters) requires libtau - {\bf should this be distributed with the code or made available separately?}
+
\section{Obtaining the code}
[TODO] Write this better once structure of code (and packages that will be
delivered) is finalised.
-The code is available as a gzipped tarball on {\tt ftp:\\ftp-eost.u-strasbg.fr/pub/alessia/code/flexwin.tgz} [NOTE: change this to what everyone agrees with...]
-The tarball is unpacked using the follwing command
+The code is available as a gzipped tarball from CIG (Computational Infrastructure for Geodynamics, {\tt http://www.geodynamics.org}). The tarball is unpacked using the follwing command
\begin{verbatim}
tar xvzf flexwin.tgz
\end{verbatim}
@@ -51,21 +51,5 @@
[TODO]
-\section{Input / Output formats}
-\subsection{Input formats}
-Input formats for data. In standard version this is SAC evenly spaced files.
-Data and synthetics must be synchronized (i.e. have the same reference time)
-and co-sampled (there is a 1/1000 [CHECK VALUE] built in). If you wish to use a different input format, here is the list of subroutines you must rewrite/substitute:
-\begin{verbatim}
-[TODO] list of subroutines
-\end{verbatim}
-\subsection{Output formats}
-The code outputs a set of text files per pair of observed and synthetic
-seismograms analysed. All text files have a number of header lines, prefixed by {\tt \#} with a set of name-value pairs.
-
-[TODO] list files here - and their formats
-
-[TODO] output in sac format?
-
Modified: seismo/3D/automeasure/latex/manual_tuning.tex
===================================================================
--- seismo/3D/automeasure/latex/manual_tuning.tex 2008-05-27 12:05:43 UTC (rev 12032)
+++ seismo/3D/automeasure/latex/manual_tuning.tex 2008-05-27 15:09:17 UTC (rev 12033)
@@ -1 +1,181 @@
\chapter{Tuning FLEXWIN for your problem\label{sec:tuning}}
+
+FLEXWIN is adapted to your specific problem by modifying the values of the parameters in Table~\ref{tb:params}, and the functional form of those parameters that are time-dependent. The base values of the various parameters are set in the {\tt PAR\_FILE}, which is read at run time. The functional forms of the time dependent parameters may be adjusted by modifying {\tt user\_parameters.f90}, and re-compiling the code.
+
+\begin{table}
+\begin{tabular}{lp{0.8\linewidth}}
+\hline
+\multicolumn{2}{l}{Standard tuning parameters:} \\[5pt]
+$T_{0,1}$ & band-pass filter corner periods \\
+$r_{P,A}$ & signal to noise ratios for whole waveform \\
+$r_0(t)$ & signal to noise ratios single windows \\
+$w_E(t)$ & water level on short-term:long-term ratio \\
+$CC_0(t)$ & acceptance level for normalized cross-correlation\\
+$\Delta\tau_0(t)$ & acceptance level for time lag \\
+$\Delta\ln{A}_0(t)$ & acceptance level for amplitude ratio \\
+\hline
+\multicolumn{2}{l}{Fine tuning parameters:} \\ [5pt]
+$c_0$ & for rejection of internal minima \\
+$c_1$ & for rejection of short windows \\
+$c_2$ & for rejection of un-prominent windows \\
+$c_{3a,b}$ & for rejection of multiple distinct arrivals \\
+$c_{4a,b}$ & for curtailing of windows with emergent starts and/or codas \\
+$w_{CC}\quad w_{\rm len}\quad w_{\rm nwin}$ & for selection of best non-overlapping window combination \\
+\hline
+\end{tabular}
+\caption{\label{tb:params}
+Overview of standard tuning parameters, and of fine
+tuning parameters. Values are defined in a parameter file, and the
+time dependence of those that depend on time is described by user-defined functions.
+}
+\end{table}
+
+\section{User modifiable parameters}
+The main user-modifiable parameters in the {\tt PAR\_FILE} are:
+\begin{description}
+\item[{\tt WIN\_MIN\_PERIOD}]Corresponds to $T_0$ in Table~\ref{tb:params}, and is the short wavelength cut-off for the band-pass filter applied to the raw synthetic and observed seismograms.
+\item[{\tt WIN\_MAX\_PERIOD}]Corresponds to $T_1$ in Table~\ref{tb:params}, and is the long wavelength cut-off for the band-pass filter applied to the raw synthetic and observed seismograms.
+\item[{\tt SNR\_INTEGRATE\_BASE}]Corresponds to $r_P$ in Table~\ref{tb:params}, and is the minimum signal to noise ratio on the power of the observed seismogram for windowing to continue.
+\item[{\tt SNR\_MAX\_BASE}]Corresponds to $r_A$ in Table~\ref{tb:params}, and is the minimum signal to noise ratio on the modulus of the observed seismogram for windowing to continue.
+\item[{\tt WINDOW\_AMP\_BASE}]Corresponds to $r_0$ in Table~\ref{tb:params}, and is the minimum signal to noise ratio for a window on the observed seismogram to be acceptable.
+\item[{\tt STALTA\_BASE}]Corresponds to $w_E$ in Table~\ref{tb:params}, and is the water level to be applied to the synthetic short-term/long-term average waveform in order to generate candidate time windows. See Figure~\ref{fg:win_composite}a.
+\item[{\tt CC\_BASE}]Corresponds to $CC_0$ in Table~\ref{tb:params}, and is the minimum normalized cross-correlation value between synthetic and observed seismogram for a window to be acceptable.
+\item[{\tt TSHIFT\_BASE}]Corresponds to $\Delta\tau_0$ in Table~\ref{tb:params}, and is the maximum cross-correlation lag (in seconds) between synthetic and observed seismogram for a window to be acceptable.
+\item[{\tt DLNA\_BASE}]Corresponds to $\Delta\ln{A}_0$ in Table~\ref{tb:params}, and is the maximum amplitude ratio ($\Delta\ln{A}$ or $\Delta A/A$) between synthetic and observed seismogram for a window to be acceptable.
+\item[{\tt C\_0}]Corresponds to $C_0$ in Table~\ref{tb:params}, and is expressed as a multiple of $w_E$. No window may contain a local minimum in its STA:LTA waveform that falls below the local value of $C_0 w_E$. See Figure~\ref{fg:win_composite}b.
+\item[{\tt C\_1}]Corresponds to $C_1$ in Table~\ref{tb:params}, and is expressed as a multiple of $T_0$. No window may be shorter than $C_1 T_0$.
+\item[{\tt C\_2}]Corresponds to $C_2$ in Table~\ref{tb:params}, and is expressed as a multiple of $w_E$. A window whose seed maximum on the STA:LTA waveform rises less than $C_2 w_E$ above either of its adjacent minima is rejected. See Figure~\ref{fg:win_composite}c.
+\item[{\tt C\_{3a}}]Corresponds to $C_{3a}$ in Table~\ref{tb:params}, and is expressed as a fraction. It regulates the acceptable height ratio between local maxima in a given window on the STA:LTA waveform. See Figure~\ref{fg:separation}.
+\item[{\tt C\_{3b}}]Corresponds to $C_{3b}$ in Table~\ref{tb:params}, and is expressed as a multiple of $T_0$. It regulates the acceptable time separation between local maxima in a given window on the STA:LTA waveform. See Figure~\ref{fg:separation}.
+\item[{\tt C\_{4a}}]Corresponds to $C_{4a}$ in Table~\ref{tb:params}, and is expressed as a multiple of $T_0$. It limits the length of a window before its first local maximum in STA:LTA.
+\item[{\tt C\_{4b}}]Corresponds to $C_{4b}$ in Table~\ref{tb:params}, and is expressed as a multiple of $T_0$. It limits the length of a window beyond its last local maximum in STA:LTA. See Figure~\ref{fg:win_composite}d.
+\item[{\tt WEIGHT\_AVERAGE\_CC}]Corresponds to $w_{CC}$ in Table~\ref{tb:params}, and is the weight given to the average cross-correlation value in the process of resolving window overlaps. See Figure~\ref{fg:phaseD}.
+\item[{\tt WEIGHT\_SPACE\_COVERAGE}]Corresponds to $w_{\rm len}$ in Table~\ref{tb:params}, and is the weight given to the time span covered by windows in the process of resolving window overlaps.
+\item[{\tt WEIGHT\_N\_WINDOWS}]Corresponds to $w_{\rm nwin}$ in Table~\ref{tb:params}, and is the weight given to the total number of windows in the process of resolving window overlaps.
+\end{description}
+
+\begin{figure}
+\center \includegraphics[width=6in]{figures/fig/window_composite.pdf}
+\caption{\label{fg:win_composite}
+(a)~Window creation process. The thick black line represents the STA:LTA
+waveform $E(t)$, and the thick horizontal dashed line its water level $w_E(t)$.
+Local maxima are indicated by alternating red and blue dots, windows are
+indicated by two-headed horizontal arrows. The time of the local maximum used
+as the window seed $t_M$ is denoted by the position of the dot. Only windows for the fourth local maximum are shown. (b)~Rejection of candidate windows based on the amplitude of the local minima. The two deep
+local minima indicated by the grey arrows form virtual barriers. All candidate
+windows that cross these barriers are rejected.
+(c)~Rejection of candidate
+windows based on the prominence of the seed maximum. The local maxima
+indicated by the grey arrows are too low compared to the local minima
+adjacent to them. All windows that have these local maxima as their seed are
+rejected (black crosses over the window segments below the time series).
+(d)~Shortening of long coda windows. The grey bar indicates the maximum coda
+duration $c_{4b} T_0$. Note that after the rejection based on prominence represented in (c) and before shortening of long coda windows represented in (d), the algorithm rejects candidate windows based on the separation of distinct phases, a process that is illustrated in Figure~\ref{fg:separation}.
+}
+\end{figure}
+
+\begin{figure}
+\center \includegraphics[width=5in]{figures/fig/window_rejection_separation.pdf}
+\caption{\label{fg:separation}
+Rejection of candidate windows based on the separation of distinct phases.
+(a)~Heights of pairs of local maxima above their intervening minimum.
+(b)~The black line represents the limiting value of $h/h_M$. Vertical bars represent
+$h/h_M$ for each pair of maxima. Their position along the horizontal axis is
+given by the time separation $\Delta T$ between the maxima of each pair. The
+color of the bar is given by the color of the seed maximum corresponding to $h_M$. Bars whose height
+exceeds the line represent windows to be rejected.
+(c)~The windows that have been rejected by this criterion are indicated by black
+crosses.
+}
+\end{figure}
+
+\begin{figure}
+\center \includegraphics[width=5in]{figures/fig/window_overlap.pdf}
+\caption{\label{fg:phaseD}
+The selection of the best non-overlapping window
+combinations. Each grey box represents a distinct group of windows.
+Non-overlapping subsets of windows are shown on separate lines. Only one
+line from within each group will be chosen, the one corresponding to the
+highest weighted score. The resulting optimal set
+of data windows is shown by thick arrows.}
+\end{figure}
+
+\section{Time dependence of user parameters}
+A subset of the FLEXWIN parameters from Table~\ref{tb:params} are time-dependent (where time is measured along the seismogram). This feature enables the user to exercise fine control of the windowing algorithm. The user can modulate the time-dependence of these parameters by editing the {\tt set\_up\_criteria\_arrays} subroutine in the {\tt user\_functions.f90} file. This subroutine is called after the seismograms have been read in, and the following variables have been set:
+\begin{description}
+\item[{\tt npts, dt, b, npts}] Number of points, time step, time of first point with respect to the reference time of both seismograms. The observed and synthetic seismograms should have identical values of these three quantities.
+\item[{\tt evla, evlo, evdp, stla, stlo}] Event latitude, event longitude, event depth (km), station latitude, station longitude, read from the observed seismogram.
+\item[{\tt azimuth, backazimuth, dist\_deg, dist\_km}] Calculated from the event and station locations above.
+\item[{\tt kstnm, knetwk, kcmpnm}] Station name, network name, component name, read from the observed seismogram.
+\item[{\tt num\_phases, ph\_names, ph\_times}] Number, names and arrival times of standard seismic phases calculated through IASPEI91 using the event depth and epicentral distance.
+\end{description}
+
+The {\tt set\_up\_criteria\_arrays} subroutine first sets up non time-modulated versions of the time-dependent parameters using a simple loop over time:
+{\small
+\begin{verbatim}
+! -----------------------------------------------------------------
+! This is the basic version of the subroutine - no variation with time
+! -----------------------------------------------------------------
+ do i = 1, npts
+ time=b+(i-1)*dt
+ DLNA_LIMIT(i)=DLNA_BASE
+ CC_LIMIT(i)=CC_BASE
+ TSHIFT_LIMIT(i)=TSHIFT_BASE
+ STALTA_W_LEVEL(i)=STALTA_BASE
+ S2N_LIMIT(i)=WINDOW_AMP_BASE
+ enddo
+\end{verbatim}
+}
+It is then up to the user to modulate these values for the specific problem at hand. For example, should the user want to discourage the algorithm from picking windows beyond the end of the first surface wave-train $R1$, the following lines should be added to the {\tt user\_functions.f90} file to raise the water level on the STA:LTA waveform by a factor of ten:
+{\small
+\begin{verbatim}
+ ! --------------------------------
+ ! Set approximate end of rayleigh wave arrival
+ R_vel=3.2
+ R_time=dist_km/R_vel
+ ! --------------------------------
+ ! modulate criteria in time
+ do i = 1, npts
+ time=b+(i-1)*dt
+ if (time.gt.R_time) then
+ STALTA_W_LEVEL(i)=STALTA_BASE*10.0
+ endif
+ enddo
+\end{verbatim}
+}
+Should the user want the algorithm to be less stringent in its requirements for the cross-correlation fit for the surface wave portion of the seismograms, and allow a greater travel-time lag for deeper events, the required lines could be:
+{\small
+\begin{verbatim}
+ ! --------------------------------
+ ! Set approximate end of rayleigh wave arrival
+ R_vel=3.2
+ R_time=dist_km/R_vel
+ ! --------------------------------
+ ! Set approximate start of love wave arrival
+ Q_vel=4.2
+ Q_time=dist_km/Q_vel
+ ! --------------------------------
+ ! modulate criteria in time
+ do i = 1, npts
+ time=b+(i-1)*dt
+ ! if we are in the surface wave times, then make the cross-correlation
+ ! criterion less severe
+ if (time.gt.Q_time .and. time.lt.R_time) then
+ CC_LIMIT(i)=0.9*CC_LIMIT(i)
+ endif
+ ! --------------------------------
+ ! modulate criteria according to event depth
+ !
+ ! if an intermediate depth event
+ if (evdp.ge.70 .and. evdp.lt.300) then
+ TSHIFT_LIMIT(i)=TSHIFT_BASE*1.4
+ ! if a deep event
+ elseif (evdp.ge.300) then
+ TSHIFT_LIMIT(i)=TSHIFT_BASE*1.7
+ endif
+ enddo
+ \end{verbatim}
+}
+ The above examples illustrate the power of the {\tt user\_functions.f90} file. The user can choose to include/exclude any portion of the seismogram, and to make the rejection criteria for windows more or less stringent on any other portion of the seismogram. All the seismogram-dependent variables whose values are known when the {\tt set\_up\_criteria\_arrays} subroutine is executed may be used to inform these choices, leading to an infinite number of windowing possibilities. The careful user will use knowledge of the properties of the observed data set, the limitations of the synthetic waveforms, and the final use to which the selected windows will be put in order to tailor the subroutine to the needs of each study.
+
+ For a given set of data and synthetics, the {\tt PAR\_FILE} and {\tt user\_functions.f90} files uniquely determine the windowing results.
More information about the cig-commits
mailing list