This page shows users how to run the Particle-Size Toolbox using the script runpst

runpst provides a graphical user interface for accessing all the different functions in the Particle-Size Toolbox.

Once a PST project has been created (do this here) there are a variety of options to choose from.

To show these options enter runpst into the Matlab command window.

          1. LOAD PARTICLE-SIZE DATA
          2. INTEGRATE PARTICLE-SIZE DATA
          3. DESCRIPTIVE STATISTICS
          4. PLOTTING TOOLS
          5. LOAD GEOLOGICAL MODEL
          6. REGULARIZE BOREHOLE DATA
          7. GRID TRANSFORMATION
          8. ALLOCATE FACIES TO DATA
          9. OPTIMISE PARTICLE-SIZE DATA
          10. INTERPOLATION OPTIONS
          11. GLOBAL TREND MODELLING
          12. GAUSSIAN TRANSFORMATION
          13. SEMI-VARIOGRAM ANALYSIS
          14. VARIOGRAM MODELLING
          15. CROSS VALIDATION
          16. INTERPOLATION
          17. DATA TRANSFORMATIONS
          18. ISATIS INTERFACE


Choose from one of these options and then click 'OK' to continue. For an explanation of how to use each of these options click on the links above.



1. LOAD PARTICLE-SIZE DATA


Load a data file into the toolbox. This step must be performed before you can do anything else.

  • Data can be loaded from txt or csv files formatted in one of the four pre-defined templates.


  • When a file has been selected choose from one of the pre-defined file formats.
dbaload1.png
    • Explanations of the different formats can be found in File Formats.
    • Template of each data format can be downloaded as an Excel spreadsheet
    • TNO users should use DINO, DINO_qwa or TOP_INTEGRAAL formats.


  • DEFAULT format data files can also be created automatically by entering Create_example_data in the Matlab command window

back to top

2. INTEGRATE PARTICLE-SIZE DATA


Integrate loaded data files into a uniform format: a set of particle-size categories. These are used for all further data analysis.

  • Enter a set of particle-size categories into the dialog box:

getpsdcats1.PNG


    • and define the particle-size units:
getpsdcats3.PNG

  • You have the option to calibrate the different data types using a set of duplicate measurements in training files:
dataCalib1.PNG
    • Particle-size distributions measured by different analytical techniques, e.g. sieve, pipette or laser analysis, use different definitions of 'particle-size'. These data must be adjusted or 'calibrated' if they are to be compatible.

  • Select 'Yes' to perform data calibration and follow the steps outlined in technique calibration. Select 'No' to continue the integration process without calibration.

  • If any files containing descriptions of sediment texture are loaded (DINO type files), the descriptions will be used to simulate complete particle-size distributions. Go to simulating particle-size distributions to find out how this process works.
intDINO1.png


Why integrate?
  • Particle-size distributions can be measured by different analytical techniques, e.g. sieve, pipette or laser analysis. These use different definitions of 'particle-size' that must be adjusted for if data are to be compatible.
  • Particle-size categories may not be the same in different files.
  • Sediment texture may be described by the proportions of gravel, sand, silt and clay.
  • Sediment texture may be described by classification codes.


Back to top

3. DESCRIPTIVE STATISTICS


Calculate descriptive statistics for numeric variables.

dstats1.PNG



  • Select a variable for calculating descriptive statistics. PSD are the particle-size distributions

dstats2.PNG


  • If you select PSD you must also select the variable containing the particle-size categories: usually PSD_CAT

dstats3.PNG


  • Select the descriptive statistics to be calculated
dstats4.PNG

  • Choose the particle-size units for data output
dstats5.PNG


back to top

4. PLOTTING TOOLS


The Particle-Size Toolbox provides a range of options for creating figures of particle-size distributions and 3D data.

dstats1.PNG




    • Click on the links above or scroll down to see examples of each of these plots and discover how they can be customized


Every time a figure is created it is saved to your PST project in the Figures folder as an EPS file.

back to top

1. 2D scatterplot

2Dscatter.PNG
The location of boreholes colored by average particle-size. The marker sizes are scaled the depth co-ordinate Z


back to plotting tools


3. 3D scatterplot
3Dscatter.PNG
Sample locations in 3D colored by average particle-size. Markers are scaled by analytical technique TECH_CD.


back to plotting tools


4. Ternary diagram or triangular plot

  • A traditional way of showing the distribution of particle-size data by major size fractions.
  • You can manually specify which size fractions to plot.
ternplot2.PNG
The relative proportions of sand, silt and clay.


back to plotting tools



5. Particle-size frequency plot


    • This graph type has a number of different options:
psdbiplots1.PNG

      • You can choose between frequency and cumulative frequency plotspsdbiplots3.PNG


      • Smoothing the distributions is also an option
psdbiplots6.PNG



    • All samples - smoothed percentage frequency distributions
pstbiplot1.png
Particle-size frequency distributions for all samples in a single graph.

    • All samples - smoothed cumulative frequency distributions
psdbiplot2.PNG
Particle-size cumulative frequency distributions for all samples in a single graph.

    • Selection of samples - smoothed frequency distributions

psdbiplots7.PNG
Particle-size frequency distributions for a selection of samples in individual graphs.




    • Mean of all samples - smoothed cumulative frequency distribution
      psdbiplots8.PNG
      The mean particle-size cumulative frequency distribution with 5 and 95% confidence levels.

back to plotting tools


6. Particle-size distribution moments plot


This option calculates the first four moments of each particle-size distribution and plots them against one another.

psdmoments.PNG


back to plotting tools


7. Principal component plots

  • Principal components rank the different parts of a data set according to how much they contribute to the overall variability. Because they are compositional data, particle-size distributions must be converted into log-ratios using the centrede log-ratio transform before the principal components can be calculated.

pcaplot.PNG
The first five principal components of the log-ratio particle-size distributions. These usually describe for nearly all of the variability in a data set.

back to plotting tools


8. alr plots

  • This a log-ratio version of the ternary plot that uses the additive log-ratio to show how particle-size data are distributed by their major size fraction.

  • You can manually specify which size fractions to plot.

alrplot.PNG
Similar to the ternary plot this figure uses the additive log-ratio transform to show the relative proportions of sand, silt and clay.


back to top





9. Voxel plots

  • Create a 3D Voxel Plot or a series of Cross-Sections using a 3D geological model. 3D geological models are stored in PST grid format:

pstvox1.png

3D Voxel Plot
  • If the geological model contains a very large number of voxels it can be useful to reduce the number of voxels viewed:
voxplot1.png
  • The number of voxels along any dimension (X, Y, Z) can be reduced by a given factor:


voxplot2.png


FACIES_DEF_voxelplot(90580).jpg
3D voxel plot of geological model.





Cross-Sections
  • Select whether to create horizontal slices or vertical cross-sections through the geological model:
sliceplot1.png
  • The number of horizontal slices or vertical cross-sections can then be entered:

    sliceplot2.png
  • The position of each individual slice or cross-section can be generated Automatically or entered Manually:

sliceplot5.png

    • The start and end points of vertical cross-sections are defined by Cartesian co-ordinates:
sliceplot6.png
    • The depth of horizontal slices are defined relative to a vertical datum:
sliceplot3.png


0008_FACIES_DEF.jpg
Vertical cross-section through a 3D geological model












-5.00m_FACIES_DEF.jpg
Horizontal slice through a 3D geological model.



back to top


5. LOAD GEOLOGICAL MODEL


This loads files containing geological model data into the Matlab environment for the Particle-Size Toolbox to use for modelling spatial trends. Be sure to load a geological model before allocating facies or selecting interpolation options

  • Select a directory containing the geological model file(s):
      • Directories can contain several geological files, which can be loaded all at once.

        Loading several model files at once allows very large areas to be split up into smaller subregions, or alternatively, allows different geological model realizations to be used at the same time.

geoload1.PNG




geoload2.PNG


  • Select which geological model files to load:
geoload3.PNG

            • The model files will then be loaded into Matlab


  • An example geological model can be created by entering Create_example_data into the Matlab command window. This will create an ASCII file which can be opened in a text editor or spreadsheet package.


Back to top


6. REGULARIZE BOREHOLE DATA


  • Borehole regularization converts irregularly spaced sediment layers into equal thickness model cells using the geological model parameters loaded in 5. LOAD GEOLOGICAL MODEL




  • During regularization when two or more layers are intercepted by the same model cell, data from each layer is merged into the new cell. For particle-size distributions this means that they will become mixed.

Borehole_regularize.png

For more information on how the mixing process works visit mixing particle-size distributions.


  • The geological model may be much larger than the borehole data, so you can optionally specify a lower limit on the borehole depth:
gridBorehole2.PNG


  • Regularized data are saved in new file called 'Gridded-data_.mat'. This is referred to by the Particle-Size Toolbox by the file variable gridFile.


Back to top

7. GRID TRANSFORMATION - under development


  • Applying a transformation to a geological model can help to simplify complex geological structures.






8. ALLOCATE GEOLOGY TO DATA



  • If different geological models overlap, e.g. because an area is split up into tiles or there are multiple realizations of the same model loaded, the regularized data cells are assigned more than one geology type.

  • When all the geological model files have been processed a figure is created, showing which boreholes have been allocated a geology code and which have not. The plot will be saved to the Figure directory in your PST project.
allocateGeology.PNG
Borehole locations are shown by red crosses. Boreholes that have been allocated a geology type are also marked by blue circles.


  • The different geology types assigned in this step are used to subdivide analytical steps in 9. Optimize particle-size data and 11. Perform Spatial Interpolation. This means that particle-size distributions in different geology types are treated separately and do not interact with one another. This helps to create a more realistic process-based model realization.


Back to top



9. OPTIMISE PARTICLE-SIZE DATA


  • Particle-size distributions contain a lot of auto-correlated data that can be effectively removed with no loss of data accuracy. Spatial interpolation is a very memory-intensive process, so it is beneficial to get rid of as much data as possible beforehand.

  • The amount of data to be removed varies depending on the signal-to-noise ratio of different analytic techniques and the heterogeneity of a sedimentary unit.

  • The Particle-Size Toolbox provides three different ways of optimizing the particle-size distributions:
optimize1.PNG
      • Principal Component Analysis (PCA) is the recommended optimization method.


  • Data optimization provides the option to use regularized data or the non-regularized raw data. To proceed to the interpoaltion step you must choose 'Regularized'.
optimize2.PNG

  • Two prompts will ask you to select the variables containing particle-size distributions and particle-size categories:
optimize3.PNG


1. Principal Component Analysis



  • Principle component analysis ranks the individual components of particle-size distribution data in terms of the total data variance they describe. To filter out the more noise) you must enter a higher threshold value. A threshold value of 10 coincides with the precision of Laser Granulometry particle-size analysers. There is no reason to enter a value lower than this.
optimize4.PNG
Components with a variance beneath this value are excluded from the interpolation scheme


2. Percentiles


  • The amount of data in a particle-size distribution can be effectively reduced by decreasing the number of particle-size categories by calculating its cumulative percentiles, e.g. D10, D20, D30, ... D90.

    • Enter the cumulative percentiles you want to use:

percOpt.PNG


  • Percentiles optimization finds the cumulative percentiles of the average particle-size distribution for each geology type. These particle-size are then used to down-sample all the particle-size distribution incorporated in that geology type.


3. Moments


  • Moments optimization summarizes each particle-size by its first four moments: mean, standard deviation, skewness and kurtosis.


Back to top


10. INTERPOLATION OPTIONS


Spatial interpolation of particle-size distributions uses the optimised particle-size data processed in 9. The optimised data can be interpolated by the Particle-Size Toolbox in Matlab, or it can be exported for interpolation by Isatis.

intOpt.PNG


To run the interpolation using Geovariances Isatis continue to 18. Isatis Interface


Interpolation in Matlab

  • Spatial interpolation in Matlab can be performed by the following methods:
        • Natural Neighbour
        • Nearest Neighbour
        • Linear
        • Cubic Spline
        • Krigging

  • After selecting an interpolation method a series of prompt screens provide further options:
        • Model vertical (z) trends: model and remove linear trends in particle-size data in the vertical plane

        • Model horizontal (x-y) trends: model and remove linear or quadratic trends in particle-size data in the horizontal plane

        • Normalise data: convert data or residuals to Gaussian distribution

Visit interpolate for more detailed information on interpolation methods used by the PST.


Back to top


11. GLOBAL TREND MODELLING


  • Run the spatial interpolation scheme in Matlab using the options selected in 10. INTERPOLATION OPTIONS. The modeled data are saved to a new data file.

Back to top


12. GAUSSIAN TRANSFORMATION




Back to top


13. VARIOGRAM MODELLING




Back to top


14. CROSS-VALIDATION




Back to top


15. INTERPOLATION




Back to top

16. DATA TRANSFORMATIONS




Back to top

18. ISATIS INTERFACE


  • The Isatis Interface allows users to export optimized particle-size data to Geovariances Isatis and automate the interpolation process in Isatis through the creating of Isatis journal files.isatsisInterface1.png


  • The Isatis interface has five options:






Back to top

EXPORT OPTIONS

  • To run an interpolation in Isatis you must first define a series of parameters about the Isatis study you will be using. This study must already exist - it won't be created by the Particle-Size Toolbox.

      • Enter the name of the Isatis study you want to use:
isatisint3.PNG

      • Enter the name of an Isatis directory you want to load the exported data into:
isatisint4.PNG

      • You must select at this stage whether you want to perform Global Trend Modelling or Raw --> Gaussian Transformation on your exported data:
isatisint5.PNG
Raw --> gaussian transforms are usually not needed for principal component data.


      • Enter the name of the Isatis 3D grid directory that the model predictions will be stored in:
isatisint6.PNG

      • Enter the name of the geological type variable that will be used to partition the interpolation scheme.
isatisint7.PNG
This should be the same geology type used in the geological model files


      • Enter the name of the variables that the modeled data and the uncertainty estimates will be stored in:
isatisint8.PNG

      • You will also be asked to locate the Isatis program file on your computer system:
isatisint9.PNG

  • Once these parameters have been defined you can continue with the other functions.


Back to Isatis Interface

EXPORT DATA TO ISATIS

  • Export the data variable specified in EXPORT OPTIONS as an Isatis formatted ASCII Lines or Points file.
export2isatis.PNG
For borehole data a 'Lines' file should be selected.


export2isatis2.png


  • Once the data file has been created it can be loaded into Isatis manually or by creating a journal file.

Back to Isatis Interface

IMPORT ISATIS DATA TO MATLAB

  • Import data from Isatis binary or ASCII grid files into Matlab. Data export from Isatis can be automated by creating an export journal file.



Back to Isatis Interface

CREATE JOURNAL FILES

  • Creating Isatis journal files allows you to automate data processing in Isatis and greatly speeds up the modeling process.

    • Journal files are created in you PST project, in the directory 'Data\Isatis\Isatis Journal Files'

    • Journal files can also be run in a 'headless' mode by opening the file 'run.bat' in the Isatis Journal Files directory. The results from these journal files are saved in an Isatis 'ilog' file so you can see what is happening.


  • To create one or more journal files select any combination of these options:

ijnlCreate10.png
NB. If you don't see all of these options you may not have selected 'Global Trend Modelling'or 'Raw --> Gaussian transformation' when setting Isatis Export Options

Once a set of options have been selected you can also select which geology types you want to process:


LOAD DATA
    • Load data exported from your PST project into Isatis


GLOBAL TREND MODELLING
    • Apply a global trend model to your data. Trend models are applied separately to each geology type.


RAW --> GAUSSIAN TRANSFORMATION
    • Transform data into Gaussian or Normal variables.


EXPERIMENTAL VARIOGRAMS
    • Create experimental variograms for each data variable. Separate variograms are created for each geology type.

    • Experimental variograms can be fully automated by selecting the Default Values:

varioCreate.PNG



    • If a variogram model has already been created previously you can use that, edit the model parameters or create a new model using the default values.

    • By selecting 'Specify Parameters' you can define up to 3 variogram directions

varioCreate4.PNG


    • For each model direction you can specify the following parameters:

varioCreate5.PNG
varioCreate6.PNG


    • Experimental variograms created by Isatis journal files are saved as images in the PST project directory under 'Projectname\Figures\ISATIS\EXPERIMENTAL_VARIOGRAMS'. You can use these image files to see if you want to modify you experimental variogram parameters and make them again by running new journal files.



VARIOGRAM MODELLING
    • Create variogram models using the parameters from EXPERIMENTAL VARIOGRAMS

varioModel1.PNG



    • Variogram models created by Isatis journal files are saved as images in the PST project directory under 'MyProjectName\Figures\ISATIS\VARIOGRAMS'.


    • Variogram models are saved as parameter files in Isatis so you can also alter them manually.
      • NB - Variogram parameter files are overwritten each time a VARIOGRAM MODELLING journal file is run. Selecting individual geology types allows you to modify a few variogram models at a time, rather than loosing changes made to parameter files from within Isatis.


CREATE 3D GRID SELECTIONS
    • Create selection variables for each geology type in the 3D grid directory specified by 1. EXPORT OPTIONS.


CROSS VALIDATION
    • Run a cross-validation scheme on data using the variogram models create by VARIOGRAM MODELLING


KRIGING
    • Perform interpolation using kriging and the variogram models created in VARIOGRAM MODELLING.
    • Kriging automatically creates a neighbourhood file with default paramters. You may wish to change this later and run the journal files again if you are not happy with the result.


GAUSSIAN --> RAW TRANSFORMATION
    • Transform predicted variables to non-Gaussian variables by applying the inverse of the RAW --> GAUSSIAN MODEL.


GLOBAL TREND MODEL INVERSION
    • Add the global trend model parameters to the results of KRIGING or GAUSSIAN --> RAW TRANSFORMATION.
    • The results of this step will be predicted principal components.


PRINCIPAL COMPONENT INVERSION
    • Apply an inverse model transform to the results of KRIGING, GAUSSIAN --> RAW TRANSFORMATION or GLOBAL TREND MODEL INVERSION.
    • Data will be transformed into log-ratio space


INVERSE CENTERED LOG-RATIO TRANSFORM
    • Convert particle-size data from log-ratio space into percentage values using an inverse centered log-ratio transformation.
    • Modeled article-size distributions use the particle-size categories specified in 2. INTEGRATE DATA.
    • Each particle-size category is labelled PSD_D, where D is the particle-size in micrometres.


MAPS AND CROSS SECTIONS
    • Create maps and cross sections from 3D Isatis grid variables.

isatisMap1.PNG



    • Maps and cross sections are created using a user-specified number of equally-spaced slices using user-defined slice thicknesses and orientations:

isatisMap3.PNG

isatisXsec1.PNG
    • Alternatively the positions of individual maps or cross sections can be defined by Cartesian co-ordinates:


isatisXsec4.PNG
x-y co-ordinate pairs for 10 user-defined cross-section slices
isatisMap7.PNG
User-specified horizontal slice depths for 10 maps


  • Maps and cross-sections are saved as images in the PST project directory under 'MyProjectName\Figures\ISATIS\MAPS'.


Back to Isatis Interface

EXPORT DATA FROM ISATIS
    • Export variables from 3D grid directories as Isatis binary or ASCII formatted files. Binary files are recommended because they are approximately 10 times smaller than ASCII files.

    • NB - ASCII file export will not work for large 3D grids (>1 million voxels).

Back to Isatis Interface

ISATIS BINARY FILE STATISTICS
    • Calculate particle-size statistics from Isatis binary files:

isatisbinfunc.png

  • Complete particle-size distributions are needed for both 'Descriptive statistics' and 'Texture classification' processes. This means that you must export all of you particle-size data variables from Isatis to create one binary file for each particle-size category. To automate this use 18.ISATSIS INTERFACE>CREATE ISATIS JOURNAL FILES>EXPORT DATA FROM ISATIS.



DESCRIPTIVE STATISTICS
    • Select a range of statistics to calculate from Pearson's moments, Folk and Ward graphic measures or Percentiles:

isatisbinfunc8.png
    • You will then be asked to load binary files containing particle-size %-frequency data:
isatisbinfunc7.png

    • Select all the files containing percentage-frequency data at once and press 'Open'


isatisbinfunc5.png


    • Automatically allows you to load the categories from a variable in a Matlab data file:
        • e.g. PSD_CAT from 'Integrated-data_[timeANDdate].mat'


isatisbinfunc4.png
If the number of size classes in PSD_CAT doesn't match the number of Isatis binary files you have loaded you must specify the size classes again

  • Alternatively you specify the upper limit of each particle-size class manually:
isatisbinfunc11.png

Once the particle-size classes have been allocated the selected particle-size statistics will be calculated and saved to a new Isatis binary file of your choosing.


UNIT CONVERSION

    • Convert Isatsis binary files containing particle-size data (e.g. mean particle-size) into a different size unit:

isatisbinfunc10.png
Choose from 'phi', 'micrometres', 'millimetres', 'centimetres', 'metres, 'inches', 'feet' and 'yards'.
    • The converted data will be saved to a new Isatis binary file.

TEXTURE CLASSIFICATION
    • Classify particle-size data using NEN5104 or USDA sediment classification systems:

textclass.png


    • You will then be asked to load binary files containing particle-size %-frequency data:
isatisbinfunc7.png

  • Select all the files containing percentage-frequency data at once and press 'Open'


isatisbinfunc5.png
  • Automatically allows you to load the categories from a varia ble in a Matlab data file:
    • e.g. PSD_CAT from 'Integrated-data_[timeANDdate].mat'
isatisbinfunc4.png
If the number of size classes in PSD_CAT doesn't match the number of Isatis binary files you have loaded you must specify the size classes again

  • Alternatively you specify the upper limit of each particle-size class manually:

isatisbinfunc11.png

  • Once the particle-size classes have been allocated the texture classification will be performed and saved to a new Isatis binary file of your choosing. The new binary file will contain different numbers that refer to different textural classes. To interpret these you must refer to the text file that will be saved alongside and called 'NEN5104.txt' or 'USDA.txt'.

Back to Isatis Interface

Back to top