Geological Programs for Mathematica v2.0 readme.txt
by Matty Mookerjee, Department of Geology, Sonoma State University, 
Rohnert Park, CA 94928

Updated June 12th, 2014 

Send all feedback/comments/problems to matty.mookerjee@sonoma.edu

The reference to article which describe the best-fit strain ellipsoid
method and the associated statistical analysis is the following:

Mookerjee, M., Nickleach, S., 2011.  Three-dimensional strain analysis 
using Mathematica.  Journal of Structural Geology 33, 1467-1476. 
DOI: 10.1016/j.jsg.2011.08.003

For the details about the latest changes to this and past version of 
the Geological Programs for Mathematica program suite, scroll to the 
bottom of this document. Also, see the end of this document for 
licensing information under "Legal Stuff."


INTRODUCTION
============

The "Geological Programs for Mathematica" is a suite of programs that 
can be used by geologists to undertake quantitative analysis with a 
particular focus on strain analysis.  These programs were written in 
Mathematica 6, Mathematica 7, and the latest version, v2.0, was fully 
tested in Mathematica 8.

Please send your comments to the above e-mail address.  Also, please 
keep checking the website for the latest version.

A version of Mathematica is required to run these programs, although 
they are reported to work in Mathematica Player Pro, which is much less 
costly than the entire Mathematica Program.  If you go the Mathematic 
Player Pro route, you will not be able to edit the notebooks (e.g., you 
will not be able to change the formatting of your plots, you will have 
to stick with the default values).  If you are associated with a 
University, you may already have a University-wide site license for 
Mathematica (this is fairly common).

To read a file into one of the Mathematica programs, the file needs to 
be in the appropriate location.  Typically, this is in the "My 
Documents" folder for Windows operating systems.  To determine where 
Mathematica is going to look for your file, simply type "Directory[]" 
into a Mathematica notebook and evaluate the cell (i.e., type "Shift"
+"Enter" or hit the "Enter" key adjacent to the number pad). If you 
want to change this location, you can use the SetDirectory[] function.  
I would recommend placing all of the files from the "Sample Data Sets" 
folder into this directory so that you can see how the programs are 
meant to run.  Also, any files that you export (e.g., graphical output 
files) will appear in this directory. 

I very much support the ideas surrounding open source software and the 
communities that often form around popular software packages.  So, 
please feel free to edit/tinker/over haul any or all of these programs.  
One of the main reasons for writing these programs in Mathematica is so 
that the users can easily edit the programs to accommodate their needs.  
I do ask, however, that if you do make changes to one of the programs 
that you change the file name, preferably by simply addition your last 
name (e.g. "Best Fit Ellipsoid-v_1_0-Smith edits.nb").  Also, it would 
be appreciated if you would describe the changes that you made in the 
introductory text at the beginning of the program.  This is particularly 
important if you ever share your version of the file with anyone else. 


LIST OF PROGRAMS
================

"Best Fit Ellipsoid-v3_0.nb"
"Best Fit Ellipsoid with Statistics-v3_0.nb"
"Best Fit Ellipsoid for ImageJ-v3_0.nb"
"Best Fit Ellipsoid-Absolute-v3_0.nb"
"Best Fit Ellipsoid-Absolute For ImageJ-v3_0.nb"
"Best Fit Ellipsoid with Statistics for ImageJ-v3_0.nb"
"Best Fit Ellipsoid with Statistics-Absolute-v3_0.nb"
"Best Fit Ellipsoid with Statistics-Absolute for ImageJ-v3_0.nb"
"Best Fit Ellipsoid with Vort-v3_0.nb"
"Best Fit Ellipsoid with Statistics with Vort-v3_0.nb"
"Best Fit Ellipsoid for ImageJ with Vort-v3_0.nb"
"Best Fit Ellipsoid-Absolute with Vort-v3_0.nb"
"Best Fit Ellipsoid-Absolute For ImageJ with Vort-v3_0.nb"
"Best Fit Ellipsoid with Statistics for ImageJ with Vort-v3_0.nb"
"Best Fit Ellipsoid with Statistics-Absolute with Vort-v3_0.nb"
"Best Fit Ellipsoid with Statistics-Absolute for ImageJ with Vort-v3_0.nb"
"Flinn Plot-v3_0.nb"
"Flinn Plot with Error Regions-v3_0.nb"
"Hsu Plot-v3_0.nb"
"Hsu Plot with Error Regions-v3_0.nb"
"Equal Area&Angle Projections-v3_0.nb"
"Rose Diagram-v3_0.nb"
"Ternary Diagram-v3_0.nb"
"Sectional Data through an Ellipsoid-v3_0.nb"
“Vorticity Diagram-v3_0.nb”
“Vorticity Diagram with Error Regions-v3_0.nb”
"2D Pure vs Simple Shear-v3_0.nb"

Below is a brief description of these programs.


BEST FIT ELLIPSOID
==================

This program determines the best fit ellipsoid for arbitrarily 
oriented sectional ellipses.  Input for this program includes the 
axial ratio and orientation of the sectional ellipses without needing 
to know specific axial lengths or ellipse areas.  One can either 
specify the mean values or input the raw data (i.e., a file with 
several/many elliptical measurement) and the means will be calculated 
automatically.  The mean ellipses are determined by averaging ellipse 
shape tensors as described by Shimamoto & Ikeda (1976) and Wheeler 
(1984).  Additionally, one also needs to input the dip and dip 
direction of the plane from which the data were collected.  Data can 
either be input manually during the running of the program or it can 
be read in from an existing file.  This program will read both text 
files (*.txt) and Excel files (*.xls but NOT *.xlsx).  Examine the 
files, "Sample Strain Data No stats.txt", and "Sample Strain Data NO 
stats.xls", to determine the appropriate file structure (it is easiest 
simply to modify these files and save them with different file names).   
          
The sign convention that this program uses is as follows:  1) all 
sectional data need to be viewed from the perspective of looking 
downward, 2) perfectly vertical planes need to be viewed looking 
westward; for vertical planes that are striking exactly east-west, 
the plane needs to be view from the south to the north, 3) the 
orientation angle (phi) is measured from the long axis of the ellipse 
to the strike line of the sectional plane, 4) phi is positive when it 
has a positive slope and negative when it has a negative slope, and 
5) for perfectly horizontal planes, phi is measured from the 
east-west line such that the NE quadrant is positive and the SE 
quadrant is negative. 

This program determines the best fit ellipsoid by defining a least 
squared error function that gets minimized using the FindMinimum 
Mathematica function (uses a steepest decent algorithm).  The 
least squared error function is constructed by subtracting the matrix 
elements assembled from the axial ratio and angular orientation data 
from the corresponding elements of that specific section through a 
general ellipsoid and then, of course, squaring this value and 
summing them all together.  The “Mean Error” which is reported along 
with the best fit ellipsoid data is the mean of the absolute values 
of the differences between the initial data matrix elements and the 
matrix elements of the fit ellipsoid for all of the data sections.  
The lower this value the more compatible the initial data are with an 
actual ellipsoid.

As is discussed in Launeau & Robin (2005), it is possible that the best 
fit surface for the data is actually a hyperboloid (i.e., a symmetric 
three by three matrix with a negative eigenvalue) instead of an 
ellipsoid.  This program constrains the FindMinimum function so that 
negative eigenvalues are unacceptable.  However, if this constraint is 
necessary, the resulting ellipsoid generally has an unrealistically 
large long axis.  Therefore, while this is the best fit ellipsoid for 
the given data, the program will output a suggestion to the user that 
she/he should most likely collect more data to further constrain the 
ellipsoid shape.

This program outputs several graphics including a three-dimensional 
plot of the best fit ellipsoid with and without the representations of 
the planar sections from which the data were collected, as well as a 
Flinn Diagram (Flinn, 1962) and a Hsu Diagram (Hossack, 1967).  More 
importantly, perhaps, are the graphs of the original elliptical data on 
top of the elliptical section from the best fit ellipsoid for each of 
the data planes.  These graphs give the user a real intuitive 
understanding of the compatibility of their data and how the original 
data have been modified to generate a truly ellipsoidal shape.

All of these graphics can either be copied and pasted into other 
programs, or exported as specific types of files (e.g., jpeg, tiffs, 
etc.).  See the bottom of the program for cells that will assist you in 
exporting your graphics.

This notebook includes some code for plotting equal area and equal angle 
projections that was modified from code written by Joshua R. Davis.


BEST FIT ELLIPSOID WITH STATISTICS
==================================

This Mathematica notebook works the same as the previously discussed 
notebook, but adds to it a statistical component. One can either 
specify the mean values and standard deviations for the axial ratios 
(Rf's) and the angular orientations (phi's) along with the number of 
ellipses measured or input the raw data (i.e., a file with several/many 
elliptical measurement) and the means and standard deviations will be 
calculated automatically.  Additionally, one also needs to input the 
dip and dip direction of the plane from which the data were collected 
and an estimation of the precision of that measurement in the form of 
an angular error (i.e., the angle away from the pole to the plane in 
any direction which then defines a subset of all possible 
orientations).  

This program takes the input data for the ellipses and uses the 
standard deviations and the angular error for the section plane 
measurements to run a Monte Carlo-type simulation.  During the 
simulation loop, the Rf’s and phi’s are continually redefined and 
randomly chosen from a normal distribution such that the mean is equal 
to the initial input data and the standard deviation is the standard 
deviation of the data set divided by the square root of the number of 
data measurements.  Also, the orientations of the planes from which the 
data were collected are continually redefined and chosen from a 
normal distribution where the standard deviation is specified by the 
user.  The simulation generates a population of data that describe a 
region within which the “true” answer is likely to be.  This data set  
is used to construct a kernel density estimator from which a 
confidence region can be assigned (e.g., the 95% confidence region).  
Using this region, confidence limits are then placed on the strain 
parameters, octahedral shear strain, Flinn’s k-value, and Lodes Ratio.  
Also, the population of ellipsoid axes orientation are used to define a 
confidence region. The size of percent confidence region (where the 
percentage is chosen by the user) is determined assuming a gamma 
distribution for the angles between the fit ellipsoid principal axes and 
the principal axes calculated during the simulation.  This parameter is
refered to as the “confidence angle.”  In addition to calculating the 
confidence angle, this program can also determine an alpha confidence 
region (e.g., alpha-95 as is used to describe paleomagnetic data 
confidence regions, (e.g., see Butler’s textbook Paleomagnetism: Magnetic 
Domains to Geologic Terranes(1992))).  However, I feel that the alpha 
confidence region underestimates the confidence region (it is generally 
about an order of magnitude smaller than the confidence angle) and that 
the confidence angle is a more appropriate measure.  Thus, the alpha 
confidence calculations are by default turned off and the user needs to 
turn them on to have them calculated (define "AlphaOn" as one in 
uppermost section of the code where various constants are defined).  

I am convinced that adding these sorts of confidence estimations to 
strain analysis will help investigators make more informed and 
reasonable geological interpretations while giving them feedback on  
their data collection techniques and help them decide when more data  
are required to further constrain a problem.

Your data can either be input manually during the running of the 
program or it can be read in from an existing file.  This program 
will read both text files (*.txt) and Excel files (*.xls but NOT 
*.xlsx).   Examine the files, "Sample Strain Data for Stats.txt", 
"Sample Strain Data for Stats.xls", "Sample Strain Data with Std 
Dev.txt", and "Sample Strain Data with Std Dev.xls", to determine 
the appropriate file structure (it is easiest just to modify these 
files and save them with different file names).  The reason for the 
two different file formats (i.e., “Sample Strain Data for Stats” and 
“Sample Strain Data with Std Dev”) is to give the user the option 
of not using this program’s built in ability to calculate the mean 
ellipses by averaging the ellipse shape tensors as described by 
Shimamoto & Ikeda (1976) and Wheeler (1984), but to instead, input 
the results of her/his own two-dimensional strain analysis (e.g., the 
Fry or Rf/phi methods).  If these alternate methods are used, the 
user must also input the standard deviations and size of their data 
set, hence, the two different file structures.

As with the “Best Fit Ellipsoid” program, this program outputs several 
graphics including a three-dimensional plot of the best fit ellipsoid 
with and without the representations of the planar sections from which 
the data were collected, as well as a Flinn diagram (Flinn, 1962) and 
a Hsu diagram (Hossack, 1967).  Both the Flinn and Hsu diagrams 
represent the confidence region for the strain ellipsoid shape.  For 
the Flinn diagram there are three ways of representing this area.  By 
default the program will output the error region as an irregular 
polygon.  This has the benefit of more accurately representing the 
actual error region as well as, in general, illustrating a 
significantly smaller error region.  However, one also has the 
option of representing the error region as delimited by the + and 
- values of Octahedral Shear Strain, Lode's Ratio, and Flinn's k-value 
(and in some cases the + and - values of Rxy and Ryz on for the Flinn 
Diagram).  This feature can be "turned on" by changing the definition of 
"ComplexPolyOrRegularPoly" from being equal to one to being equal to 
zero.  This can be done at the begining of the code where several/many
variables are defined and accompany some explanitory text in comments
(i.e., between (* *)).  In this case the Flinn diagram plots the error
region either as a rectangular region with plus or minus Rxy and Ryz 
values or using the plus or minus Epsilon-S and k values.  Of these two,
I often prefer the latter; however, there are times when the area of the 
rectangular region is significantly smaller than the more irregularly 
shaped Epsilon-S/k-value error region.  Because of this, the parameter, 
“ErrorShapePercent”, is added, which helps the program decide which 
region to display.  If “ErrorShapePercent” is set to one, then the 
program will display the error region that has the smallest area; 
however, if the user increase this value then this indicates a 
preference for displaying the more irregularly shaped error region 
(and vice versa).  If “ErrorShapePercent” is set to 1.5, for instance, 
then the irregularly shaped region would have to be more than 1.5 
times the area of the rectangular region before the program will 
display the rectangular area.  This program will also display equal 
area plots of the ellipsoid axes calculated during the  simulation 
along with their mean orientations and the best fit ellipsoid axes 
orientations.  As with the “Best Fit Ellipsoid” program, this program 
graphs the original elliptical data on top of the elliptical section 
from the best fit ellipsoid for each of the data planes.  These graphs 
give the user a real intuitive understanding of the compatibility of 
their data and how the original data have been modified to generate a 
truly ellipsoidal shape.

All of these graphics can either be copied and pasted into other 
programs, or exported as specific types of files (e.g., jpegs,tiffs, 
etc.).  See the bottom of the program for cells that will assist you in 
exporting your graphics.

This notebook includes some code for plotting equal area and equal angle 
projections that was modified from code written by Joshua R. Davis. 


BEST FIT ELLIPSOID FOR IMAGEJ
=============================

This program is the same as the “Best Fit Ellipsoid.nb” program that was 
describe above with the exception of the sign convention.  Moreover, 
only #4 of the sign convention is different (i.e., phi is positive when 
it has a positive slope and negative when it has a negative slope).  
Instead of defining phi from -90 to +90, this program defines phi from 0 
to 180 which is consistent with the output of ImageJ (a useful program 
for strain analysis). Therefore, phi is always positive and is measured 
counter clockwise from the positive horizontal axis.  

This program will read both text files (*.txt) and Excel files (*.xls but 
NOT *.xlsx).  Examine the files, "Sample Strain Data No stats from 
ImageJ.txt", and "Sample Strain Data NO stats from ImageJ.xls", to 
determine the appropriate file structure (it is easiest simply to modify 
these files and save them with different file names).

This notebook includes some code for plotting equal area and equal angle 
projections that was modified from code written by Joshua R. Davis.


BEST FIT ELLIPSOID-ABSOLUTE
===========================

This program is the same as the “Best Fit Ellipsoid.nb” program that was 
describe above with the exception that instead of using axial ratios with 
normalized areas, this program uses absolute lengths.  By using the 
absolute lengths of ellipse axes,the absolute size and volume of the best 
fit ellipsoid can be calculated.

This program will read both text files (*.txt) and Excel files (*.xls but 
NOT *.xlsx).   Examine the files, "Sample Strain Data No stats-ABS.txt", 
and "Sample Strain Data NO stats-ABS.xls", to determine the appropriate 
file structure (it is easiest simply to modify these files and save them 
with different file names).   

This notebook includes some code for plotting equal area and equal angle 
projections that was modified from code written by Joshua R. Davis.


BEST FIT ELLIPSOID-ABSOLUTE FOR IMAGEJ
======================================

As the title suggest, this program is a combination of “Best Fit 
Ellipsoid-Absolute.nb” and “Best Fit Ellipsoid For ImageJ.nb.”  In other 
words, this program uses absolute lengths of ellipse axes to calculate 
the absolute size and volume of the best fit ellipsoid and it uses the 
sign convention used by ImageJ (i.e., phi is defined from 0 to 180 and 
is measured counter clockwise from the positive horizontal axis).

This program will read both text files (*.txt) and Excel files (*.xls but 
NOT *.xlsx).   Examine the files, "Sample Strain Data No stats-ABS from 
ImageJ.txt", and "Sample Strain Data NO stats-ABS from ImageJ.xls", to 
determine the appropriate file structure (it is easiest simply to modify 
these files and save them with different file names). 

This notebook includes some code for plotting equal area and equal angle 
projections that was modified from code written by Joshua R. Davis.  


BEST FIT ELLIPSOID WITH STATISTICS FOR IMAGEJ
=============================================

This program is the same as the “Best Fit Ellipsoid with 
Statistics.nb” program that was describe above with the exception of 
the sign convention.  Moreover, only #4 of the sign convention is 
different (i.e., phi is positive when it has a positive slope and 
negative when it has a negative slope).  Instead of defining phi from 
-90 to +90, this program defines phi from 0 to 180 which is consistent 
with the output of ImageJ (a useful program for strain analysis).  
Therefore, phi is always positive and is measured counter clockwise 
from the positive horizontal axis.  

This program will read both text files (*.txt) and Excel files (*.xls 
but NOT *.xlsx).   Examine the files, "Sample Strain Data for Stats 
from ImageJ.txt", "Sample Strain Data for Stats from ImageJ.xls", 
"Sample Strain Data with Std Dev from ImageJ.txt", and "Sample Strain 
Data with Std Dev from ImageJ.xls", to determine the appropriate file 
structure (it is easiest simply to modify these files and save them 
with different file names).

This notebook includes some code for plotting equal area and equal angle 
projections that was modified from code written by Joshua R. Davis. 


BEST FIT ELLIPSOID WITH STATISTICS-ABSOLUTE
===========================================

This program is the same as the “Best Fit Ellipsoid with 
Statistics.nb” program that was describe above with the exception that 
instead of using axial ratios with normalized areas, this program uses 
absolute lengths.  By using the absolute lengths of ellipse axes, the 
absolute size and volume of the best fit ellipsoid can be calculated.

This program will read both text files (*.txt) and Excel files (*.xls 
but NOT *.xlsx).   Examine the files, "Sample Strain Data for 
Stats-ABS.txt", "Sample Strain Data for Stats-ABS.xls", "Sample Strain 
Data with Std Dev-ABS.txt", and "Sample Strain Data with Std 
Dev-ABS.xls", to determine the appropriate file structure (it is 
easiest simply to modify these files and save them with different file 
names).   

This notebook includes some code for plotting equal area and equal angle 
projections that was modified from code written by Joshua R. Davis. 


BEST FIT ELLIPSOID WITH STATISTICS-ABSOLUTE FOR IMAGEJ
======================================================

As the title suggest, this program is a combination of “Best Fit 
Ellipsoid with Statistics-Absolute.nb” and “Best Fit Ellipsoid with 
Statistics For ImageJ.nb.” In other words, this program uses absolute 
lengths of ellipse axes to calculate the absolute size and volume of the 
best fit ellipsoid and it uses the sign convention used by ImageJ (i.e., 
phi is defined from 0 to 180 and is measured counter clockwise from the 
positive horizontal axis).

This program will read both text files (*.txt) and Excel files (*.xls 
but NOT *.xlsx).   Examine the files, "Sample Strain Data for Stats-ABS 
for ImageJ.txt", "Sample Strain Data for Stats-ABS for ImageJ.xls", 
"Sample Strain Data with Std Dev-ABS for ImageJ.txt", and "Sample Strain 
Data with Std Dev-ABS for ImageJ.xls", to determine the appropriate file 
structure (it is easiest simply to modify these files and save them with 
different file names).   

This notebook includes some code for plotting equal area and equal angle 
projections that was modified from code written by Joshua R. Davis. 


FLINN PLOT
==========

This Mathematic notebook will plot your ellipsoid data onto a Flinn 
diagram (Flinn, 1962) with both "k" contours and octahedral shear 
strain (Epsilon-s) (Nadai, 1963) contours.  Your data can either be input 
manually while the program is running or your data can be read in from 
an existing file.  This program will read both text files (*.txt) and 
Excel files (*.xls but NOT *.xlsx).  Examine the files, 
"AxesDataSet.txt" and "AxesDataSet.xls", to determine the appropriate 
file structure (it is easiest simply to modify these files and save 
them with different file names).  If your data are coming from running 
either the “Best Fit Ellipsoid” or “Best Fit Ellipsoid with Statistics” 
programs, be sure to export the raw data file (at the very bottom of the 
notebook) which can save you some time when assembling your data file to 
be read in by the “Flinn Plot” program. Please note that your sample names 
can only be one-word long, i.e., they cannot contain any spaces, but 
underscores and dashes are acceptable (e.g. SL-137-02).  Within the 
code itself, there are parameters that you may wish to alter to 
appropriately scale and format your plot.  The most useful changes are 
described in comments (i.e., between "(* *)").  

Your plot can either be copied and pasted into other programs, or 
exported as specific types of files (e.g., jpegs, tiffs, etc.).  See the 
bottom of the program for cells that will assist you in exporting your 
graphics.


FLINN PLOT WITH ERROR REGIONS
=============================

This Mathematica notebook will plot your ellipsoid data onto a Flinn 
diagram (Flinn, 1962) with both "k" contours and octahedral shear 
strain (Epsilon-s) (Nadai, 1963) contours and will define an error region 
of your choosing.  Your data can either be input manually while the 
program is running or your data can be read in from an existing file.  
This program will read both text files (*.txt) and Excel files (*.xls 
but NOT *.xlsx).  Examine the files, "AxesDataSetFlinnError.txt",
"AxesDataSetFlinnError.xls", "SampleFlinnErrorData.txt", and 
"SampleFlinnErrorData.xls", to determine the appropriate file 
structure (it is easiest simply to modify these files and save them 
with different file names).  If your data are coming from running either 
a “Best Fit Ellipsoid with Statistics” programs, be sure to export the 
data file (at the very bottom of the notebook).  Please note that your 
sample names can only be one-word long, i.e., they cannot contain any 
spaces, but underscores and dashes are acceptable (e.g. SL-137-02).  
within the code itself, there are parameters that you may wish to alter 
to appropriately scale and format your plot.  The most useful changes are 
described in comments (i.e., between "(* *)").  

Your plot can either be copied and pasted into other programs, or 
exported as specific types of files (e.g., jpegs, tiffs, etc.).  See the 
bottom of the program for cells that will assist you in exporting your 
graphics.


HSU PLOT
========

This Mathematic notebook will plot your ellipsoid data onto a Hsu 
diagram (Hossack, 1967) with both Lode's Ratio (nu) contours and 
octahedral shear strain (Epsilon-S) (Nadai, 1963) contours.  Your data 
can either be input manually while the program is running or your data 
can be read in from an existing file.  This program will read both 
text files (*.txt) and Excel files (*.xls but NOT *.xlsx).  Examine 
the files, "AxesDataSet.txt" and "AxesDataSet.xls", to determine the 
appropriate file structure (it is easiest simply to modify these files 
and save them with different file names).  If your data are coming from 
running either one of the “Best Fit Ellipsoid” or “Best Fit Ellipsoid 
with Statistics” programs, be sure to export the raw data file (at the 
very bottom of the notebook) which can save you some time when 
assembling your data file to be read in by the “Hsu Plot” program. 
Please note that your sample names can only be one-word long, i.e., 
they cannot contain any spaces, but underscores and dashes are 
acceptable (e.g. SL-137-02).  Within the code itself, there are 
parameters that you may wish to alter to appropriately scale and format 
your plot. The most useful are described in comments (i.e., 
between "(* *)").  

Your plot can either be copied and pasted into other programs, or 
exported as specific types of files (e.g. jpegs, tiffs, etc.).  See the 
bottom of the program for cells that will assist you in exporting your 
graphics.


HSU PLOT WITH ERROR REGIONS
===========================

This Mathematic notebook will plot your ellipsoid data onto a Hsu 
diagram (Hossack, 1967) with both Lode's Ratio (nu) contours and 
octahedral shear strain (Epsilon-S) (Nadai, 1963) contours and will 
define an error region of your choosing.  Your data can either be input 
manually while the program is running or your data can be read in from 
an existing file.  This program will read both text files (*.txt) and 
Excel files (*.xls but NOT *.xlsx).  Examine the files, 
"AxesDataSetHsuError.txt", "AxesDataSetHsuEror.xls", 
"SampleFlinnErrorData.txt", and "SampleFlinnErrorData.xls" to determine 
the appropriate file structure (it is easiest simply to modify these 
files and save them with different file names).  If you data are coming 
from running either one of the “Best Fit Ellipsoid with Statistics” 
programs, be sure to export the raw data file (at the very bottom of 
the notebook).  Please note that your sample names can only be 
one-word long, i.e., they cannot contain any spaces, but underscores 
and dashes are acceptable (e.g. SL-137-02). Within the code itself, 
there are parameters that you may wish to alter to appropriately scale 
and format your plot.  The most useful are described in comments 
(i.e., between "(* *)").  

Your plot can either be copied and pasted into other programs, or 
exported as specific types of files (e.g., jpegs, tiffs, etc.).  See the 
bottom of the program for cells that will assist you in exporting your 
graphics.


EQUAL AREA&ANGLE PROJECTIONS
============================

This Mathematica notebook will plot both linear and planar data 
on either an equal-area or equal angle plot.  Planar data can be 
displayed either as a great circle projection or as the pole to the 
plane (or both). 
 
Your data can either be input manually while the program is 
running or they can be read in from an existing file. This program 
will read both text files (*.txt) and Excel files (*.xls but NOT 
*.xlsx).  Examine the sample files, "Equal Area Projection 
Example.xls", "Equal Area Projection Example.txt", "Equal Angle 
Projection Example.xls", and "Equal Angle Projection Example.txt", to 
determine the appropriate file structure (it is easiest just to modify 
this file and save it as a different file name).  Within the code 
itself, there are parameters that you may wish to alter to format your 
plot.  The most useful parameters are described in comments below 
(i.e., between "(* *)"). 
 
Your plot can either be copied and pasted into other programs, or 
exported as specific types of files (e.g., jpegs, tiffs, etc.).  See the 
bottom of the program for cells that will assist you in exporting your 
graphics.

This notebook includes some code for plotting equal area and equal angle 
projections that was modified from code written by Joshua R. Davis. 
	

ROSE DIAGRAM
============

This Mathematica notebook will plot your trend data on a 
rose diagram.  Your data can either be input manually while the 
program is running or your data can be read in from an existing file.  
This program will read both text files (*.txt) and Excel files (*.xls 
but NOT *.xlsx).  Examine the files, "Rose Diagram Sample.txt" and 
"Rose Diagram Sample.xls" to determine the appropriate file structure.  
When prompted, input your desired bin width (i.e., the size of the 
interval range in number of degrees).  You will also be prompted to 
define the contour interval for the concentric frequency contours.  
Finally, you will be asked whether your data are "directional" or 
"non-directional," meaning, does your data indicate a specific bearing 
(e.g., paleo-flow directions) which will yield an asymmetric plot, or 
are your data non-directional (e.g., the strike of vertical joints) 
which therefore yield a symmetric plot.   Within the code itself, 
there are parameters that you may wish to alter to appropriately 
format your plot.  The most useful are described in comments (i.e., 
between "(* *)").

Your plot can either be copied and pasted into other programs, or 
exported as specific types of files (e.g., jpegs, tiffs, etc.).  See the 
bottom of the program for cells that will assist you in exporting your 
graphics.


TERNARY DIAGRAM
===============

This Mathematica notebook will plot your compositional data 
on a ternary diagram.  Your data can either be input manually while 
the program is running or your data can be read in from an existing 
file.  You can choose to label individual points with a sample name 
which will be displayed when you mouse over the point.  This program 
will read both text files (*.txt) and Excel files (*.xls but NOT 
*.xlsx).  Examine the files, "Ternary Sample Data.txt", "Ternary 
Sample Data.xls", "Ternary Sample Data with Sample Names.txt", and 
"Ternary Sample Data with Sample Names.xls", to determine the 
appropriate file structure (it is easiest to simply modify these files 
and save them with different file names).  You should change the 
column headings as appropriate, however, the column headers can only 
be one-word long (except for the "Sample Name" column which should not 
be changed). While the program is running, you will be prompted to 
choose a percentage contour interval. Within the code itself, there 
are parameters that you may wish to alter to format your plot.  The 
most useful changes are described in comments (i.e., between "(* *)").  

Your plot can either be copied and pasted into other programs, or 
exported as specific types of files (e.g., jpegs, tiffs, etc.).  See 
the bottom of the program for cells that will assist you in exporting 
your graphics.


SECTIONAL DATA THROUGH AN ELLIPSOID
===================================

This Mathematica notebook will graph any ellipsoid for you 
(i.e., an ellipsoid with any axes lengths and orientations).  
Additionally, the notebook can plot planes of any orientation cutting 
through the center of the ellipsoid and graph the resulting elliptical 
sections within that/those plane(s).  The program will prompt you for the 
ellipsoid axes lengths, the trend and plunge of the long axis,  the trend 
of the intermediate axis (unless the plunge of the long axis is zero at 
which point you will be prompted to enter the plunge of the intermediate 
axis and choose between two possible trends) as well as the orientation 
of the plane(s) that will cut through the ellipsoid.  Note that you can 
"grab" any of the ellipsoid images and rotate them into any desired 
viewing orientations.  These images can then be copied and pasted into 
other programs (e.g., Adobe Illustrator).  Also, you can export your 
graphics as specific types of files (e.g. jpegs, tiffs, etc.).  See the 
bottom of the program for cells that will assist you in exporting your 
graphics.

This notebook includes some code for plotting equal area and equal angle 
projections that was modified from code written by Joshua R. Davis.


2D PURE VS SIMPLE SHEAR
=======================

This Mathematica notebook models combinations of two-dimensional pure and 
simple shear.  You can create animations of either simple shear followed 
by pure shear, pure shear followed by simple shear and simultaneous pure 
and simple shear.  You will be prompted to choose between these three 
scenarios and to input the respective strain amounts (in terms of axial 
ratios) while the program is running. 

Your animation can be exported as specific types of files (e.g., animated 
gif or avi).  See the bottom of the program for cells that will assist you 
in exporting your graphics.


Changes associated with version 3.0
=====================================

There are two major changes associated with version 3.0; the addition of 
vorticity programs to the program suite, and the ability to contour equal 
area projections.

The addition of vorticity analysis double the number of strain programs 
within the program suite.  Within each of the vorticity strain programs, 
the three-dimensional strain data is plotted on a on what I am calling a 
“vorticity diagram” (i.e., a diagram of Rxz plotted against theta prime 
[the angle between the long axis of the strain ellipsoid and the mean 
foliation plane] with kinematic vorticity number (Wk) contours)(Tikoff 
& Fossen, 1995). Additionally, the statistical strain programs also 
define a Kernel Density Estimation that is used to determine the error 
region in vorticity-space and the +/- values are calculated for Wk.  In 
addition to the Best Fit Ellipsoid vorticity programs, there are also 
two more programs which can be used to plot multiple sample datasets 
on a single vorticity diagram, one with error regions and one without.  
The vorticity Best Fit Ellipsoid programs no longer support input from 
text files or manual input.  It would be relatively easy to reinstate 
this functionality, but I get the impression that nobody, including 
myself, ever uses this, so it wasn’t worth the time to update that 
part of the code.  However, I didn’t delete the old code, so if one 
was so inclined s/he could update that functionality without too much 
hastle. 

The contouring of equal area projections can be seen in all of the 
statistical Best Fit Ellipsoid programs.  The statistical population of 
long, intermediate, and short principal strain axes is now contoured.  
The Equal Area&Angle Projection program also has the ability to contour 
Equal Area Projections (but NOT Equal Angle Projections). My approach to 
coding the contouring of equal area projections was aided by the book 
“Computational Geosciences with Mathematica” by William Haneberg.  This 
book has been very useful to me throughout my career. 

Another minor change to the programs is that they now can read it “XLSX” 
files from Excel.  Of course, this only works if you are using a version 
of Mathematica that recognizes the “XLSX” format.  Mathematica 7 does 
not, but Mathematica 9 does (I haven’t tested Mathematica 8).

I also added a little bit of code to help with the naming of files when 
they are exported.  All the Best Fit Ellipsoid programs now name the 
exported files with the file that was read into the program to run. I 
used to make my students do this manually for all of the exported files, 
so now they should be happy that the program does it for them. 

I also tried to eradicate the typo “Pricipal” which found its way into 
several places in the code. 

The release of this version was somewhat rushed because of the “Strain 
Programs for Teaching and Research Workshop” at this years’ Structural 
Geology and Tectonics Forum.  I apologize if my haste has generated any 
errors within these programs.  Please report any bugs or problems to me 
at matty.mookerjee@sonoma.edu.  Thanks.




Changes associated with version 2.0
=====================================

In a previous version (1.1), a feature was added to the "Best Fit 
Ellipsoid with Statistics" programs where the axial ratios (Rfs) 
and the angular orientations (phis) used during the Monte Carlo-type
simulation were drawn from a bivariate normal distribution and the 
correlation numbers were determined from the input values of Rfs and
phis.  Unfortunately, this approach leads to a systematic 
underestimations of the Rf values because the Rfs and phis are still
decoupled even though they are correlated.  In this latest version 
(2.0), the Monte Carlo-type simulation draws from a population of the
2x2 matrix components, and thus does not artificially decouple Rf and
phi.  The 2x2 matrices are calculated for each of the input values of
Rf and phi, and a variance-covariance matrix is calculated for the 
three independent components of these matrices.  The variance-
covariance matrix is then utilized to generate the simulation data, 
i.e., the components of the 2x2 matrix, from which Rf and phi are 
calculated and used elsewhere in the program.

The second major change instituted in version 2.0 is graphical in 
nature.  In all previous versions of the program suite, the Flinn and
Hsu diagrams depicted error regions delimited by the plus- and minus- 
values of Octahedral Shear Strain, Lode's Ratio, and Flinn's k-value 
(and in some cases the plus- and minus-values of Rxy and Ryz on for the 
Flinn Diagram).  In this latest version, all of the "Best-Fit Ellipsoid 
with Statistics" programs now have the option of representing this error 
region as an irregular polygon.  This has the obvious benefit of more
accurately representing the actual error region as well as, in 
general, illustrating a significantly smaller error region.  This 
feature is "turned on" by default, but you can switch back to the 
previous error region plotting method by changing the definition of 
"ComplexPolyOrRegularPoly" from being equal to one to being equal to 
zero.  This can be done at the beginning of the code where several/many
variables are defined and accompany some explanatory text in comments
(i.e., between (* *)).

One further minor change in version 2.0 is that a typo was discovered
in the section where the a best fit plane is determined for 
simulation data that do, in fact, approximately lie within a specific
planar orientation.  The seed value for the find minimum function 
had a greater than sign as opposed to a less than sign which in some 
cases made the program determine an inaccurate local minimum.


Changes associated with version 1.15
=====================================
Version 1.15 corrects two minor error and adds one new features.  With 
the addition of the ability to analyze an unlimited number of data 
planes in all of the "Best Fit Ellipsoid" programs in version 1.1, a 
graphical error was introduced.  The elliptical outlines at the plane-
ellipsoid interface were not fully incorporated into the new version; 
specifically, only one ellipse would be plotted.  This has now been 
fixed.  Additionally, the "Sectional Data through an Ellipsoid" 
program would occasionally switch the long and short axes 
orientations.  This program now more effectively determines which
eigenvalues are paired with which eigenvectors.  This new code has 
been added to the "Best Fit Ellipsoid" programs, as well.  The new 
feature involves the equal-area plots of the principal axes in the 
"Sectional Data through an Ellipsoid" and the "Best Fit Ellipsoid" 
programs.  The trend and plunge of the axes now appears when one 
mouses-over one of the points.



Changes associated with version 1.1
=====================================

The main change in version  1.1 is associated with the Best Fit Ellipsoid
programs with statistics.  During the Monte Carlo-type simulation, the 
axial ratios (Rfs) and the angular orientations (phis) are sampled 
randomly from a normal distribution.  Prior to version 1.1, the Rfs and 
the phis were were obtained from two independent normal distributions.  
In version 1.1, these values are obtained from a bivariate normal 
distribution by assembling a variance covariance matrix from the initial 
elliptical data set.  In other words, the correlation is calculated 
between the Rfs and the phis, and this correlation is used generate a 
sample data set that has a similar correlation.  The Rfs and the phis are 
no longer independent of one another as long as the original data set 
shows some amount of correlation. 

Another change to the version 1.1 programs is that all of the "Best Fit 
Ellipsoid" programs as well as the "Sectional Data through an Ellipsoid"
program can now theoretically accommodate and infinite number of planes 
(i.e., they are no longer restricted to 6 planes).  The maximum number 
of planes that I have used to test these programs is 36.  Depending on 
your computer specifications, too many planes may eventually cause your 
computer to crash.

An additional graphic has been added to all of the “Best Fit Ellipsoid” 
programs, an equal area projection of the three principal axes of the 
best fit ellipsoid.  This graphic was also added to the “Sectional Data 
through an Ellipsoid” program along with Hsu and Flinn diagrams.  These 
notebook includes some code for plotting equal area and equal angle 
projections that was modified from code written by Joshua R. Davis.

The format of the exported data file at the end of the “Best Fit 
Ellipsoids” programs has been slightly modified.  Also, the exported 
files at the end of the “Sectional Data through an Ellipsoid” program 
have been modified.



Changes associated with version 1.0.1
=====================================

The biggest change in version 1.0.1 is the addition of several programs: 
"Best Fit Ellipsoid for ImageJ-v_1_0_1.nb"
"Best Fit Ellipsoid-Absolute-v_1_0_1.nb"
"Best Fit Ellipsoid-Absolute For ImageJ-v_1_0_1.nb"
"Best Fit Ellipsoid with Statistics for ImageJ-v_1_0_1.nb"
"Best Fit Ellipsoid with Statistics-Absolute-v_1_0_1.nb"
"Best Fit Ellipsoid with Statistics-Absolute for ImageJ-v_1_0_1.nb"
While these programs do not constitute a major change to the base 
program, they do incorporate two additional features that some users 
may find useful.  These two features are 1) the inclusion of the sign 
convention used by ImageJ, and 2) the ability to determine the absolute 
size of the best fit ellipsoid.  For more details, see above.

Other change:
1) The addition of the “out-of-plane natural strain” (Epsilon-OP) to 
	all “Best Fit” programs.  If one knows the orientation of the 
	regional motion plane, then the natural strain can be calculated 
	in the direction perpendicular to this plane.  The benefit of 
	this approach is that it takes into account both the 	shape 
	and the orientation of the ellipsoid as opposed to both the 
	Flinn and Lodes ratio values which only account for ellipsoid 
	shape.  For instance, 	a plane strain ellipsoid (k=1 and nu=0) 
	oriented with its long axis perpendicular to the thrusting 
	direction does not represent a plane strain deformation. This 
	calculation assumes no volume loss.
2) All “Best Fit” programs now report a “Mean Error” instead of the 
	“Error Index.” The Mean Error is the mean of the absolute values 
	of the differences between the initial data matrix elements and 
	the matrix elements of the fit ellipsoid for all of the data 
	sections.  The lower this value the more compatible the initial 
	data are with an actual ellipsoid. 
3) In all “Best Fit Ellipsoid with Statistics” programs, the program will 
	fit a plane to the data set of ellipsoid axes if the confidence 
	angle is greater than some threshold value (defined as 
	“PlanarFitThreshold” which has a default of 5 degrees, but can be 
	changed at the beginning of the code where various constant are 
	defined) AND the mean difference in the angles between the data 
	set of principal axes and the fit plane is below some threshold 
	value (defined as “MeanDiffThreshold” which has a default of 1 
	degree, and can also be changed at the beginning of the code 
	where the constants are defined).  This is particularly useful 
	for nearly oblate and prolate ellipsoids where there can be a 
	wide range in the orientations of two out of the three principal 
	axes, but where that range defines a plane. In this case, the 
	confidence angle can be deceptively large and fitting the 
	plane to the data can help explain the range in the data. 
4) In all “Best Fit Ellipsoid with Statistics” programs, the working 
	precision of the principal axes vector components was increased.
5) In all “Best Fit Ellipsoid with Statistics” programs the “confidence 
	angle” has been introduced and to some degree has replaced the 
	“alpha confidence” 	estimate.  As mentioned above, the alpha 
	calculations are by default no 	displayed, but “AlphaOn” can be 
	set equal to one in order to show these	error estimates as well.
6) In all “Best Fit Ellipsoid with Statistics” programs a time constrain 
	has been placed on the fitting (default is set at 200 seconds).  
	This is added in case the fitting algorithm gets stuck.  It the 
	time constrain is reached, the loop will break and start over 
	again will another randomly selected set of data.
7) In all “Best Fit” programs, an improvement was made to the way *.xls 
	file were imported.  Excel would sometime import cells that 
	did not have any data in them.  This made it difficult to gage the 
	size of the file in terms of the number of data that the file 
	includes.  These program now ignore these blank cells. 
8) All programs have had their exporting text up dated and now include 
	the option of exporting *.eps files which loose much less 
	resolution than the *.wmf format and is always a vector image.
9) All programs with ellipsoid graphics now have some code at the bottom 
	of the program (among the rest of the exporting graphics code) 
	where the axes labels can be changed and the view point can be 
	quantitatively changed.
10) In all “Best Fit Ellipsoid with Statistics” programs there was some 
	additional code added to deal better deal with horizontal, 
	nearly horizontal, vertical and nearly vertical planes to ensure 
	that the randomly chosen planes and the data within them were 
	consistent with the original data set as well as being 
	consistent with the sign conventions.  This should reduce the 
	confidence intervals for data sets which include planes with 
	these orientations.
11)  The sign convention was off in version 1.0 for perfectly 
	horizontal planes as well as vertical planes with dip direction
	greater than 180 degrees or dipping exactly due north.  This 
	has been corrected in the current version.
12)  Version 1.0 used a uniform distribution to model measurement error 
	associated with the orientation of the data planes.  This has 
	been changed to a normal distribution where the user specifies
	the standard deviation of that distribution. 
13)  Version 1.0 calculated a large standard deviation for phi angles 
	that were nearly 180 degrees apart (e.g. 89 and -89 are only two 
	degrees apart, but the program treated them as if they were 178 
	degrees apart which artificially increased the standard 
	deviation).  In version 1.0.1, this is no longer a problem.



The Legal Stuff:


=====================================================================
Geological Programs for Mathematica is licensed under the MIT License
=====================================================================

Copyright (C) 2010--2012 Matty Mookerjee


================================================================================
Permission is hereby granted, free of charge, to any person obtaining a copy of 
this program suite and associated documentation files (the "Software"), to deal in 
the Software without restriction, including without limitation the rights to use, 
copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the 
Software, and to permit persons to whom the Software is furnished to do so, 
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all 
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
