paper.tex

国外免费地震资料处理软件包

  \hline 
  \noindent\texttt{scons view} or \texttt{scons $<$result$>$.view} \\ \ \\
  \indent Generate \texttt{Result} figures and display them on the screen. \\
  \hline 
  \noindent\texttt{scons print} or \texttt{scons $<$result$>$.print} \\ \ \\
  \indent Generate \texttt{Result} figures and print them. \\
  \hline 
  \noindent\texttt{scons lock} or \texttt{scons $<$result$>$.lock} \\ \ \\
  \indent Generate \texttt{Result} figures and install them in a separate location. \\
  \hline 
  \noindent\texttt{scons test} or \texttt{scons $<$result$>$.test} \\ \ \\
  \indent Generate \texttt{Result} figures and compare them with the corresponding ``locked'' figures stored in a separate location (regression testing). \\
  \hline 
  \noindent\texttt{scons $<$result$>$.flip} \\ \ \\
  \indent Generate the \texttt{$<$result$>$} figure and compare it with the corresponding ``locked'' figure stored in a separate location by flipping between the two figures on the screen. \\
  \\
  \hline 
  \noindent\texttt{scons TIMER=y ...} \\ \ \\
  \indent Time the execution of each step in the processing flow (using the Unix \texttt{time} utility.) \\
  \hline 
  \noindent\texttt{scons CHECKPAR=y ...} \\ \ \\
  \indent Check the names and values of all parameters supplied to Madagascar modules in the processing flows before executing anything (guards against incorrect input.) This option is new and experimental. \\
  \hline 
\end{tabular}
\end{center}}

\subsection{Example 2}
\inputdir{rsfpy}

The plan for this experiment is to add random noise to the test
``Lena'' image and then to attempt removing it by low-pass filtering
and by hard thresholding of coefficients in the Fourier domain. The
result images are shown in Figure~\ref{fig:panel1}
and~\ref{fig:panel2}.  

\plot{panel1}{height=0.5\textheight}{Top left: original image. Top  right: random noise added. Bottom left: original image spectrum in the Fourier ($F$-$X$) domain. Bottom right: noisy image spectrum in the Fourier ($F$-$X$) domain.}

\plot{panel2}{height=0.25\textheight}{Left: denoising by low-pass filtering.  Right: denoising by hard thresholding in the Fourier domain.}

Since the \texttt{SConstruct|} file is a Python script, we can also use all the
flexibility and power of the Python language in our Madagascar
reproducible scripts. A demo script is available in the
\texttt{rsf/scons/rsfpy} subdirectory of the Madagascar \texttt{book}
directory. Rather than commenting it line-by-line, we select some
parts of interest.

In the \texttt{SConstruct} script, we can declare
Python variables

\lstinputlisting[firstline=3,lastline=3,frame=single]{rsfpy/SConstruct}

\noindent and use them later, for example, to define our customized plot
command as a Python function

\lstinputlisting[firstline=5,lastline=10,frame=single]{rsfpy/SConstruct}

This Python function, named \texttt{grey()}, can then be called in Plot or Result
commands, e.g.

\lstinputlisting[firstline=48,lastline=48,frame=single]{rsfpy/SConstruct}

We can define a Python dictionary, e.g.

\lstinputlisting[firstline=34,lastline=35,frame=single]{rsfpy/SConstruct}

\noindent and loop over its entries, e.g.

\lstinputlisting[firstline=36,lastline=40,frame=single]{rsfpy/SConstruct}

\noindent Note that the title of the plots is obtained by concatenating Python
strings.

Python strings can also be used to define sequences of commands used
in several Flows, e.g.

\lstinputlisting[firstline=65,lastline=67,frame=single]{rsfpy/SConstruct}

Finally, in our Madagascar reproducible script, we may want the option
to pass command line arguments when running SCons or use default
values otherwise, e.g.

\lstinputlisting[firstline=69,lastline=71,frame=single]{rsfpy/SConstruct}

Running \texttt{scons} only, the default value set for fthr (i.e. 70)
is used whereas running \texttt{scons fthr=68} set fthr to a command
line specified value.

This is by no mean an exhaustive list of options but, hopefully, it
gives you a flavor of the powerful tool you have in hands. Enjoy!

\begin{comment}
\subsection{Useful SCons commands for reproducible scripts}

On top of SCons standard options (\texttt{scons --help} for more
details), Madagascar has its own SCons options. We already saw
\texttt{scons plot.view} that displays \texttt{plot.vpl} (in the
\texttt{Fig} folder) obtained in a Result command. \texttt{scons view}
displays the result plots one after the other.

It is also possible to check parameters for Madagascar programs in
SCons Flow commands using the CHECKPAR option (\texttt{scons
  CHECKPAR=y target}). Note that CHECKPAR is an experimental option
and will be enhanced in the future to include parameter ranges and
other safety checks.

To time the execution of processing flows in a SConstruct use the
TIMER option (\texttt{scons TIMER=y target}).

\texttt{scons lock} is used to secure result plots and copy them from
the \texttt{Fig} folder of your working directory to your
\texttt{\$RSFFIGS} folder where \texttt{RSFFIGS} is the environmental
variable to the directory where you want Madagascar to put your key
Madagascar result plots. Note that this is a necessary step before
creating a reproducible documentation. \texttt{scons plot.flip} runs
\texttt{xtpen Fig/plot.vpl /locked/figures/plot.vpl} to flip between
the new and locked figure. This is useful when detecting changes.
\end{comment}

\section{Creating reproducible documentation}
%
You are done with computational experiments and want to communicate
them in a paper. SCons helps us create high-quality papers, where
computational results (figures) are integrated with papers written in
\LaTeX\. 
The corresponding SCons extension is defined in  \texttt{\$RSFROOT/lib/rsftex.py} where
\texttt{RSFROOT} is the environmental variable to the Madagascar
installation directory. The source of this file is in
\href{http://svn.sourceforge.net/viewvc/rsf/trunk/python/rsftex.py?view=markup}{python/rsftex.py}.
We summarize the basic methods and commands in Tables~\ref{tbl:texcom} and~\ref{tbl:tex}.

\tabl{texcom}{Basic methods of an \texttt{rsftex} object.}{
\begin{center}
\begin{tabular}{|p{0.9\textwidth}|} \hline
  \noindent\texttt{Paper($<$paper\_name$>$,[,lclass][,use][,include][,options])}\\ \ \\
  \indent A rule to compile \texttt{$<$paper\_name$>$.tex} \LaTeX\
  document using the \LaTeX2e\ class specified in \texttt{lclass}
  (default is \texttt{geophysics.cls} from the
  \href{http://rsf.sourceforge.net/wiki/index.php/Segtex}{SEGTeX}
  package) with additional options specified in \texttt{options},  
  additional packages specified in \texttt{use},
  and additional preamble specified in \texttt{include} \\
  \hline
  \noindent\texttt{End()} \\ \ \\
  \indent A rule to collect default targets (referring to \texttt{paper.tex} document). \\
  \hline 
\end{tabular}
\end{center}}

\tabl{tex}{SCons commands defined in \texttt{rsftex}.}{
\begin{center}
\begin{tabular}{|p{0.9\textwidth}|}
  \hline 
  \noindent\texttt{scons}\\ \ \\
  \indent Generate the default target (usually the PDF file \texttt{paper.pdf} from the source \LaTeX\ file \texttt{paper.tex}.) \\
  \hline 
  \noindent\texttt{scons pdf} or \texttt{scons $<$paper\_name$>$.pdf} \\ \ \\
  \indent Generate PDF files from \LaTeX\ sources \texttt{paper.tex} or \texttt{$<$paper\_name$>$.tex}. \\
  \hline 
  \noindent\texttt{scons read} or \texttt{scons $<$paper\_name$>$.read} \\ \ \\
  \indent Generate PDF files from \LaTeX\ sources \texttt{paper.tex} or \texttt{$<$paper\_name$>$.tex} and display them on the screen. \\
  \hline 
  \noindent\texttt{scons print} or \texttt{scons $<$paper\_name$>$.print} \\ \ \\
  \indent Generate PDF files from \LaTeX\ sources \texttt{paper.tex} or \texttt{$<$paper\_name$>$.tex} and print them. \\
  \hline 
  \noindent\texttt{scons html} or \texttt{scons $<$paper\_name$>$.html} \\ \ \\
  \indent Generate HTML files from \LaTeX\ sources \texttt{paper.tex} or \texttt{$<$paper\_name$>$.tex} using \LaTeX{toHTML}. 
  The directory \texttt{$<$paper\_name$>$\_html} gets created. \\
  \hline 
  \noindent\texttt{scons install} or \texttt{scons $<$paper\_name$>$.install} \\ \ \\
  \indent Generate PDF and HTML files from \LaTeX\ sources \texttt{paper.tex} or \texttt{$<$paper\_name$>$.tex} and  
  install them in a separate location (used for publishing on a web site). \\
  \hline 
  \noindent\texttt{scons wiki} or \texttt{scons $<$paper\_name$>$.wiki} \\ \ \\
  \indent Convert \LaTeX\ sources \texttt{paper.tex} or \texttt{$<$paper\_name$>$.tex} to the \texttt{MediaWiki} format  
  (used for publishing on a Wiki web site). \\
  \hline 
\end{tabular}
\end{center}}

\begin{comment}
A Madagascar reproducible paper is a paper written in \LaTeX\ and
whose figures are either generated by Madagascar reproducible scripts
or available for download, e.g.  this paper!  (\texttt{paper.tex}
available in the \texttt{rsf/scons/} directory of Madagascar book
section).

The main SConstruct command set in our reproducible research
environment and related to documentation is

This command is defined in \texttt{\$RSFROOT/lib/rsftex.py}.
\end{comment}

\subsection{Example}

This paper by itself is an example of a reproducible document. It is
generated using the following \texttt{SConstruct} file which is place
in the directory above the projects directories.

\lstinputlisting[frame=single]{SConstruct}

This \texttt{SConstruct} generates this paper but it can also compile
\texttt{velan.tex} in the same directory. Note that there is no
\texttt{Paper} command for \texttt{paper.tex} since it is the default
documentation name. Optional \LaTeX\ packages and style used in
\texttt{paper.tex} are passed in the End command.

Let's now have a closer look at \texttt{paper.tex} to understand how
the figures of the documentation are linked to the reproducible
scripts that created them. First of all, note that \texttt{paper.tex}
is not a regular \LaTeX\ document but only its body (no
$\backslash$documentclass, $\backslash$usepackage, etc.). In our
paper, Fig.~\ref{fig:lena} was created in the project folder
\texttt{easystart} (sub-folder of our documentation folder) by the
result plot \texttt{lena.vpl}. In the \LaTeX\ source code, it
translates as\\

\lstset{language=[LaTeX]TeX,backgroundcolor=\color{frame},showstringspaces=false,numbers=left,numberstyle=\tiny}
\lstinputlisting[firstline=452,lastline=454,frame=single]{paper.tex}

The $\backslash$inputdir command points to the project directory and
the $\backslash$sideplot command calls \texttt{$<$result\_name$>$}. The
\LaTeX\ tag of the figure is \texttt{fig:$<$result\_name$>$}. The
first time the paper is compiled, the result file is automatically
converted to the PDF file format. 
% unless the VPL result file is updated and
%locked in which case, the PDF file is also automatically updated at
%the next paper compilation.

\begin{comment}
\subsection{Useful SCons commands for reproducible documentation}

To actually compile this paper you first need to run and lock the
\texttt{easystart} project. Go in the \texttt{easystart} folder and
run \texttt{scons lock}. Go back to the documentation folder and run
\texttt{scons pdf} (alternatively \texttt{scons
  $<$paper\_name$>$.pdf}). Use \texttt{scons read} (alternatively
\texttt{scons $<$paper\_name$>$.read}) or your favorite PDF reader to
read this paper reproduced by yourself...
\end{comment}

\bibliographystyle{seg}
\bibliography{SEG,SEP2,scons}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: