Recent changes to Tutorial

Tutorial modified by Nick Crabtree

Nick Crabtree — Thu, 18 May 2017 12:53:27 -0000

--- v4
+++ v5
@@ -56,4 +56,6 @@

 The analysis in the `cross_validation_stats` files are duplicated, once analysing the depth maps before the final stage of error-correction (uncorrected) and once after final error correction (corrected). The reason for this is that the final error correction stage can actually end up in making final depth maps which are less predictive than the uncorrected maps. The results are duplicated to allow you to figure out if this is the case with your dataset.

+The stats file reports the aggregate RMS for all runs, but only the best and next-best have the individual per-well residuals output. Search for the string `The Best` to find the best method after error correction (which is what most people want). Also, search for the string 'Max RMS' to find the chunks nearer the end of the stats file which show the aggregate statistics for the best 100 runs and so on.
+
 The montecarlo process will continue running indefinitely. In order to terminate it without corrupting the creation of the stats files, Xval will regularly check for the existence of a file named `finish_now` in the working directory, and will exit gracefully if this file exists. It is strongly recommended to terminate an Xval run by creating this file, for example using the unix command `touch finish_now`. Remember to delete the file before starting a new run!

Tutorial modified by Nick Crabtree

Nick Crabtree — Thu, 18 May 2017 12:48:14 -0000

--- v3
+++ v4
@@ -53,3 +53,7 @@
 Initially, all methods have the same weighting. As the cross-validation runs progress, they output their results into a file `cross_validation_report.txt`. This file can grow very large. If you are running multiple simultaneous cross-validation processes in the same directory (this is the recommended way to do things) then file locking is used to ensure that only one of the processes updates the file at any one time. The `cross_validation_report.txt` file contains a full description of the velocity model used, and the cross-validation error for one well, on each line. Due to the possibilty of multpile processes running in parallel, the errors for all wells for one particular method will not necessarily be next to each other in this file.

 Periodically, Xval pauses doing the cross-validation and analyses the `cross_validation_report.txt` file to get the cross-validation RMS for all the velocity models represented in the file. It outputs the results of the analysis into the file `cross_validation_stats.txt`. If there is an already-existing `cross_validation_stats.txt` file then it is copied to `cross_validation_stats.bak`. There is a good chance that at any given moment the `cross_validation_stats.txt` file is in the middle of being updated, so it is recommended that you only ever open up the `cross_validation_stats.bak` file to look at. This file is the only place where the cross validation statistics are reported, so you'll need to become somewhat familiar with this file. You will also need an editor which is capable of loading a very large text file and searching through it. If you are using Windows, then you are likely to be very frustrated; neither Notepad or Wordpad or Microsoft Word is really capable of handling files of the size which Xval produces after a long run. Notepad++ is a good choice. Textedit on Mac works well. On Linux (e.g. in the virtual machine) `nano` is a good console text editor for newcomers.
+
+The analysis in the `cross_validation_stats` files are duplicated, once analysing the depth maps before the final stage of error-correction (uncorrected) and once after final error correction (corrected). The reason for this is that the final error correction stage can actually end up in making final depth maps which are less predictive than the uncorrected maps. The results are duplicated to allow you to figure out if this is the case with your dataset.
+
+The montecarlo process will continue running indefinitely. In order to terminate it without corrupting the creation of the stats files, Xval will regularly check for the existence of a file named `finish_now` in the working directory, and will exit gracefully if this file exists. It is strongly recommended to terminate an Xval run by creating this file, for example using the unix command `touch finish_now`. Remember to delete the file before starting a new run!

Tutorial modified by Nick Crabtree

Nick Crabtree — Tue, 16 May 2017 07:26:52 -0000

--- v2
+++ v3
@@ -38,11 +38,18 @@
 #Running your first cross-validation#
 ##Building the list of velocity models to be cross-validated##
 When running a deterministic depth conversion, you have only one method for each layer, and only one way to go from top to bottom of your set of horizons. As soon as you move into the world of having more than one method, and more than one layering scheme, things get complicated very quickly.
+
 Xval keeps track of all the options in a series of multi-dimensional Perl arrays. So $method\[2]\[4]\[5] would contain the sixth depth conversion method to go from horizon two to horizon four in your list (skipping horizon 3). In this arry, the horizon index 0 (Perl array subscripts start at zero, like C) represents the free surface (usually mean sea level (MSL) for offshore projects; and the seismic reference datum (SRD) onshore. (As an aside, the SRD for a depth-conversion project should always be up in the air, above all the topography). The method index also starts at 0, which is why \[5] denotes the sixth method.
+
 It is suggested to start simple and add additional methods cautiously; with only a few different options the number of different ways they can be assembled into one multi-layer model very quickly gets very large.
 If the `sprint_layering()` entry point is called then Xval will systematically work through all the possible combinations of horizons and methods. On any non-trivial depth conversion proejct, it quickly becomes apparent that the computation time for running through all these models is of the order of hundreds of years if not millenia. 
 ##Monte-carlo or not-montecarlo?##
 The solution to the run-time problem is, rather than systematically running through all possible options, to randomly select from the available options to build the velocity models. Calling Xval with the `sprint_layering_montecarlo()` entry point achieves this. 
+
 However this is not the end of the story. Some of the individual components will turn out to always give a poor cross-validation result. Usually what we are looking for in a cross-validation run is a set of low cross-validation residual results which are nevertheless distinct from each other, in order to assess the uncertainty in depth-prediction away from the well data.
+
 Supplying the `--not-montecarlo` flag to Xval achieves this. This activates a weighting scheme which is applied to the random choice of the layering scheme and individual depth conversion methods. This weighting scheme is designed to filter out bad methods, and focus on the ones which perform well. Because it is only a weighting applied to a random selection, all possible models are still available for selection.
-Initially, all methods have the same weighting. As the cross-validation runs progress, they output their results into a file `cross_validation_report.txt`. This file can grow very large. If you are running multiple simultaneous cross-validation processes in the same directory (this is the recommended way to do things) then file locking is used to ensure that only one of the processes updates the file at any one time. The `cross_validation_report.txt` file contains a full description of the velocity model used, and the cross-validation error for one well, on each line. Due to the possibilty of multpile processes running in parallel, the errors for all wells for one particular method will not necessarily be next to each other in this file. Periodically, Xval pauses doing the cross-validation and analyses the `cross_validation_report.txt` file to get the cross-validation RMS for all the velocity models represented in the file. It outputs the results of the analysis into the file `cross_validation_stats.txt`. If there is an already-existing `cross_validation_stats.txt` file then it is copied to `cross_validation_stats.bak`. There is a good chance that at any given moment the `cross_validation_stats.txt` file is in the middle of being updated, so it is recommended that you only ever open up the `cross_validation_stats.bak` file to look at. This file is the only place where the cross validation statistics are reported, so you'll need to become somewhat familiar with this file. You will also need an editor which is capable of loading a very large text file and searching through it. If you are using Windows, then you are likely to be very frustrated; neither Notepad or Wordpad or Microsoft Word is really capable of handling files of the size which Xval produces after a long run. 
+
+Initially, all methods have the same weighting. As the cross-validation runs progress, they output their results into a file `cross_validation_report.txt`. This file can grow very large. If you are running multiple simultaneous cross-validation processes in the same directory (this is the recommended way to do things) then file locking is used to ensure that only one of the processes updates the file at any one time. The `cross_validation_report.txt` file contains a full description of the velocity model used, and the cross-validation error for one well, on each line. Due to the possibilty of multpile processes running in parallel, the errors for all wells for one particular method will not necessarily be next to each other in this file. 
+
+Periodically, Xval pauses doing the cross-validation and analyses the `cross_validation_report.txt` file to get the cross-validation RMS for all the velocity models represented in the file. It outputs the results of the analysis into the file `cross_validation_stats.txt`. If there is an already-existing `cross_validation_stats.txt` file then it is copied to `cross_validation_stats.bak`. There is a good chance that at any given moment the `cross_validation_stats.txt` file is in the middle of being updated, so it is recommended that you only ever open up the `cross_validation_stats.bak` file to look at. This file is the only place where the cross validation statistics are reported, so you'll need to become somewhat familiar with this file. You will also need an editor which is capable of loading a very large text file and searching through it. If you are using Windows, then you are likely to be very frustrated; neither Notepad or Wordpad or Microsoft Word is really capable of handling files of the size which Xval produces after a long run. Notepad++ is a good choice. Textedit on Mac works well. On Linux (e.g. in the virtual machine) `nano` is a good console text editor for newcomers.

Tutorial modified by Nick Crabtree

Nick Crabtree — Tue, 16 May 2017 07:22:25 -0000

--- v1
+++ v2
@@ -36,4 +36,13 @@
 There are a few options which don't have a command-line equivalent (due to programmer laziness) but which are important in controlling the program. Chief among these is the `$options->{cross_validate_all_horizons}` option.
 #Running your first depth conversion#
 #Running your first cross-validation#
+##Building the list of velocity models to be cross-validated##
+When running a deterministic depth conversion, you have only one method for each layer, and only one way to go from top to bottom of your set of horizons. As soon as you move into the world of having more than one method, and more than one layering scheme, things get complicated very quickly.
+Xval keeps track of all the options in a series of multi-dimensional Perl arrays. So $method\[2]\[4]\[5] would contain the sixth depth conversion method to go from horizon two to horizon four in your list (skipping horizon 3). In this arry, the horizon index 0 (Perl array subscripts start at zero, like C) represents the free surface (usually mean sea level (MSL) for offshore projects; and the seismic reference datum (SRD) onshore. (As an aside, the SRD for a depth-conversion project should always be up in the air, above all the topography). The method index also starts at 0, which is why \[5] denotes the sixth method.
+It is suggested to start simple and add additional methods cautiously; with only a few different options the number of different ways they can be assembled into one multi-layer model very quickly gets very large.
+If the `sprint_layering()` entry point is called then Xval will systematically work through all the possible combinations of horizons and methods. On any non-trivial depth conversion proejct, it quickly becomes apparent that the computation time for running through all these models is of the order of hundreds of years if not millenia. 
 ##Monte-carlo or not-montecarlo?##
+The solution to the run-time problem is, rather than systematically running through all possible options, to randomly select from the available options to build the velocity models. Calling Xval with the `sprint_layering_montecarlo()` entry point achieves this. 
+However this is not the end of the story. Some of the individual components will turn out to always give a poor cross-validation result. Usually what we are looking for in a cross-validation run is a set of low cross-validation residual results which are nevertheless distinct from each other, in order to assess the uncertainty in depth-prediction away from the well data.
+Supplying the `--not-montecarlo` flag to Xval achieves this. This activates a weighting scheme which is applied to the random choice of the layering scheme and individual depth conversion methods. This weighting scheme is designed to filter out bad methods, and focus on the ones which perform well. Because it is only a weighting applied to a random selection, all possible models are still available for selection.
+Initially, all methods have the same weighting. As the cross-validation runs progress, they output their results into a file `cross_validation_report.txt`. This file can grow very large. If you are running multiple simultaneous cross-validation processes in the same directory (this is the recommended way to do things) then file locking is used to ensure that only one of the processes updates the file at any one time. The `cross_validation_report.txt` file contains a full description of the velocity model used, and the cross-validation error for one well, on each line. Due to the possibilty of multpile processes running in parallel, the errors for all wells for one particular method will not necessarily be next to each other in this file. Periodically, Xval pauses doing the cross-validation and analyses the `cross_validation_report.txt` file to get the cross-validation RMS for all the velocity models represented in the file. It outputs the results of the analysis into the file `cross_validation_stats.txt`. If there is an already-existing `cross_validation_stats.txt` file then it is copied to `cross_validation_stats.bak`. There is a good chance that at any given moment the `cross_validation_stats.txt` file is in the middle of being updated, so it is recommended that you only ever open up the `cross_validation_stats.bak` file to look at. This file is the only place where the cross validation statistics are reported, so you'll need to become somewhat familiar with this file. You will also need an editor which is capable of loading a very large text file and searching through it. If you are using Windows, then you are likely to be very frustrated; neither Notepad or Wordpad or Microsoft Word is really capable of handling files of the size which Xval produces after a long run.

Tutorial modified by Nick Crabtree

Nick Crabtree — Mon, 15 May 2017 17:39:19 -0000

Xval Tutorial

Xval Tutorial
Introduction
Getting started
Running your first depth conversion
Running your first cross-validation
- Monte-carlo or not-montecarlo?

Introduction

Getting started

Getting started with the virtual machine

Getting started with a source code download

Basics of running an Xval job

Xval is (mainly) written in Perl. As it is a complex piece of software, it is split into several modules. These files have the suffix ".pm". The key modules are sprint.pm (which is the main engine for the software), grid.pm (which deals with all the interactions with grids / surfaces) and util.pm (which contains useful stuff not specifically depth-conversion-related).

To run Xval you need to write a small program, called a script, which tells Xval what you want to do. Typically this script contains the names and locations of the files containing your well data and gridded seismic interpretation, along with some instructions about layering and velocity models. The 'sample_sprint_scripts' folder within the software installation folder (look in 'xval' in your home directory if you don't know where this is) contains several examples to hopefully get you started.

Xval, like Unix command-line programs in general, is controllable by a series of options. Think of these like the various check boxes you might get in a 'Preferences' or 'Options' page in a mouse-driven program.

The options can be supplied in two ways. The first is to supply them on the command line, like this example, which increases the default verboseness level to 10, tells the program to run when my laptop is on battery power (which it won't do by default) and asks for a report on the 10th iteration of the script:

perl xval_driver_script.pl --verbose=10 --run-on-battery --report=10

There is a full list of options which can be supplied on the command-line like this here

There is a second method of supplying options, and this is typically used for things you want to set and forget, such as whether you want all the time grids to be trimmed to remove negative thicknesses (usually desirable) and the cross-validation exclusion radius:

#!/usr/bin/perl -w

use FindBin;
use lib "$FindBin::Bin";
use lib "$ENV{HOME}/xval";
use sprint 3.7;

$options->{make_conformal} = 1;
$options->{validation_radius} = 1000;

There are a few options which don't have a command-line equivalent (due to programmer laziness) but which are important in controlling the program. Chief among these is the $options->{cross_validate_all_horizons} option.

Running your first depth conversion

Running your first cross-validation