From 33a1df409560debba3c3423f5e2f0520c04995ac Mon Sep 17 00:00:00 2001 From: "Marco A. Lopez-Sanchez" Date: Mon, 27 Nov 2017 10:25:05 +0100 Subject: [PATCH] release v1.4 changes in documentation and script --- DOCS/Scope.md | 13 +-- DOCS/brief_tutorial.md | 91 ++++++++++++----- DOCS/quick_tutorial.md | 16 +++ DOCS/specifications.md | 110 -------------------- DOCS/tableOfContents.md | 3 +- GrainSizeTools_script.py | 215 ++++++++++++++++++++++++++++++++++----- README.md | 7 +- 7 files changed, 286 insertions(+), 169 deletions(-) delete mode 100644 DOCS/specifications.md diff --git a/DOCS/Scope.md b/DOCS/Scope.md index 75fb153..8c7a6d6 100644 --- a/DOCS/Scope.md +++ b/DOCS/Scope.md @@ -5,7 +5,8 @@ GrainSizeTools (GST) script is primarily targeted at anyone who wants to: 1. Visualize grain size features 2. Obtain a set of single 1D measures of grain size to estimate the magnitude of differential stress (or rate of mechanical work) in dynamically recrystallized rocks or any other type of crystalline aggregate -3. Estimate the actual 3D distribution of grain sizes from a population of apparent grain sizes measured in thin sections. This includes the estimation of the volume occupied by a particular grain size fraction and the shape of the population of grain sizes (assuming that the distribution of grain sizes follows a lognormal distribution) +3. Estimate differential stress via paleopizometers (**New in version 1.4!**) +4. Estimate the actual 3D distribution of grain sizes from a population of apparent grain sizes measured in thin sections. This includes the estimation of the volume occupied by a particular grain size fraction and the shape of the population of grain sizes (assuming that the distribution of grain sizes follows a lognormal distribution) GST script requires as the input the measurement of the areas of the grain profiles (grain-by-grain) in a thin section. Hence, the script does not apply for determining mean grain sizes via the planimetric (Jeffries) (i.e. the number of grains per unit area) or intercept (the number of grains intercepted by a test line per unit length of test line) procedures. The reasons for using grain-by-grain methods over the planimetric/intercept procedures in rocks are detailed in [Lopez-Sanchez and Llana-Fúnez (2015)](http://www.solid-earth.net/6/475/2015/). The following is an overview of the key assumptions to consider so that the results obtained by the script are meaningful and reliable. @@ -15,21 +16,21 @@ GST script requires as the input the measurement of the areas of the grain profi #### Getting unidimensional measures of apparent grain size -Unidimensional apparent grain size measures such as the **mean** or **median** are only meaningful in specimens that show a **unimodal distribution of diameters** (or areas). Consequently, in all cases it is key to visualize the distribution of apparent grain sizes and **observe if the distribution is unimodal** (a single peak). In the case that the distribution is multimodal (two or more peaks), you can use for comparative purposes the modal interval or, better, the **location of frequency peaks** based on the Kernel density estimate [(Lopez-Sanchez and Llana-Fúnez, 2015)](http://www.solid-earth.net/6/475/2015/). Despite this, the best option when a multimodal grain size distribution occurs is to separate the different populations of grain size previously via image analysis methods. Unfortunately, no general protocol exist in the earth science community for unidimensional grain size measures. Consequently, if possible, it is advisable to always report all the different unidimensional grain size measures (mean, median, freq. peak). This will allow other scientists to compare their data with yours directly when using a different type of grain size measurement from that used in your study. +Unidimensional apparent grain size measures such as the **mean** or **median** are only meaningful in specimens that show a **unimodal distribution of diameters** (or areas). Consequently, in all cases it is key to visualize the distribution of apparent grain sizes and **observe if the distribution is unimodal** (a single peak). In the case that the distribution is multimodal (two or more peaks), you can use for comparative purposes the modal interval or, better, the **location of frequency peaks** based on the Kernel density estimate [(Lopez-Sanchez and Llana-Fúnez, 2015)](http://www.solid-earth.net/6/475/2015/). Despite this, the best option when a multimodal grain size distribution occurs is to separate the different populations of grain size previously via image analysis methods. Unfortunately, no general protocol exists in the earth science community for unidimensional grain size measures. Consequently, if possible, it is advisable to always report all the different unidimensional grain size measures (mean, median, freq. peak). This will allow other scientists to compare their data with yours directly when using a different type of grain size measurement from that used in your study. When we estimate unimodal grain size measures from a **single section**, whatever the number of grain boundary maps used, the results will be only meaningful if grains are equant (equiaxed) or near-equant (i.e. aspect ratios mostly < 2.0). If grains systematically show aspect ratios above 2.0 and a shape preferred orientation of their large axes throughout the rock volume, you will need to **estimate the grain size over three orthogonal sections and then averaged the results**. Although specimens with equant grains accept any orientation to obtain a unidimensional grain size measure, it is advisable to use a principal section. Specifically, we promote the use of the XZ section, i.e. parallel to the lineation and perpendicular to the foliation, since this will allow us: (i) to visualize and measure whether the grains are far from equant via the aspect ratio; and (ii) to provide a fairer comparison between different specimens when near-equant grains and preferred orientation of the large axes exist. -A common way to estimate a **confidence interval** of your grain size measurement is to take several representative micrographs from the same specimen (three or more) and then estimate the mean and the variation in the results reporting the standard deviation (SD) at a 2-sigma level of confidence, i.e. the confidence interval will be the mean ± two times the SD. To minimize variations in the results due to an insufficient number of grain measurements, a minimum of 433 (2-sigma) or 965 (3-sigma) grain areas is required for each grain boundary map (see [Lopez-Sanchez and Llana-Fúnez, 2015)](http://www.solid-earth.net/6/475/2015/) for details). +A common way to estimate a **confidence interval** of your grain size measurement is to take several representative micrographs from the same specimen (three or more) and then estimate the mean and the variation in the results reporting the standard deviation (SD) at a 2-sigma level of confidence, i.e. the confidence interval will be the mean ± two times the SD. To minimize variations in the results due to an insufficient number of grain measurements, a minimum of 433 (although use better 965) is required for each grain boundary map (see [Lopez-Sanchez and Llana-Fúnez, 2015)](http://www.solid-earth.net/6/475/2015/) for details). -For paleopizometry/paleowattmetry studies **do not report measures derived from distributions estimated via stereological methods but apparent grain size measures**. The reasoning behind this is that stereological methods are built on several (weak) geometric assumptions and the results will always be, at best, only approximate. This means that the precision of the estimated 3D size distribution is **much poorer** than the precision of the original distribution of grain profiles since the latter is based on real data. Lastly, when using a piezometer relation is of paramount importance to ensure what type of grain size measure should be used. For example, if you want to use the piezometric relation established for quartz in Stipp and Tullis (2003), note that they have been established using the **root mean square diameter** not the *linear or the logarithmic mean diameter*. +For paleopizometry/wattmetry studies **do not report measures derived from distributions estimated via stereological methods but apparent grain size measures**. The reasoning behind this is that stereological methods are built on several (weak) geometric assumptions and the results will always be, at best, only approximate. This means that the precision of the estimated 3D size distribution is **much poorer** than the precision of the original distribution of grain profiles since the latter is based on real data. Lastly, when using a piezometer relation is of paramount importance to ensure what type of grain size measure should be used. For example, if you want to use the piezometric relation established for quartz in Stipp and Tullis (2003), note that they have been established using the **root mean square apparent diameter** not the *linear nor the logarithmic mean diameter*. For details see the step-by-step tutorial. #### Getting the shape of actual grain size distribution or the volume occupied by a particular grain size fraction Estimating the actual grain size distribution from thin sections using stereological methods requires spatial homogeneity and that **grains under study are equant or near-equant**. The Saltykov and two-step methods will not provide reliable results if most of the grains show aspect ratios above 2.0, regardless of whether a shape preference orientation exists or not. In any event, this assumption is acceptable most of the time for some of the most common dynamically recrystallized non-tabular grains in crustal and mantle shear zones, such as quartz, feldspar, olivine and calcite, as well as in ice or metals/alloys. However, be careful when recrystallized grains show very irregular/lobate grain boundaries (i.e. the main recrystallization mechanism was "fast" grain boundary migration). -The Saltykov method is suitable to estimate the volume of a particular grain fraction of interest (in percentage) and to visualize the aspect of the derived 3D grain size distribution using the histogram and a volume-weighted cumulative frequency curve. To provide reliable results, the method requires using a few number of classes and a large number of individual grain measurements. *Practical experience* indicates using more than 1000 grains and less than 20 classes. The number of classes has to be set by a trial and error approach. This will inevitably leads to different authors using different number of classes across studies. Due to this, when estimating the volume of a grain size fraction based on a single grain boundary map it is neccesary to take an absolute error of ± 5 to stay safe (see details in [Lopez-Sanchez and Llana-Fúnez, 2016](http://www.sciencedirect.com/science/article/pii/S0191814116301778)). If possible, take more than one representative grain boundary map and then estimate a confidence interval as explained above in this section. +The Saltykov method is suitable to estimate the volume of a particular grain fraction of interest (in percentage) and to visualize the aspect of the derived 3D grain size distribution using the histogram and a volume-weighted cumulative frequency curve. To provide reliable results, the method requires using a few number of classes and a large number of individual grain measurements. *Practical experience* indicates using more than 1000 grains and less than 20 classes. The number of classes has to be set by a trial and error approach. This will inevitably lead to different authors using a different number of classes across studies. Due to this, when estimating the volume of a grain size fraction based on a single grain boundary map it is necessary to take an absolute error of ± 5 to stay safe (see details in [Lopez-Sanchez and Llana-Fúnez, 2016](http://www.sciencedirect.com/science/article/pii/S0191814116301778)). If possible, take more than one representative grain boundary map and then estimate a confidence interval as explained above in this section. -The two-step method ([Lopez-Sanchez and Llana-Fúnez, 2016](http://www.sciencedirect.com/science/article/pii/S0191814116301778)) is suitable for describing quantitatively the shape of the actual 3D grain size distribution using a single parameter; the multiplicative standard deviation (MSD) value. The method also provides a reliable uncertainty value. The method assume that the actual grain size distribution follows a lognormal distribution, **there is therefore critical to visualize the distribution using the Saltykov method first and ensure that the distribution is unimodal and lognormal-like**. The MSD estimate is independent of the chosen number of classes as long as the Saltykov method produces stable results (i.e. you do not lose the lognormal appearance of the distribution due to the use of an excessive number of classes). +The two-step method ([Lopez-Sanchez and Llana-Fúnez, 2016](http://www.sciencedirect.com/science/article/pii/S0191814116301778)) is suitable for describing quantitatively the shape of the actual 3D grain size distribution using a single parameter; the multiplicative standard deviation (MSD) value. The method also provides a reliable uncertainty value. The method assumes that the actual grain size distribution follows a lognormal distribution, **there is therefore critical to visualize the distribution using the Saltykov method first and ensure that the distribution is unimodal and lognormal-like**. The MSD estimate is independent of the chosen number of classes as long as the Saltykov method produces stable results (i.e. you do not lose the lognormal appearance of the distribution due to the use of an excessive number of classes). [next section](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/brief_tutorial.md) diff --git a/DOCS/brief_tutorial.md b/DOCS/brief_tutorial.md index c62c731..a178e13 100644 --- a/DOCS/brief_tutorial.md +++ b/DOCS/brief_tutorial.md @@ -2,11 +2,11 @@ ------------- > **Important note:** -> Please, **update as soon as possible to version 1.3.x**, it contains important changes that are not fully compatible with previous versions. It is also advisable to **update the plotting library matplotlib to version 2.x** since the plots are optimized for such version. +> Please, **update as soon as possible to version 1.4**. It is also advisable to **update the plotting library matplotlib to version 2.x** since the plots are optimized for such version. ### *Open and running the script* -First of all, make sure you have the required software and necessary Python libraries installed (see [requirements](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/Requirements.md) for details), and that you downloaded the latest version of the GrainSizeTools script (currently the v1.3.2). If this is the case, then you need to open the script in a integrated development environment (IDE) to interact with it (Fig. 1). For this, open the Canopy editor -if you installed the Enthought package- or the Spyder IDE -if you installed the Anaconda package-, and open the GrainSizeTools script using ```File>Open```. The script will appear in the editor as shown in figure 1. +First of all, make sure you have the required software and necessary Python libraries installed (see [requirements](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/Requirements.md) for details), and that you downloaded the latest version of the GrainSizeTools script (currently the v1.4). If this is the case, then you need to open the script in a integrated development environment (IDE) to interact with it (Fig. 1). For this, open the Canopy editor -if you installed the Enthought package- or the Spyder IDE -if you installed the Anaconda package-, and open the GrainSizeTools script using ```File>Open```. The script will appear in the editor as shown in figure 1. ![Figure 1. The Python editor and the shell in the Enthought Canopy environment](https://raw.githubusercontent.com/marcoalopez/GrainSizeTools/master/FIGURES/IDEs.png) *Figure 1. The editor and the Python shell (a.k.a. the console) in the the Spyder integrated development environment (IDE). The Enthough Canopy and the Spyder IDEs are both MATLAB-like IDEs optimized for numerical computing and data analysis using Python. They also provide a file explorer, a variable explorer, or a history log among other interesting features.* @@ -18,26 +18,46 @@ To use the script it is necessary to run it. To do this, just click on the green The following text will appear in the shell/console (Fig. 1): ``` -#======================================================================================# -# # -# Welcome to GrainSizeTools script v1.3.4 # -# # -# The following methods are available: # -# # -# extract_areas # extract the areas of the grains from a text file # -# calc_diameters # calculate the diameter via the equivalent circular diameter # -# find_grain_size # estimate and visualize different apparent grain size measures # -# derive3D # estimate the actual (3D) grain size via steorology methods # -# # -# You can get information on the different methods by: # -# # -# (1) Typing help(name of the method) in the console. e.g. >>> help(derive3D) # -# # -# (2) In Spyder IDE by writing the name of the method and clicking Ctrl + I # -# # -# (3) Visit the documentation at https://marcoalopez.github.io/GrainSizeTools/ # -# # -#======================================================================================# +====================================================================================== +Welcome to GrainSizeTools script v1.4 +====================================================================================== + +GrainSizeTools is a free open-source cross-platform script to visualize and characterize +the grain size in polycrystalline materials from thin sections and estimate differential +stresses via paleopizometers. + +METHODS AVAILABLE +----------------- +================== ================================================================== +Function Description +================== ================================================================== +extract_areas Extract the areas of the grains from a text file +calc_diameters Calculate the diameter via the equivalent circular diameter +find_grain_size Estimate different apparent grain size measures and visualize populations +derive3D Estimate the actual grain size distribution via steorology methods +quartz_piezometer Estimate the differential stress for quartz using piezometers +olivine_piezometer (not yet implemented, available soon) +================== ================================================================== + +You can get information on the different methods by: + (1) Typing help(name of the method) in the console. e.g. >>> help(derive3D) + (2) In the Spyder IDE by writing the name of the method and clicking Ctrl + I + (3) Visit script documentation at https://marcoalopez.github.io/GrainSizeTools/ + + +EXAMPLES +-------- +Extracting data using the automatic mode: +>>> areas = extract_areas() + +Estimating the equivalent circular diameters: +>>> diameters = calc_diameters(areas) + +Estimate and visualize different apparent grain size measures in square root scale +>>> find_grain_size(areas, diameters, form='sqrt') + +Estimating differential stress using the paleopiezometric relations +>>> quartz_piezometer(grain_size=9.7, form='Stipp') ``` Once you see this text, all the tools implemented in the GrainSizeTools script will be available by typing some commands in the shell as will be explained below. @@ -169,7 +189,7 @@ This example means that for each apparent diameter calculated from the sectional Once we estimated and stored the apparent grain sizes, we have several choices: (1) estimate an unidimensional value of grain size for paleopiezometry/paleowattmetry studies, or (2) derive the actual 3D grain size distribution from the population of apparent grain sizes using the Saltykov method (Saltykov, 1967; Sahagian and Proussevitch, 1998) or an extension of the Saltykov method named the two-step method (Lopez-Sanchez and Llana-Fúnez, 2016). -#### *Obtaining an unidimensional value of grain size (paleopiezo/wattmetry studies)* +#### *Obtaining an unidimensional value of grain size* For this, we need to call the function ```find_grain_size```. This function returns several grain size measures and plots, depending on your needs. The default mode returns a frequency *vs* apparent grain size plot together with the mean, median, and frequency peak grain sizes; the latter using a Gaussian kernel density estimator (see details in [Lopez-Sanchez and Llana-Fúnez 2015](http://www.solid-earth.net/6/475/2015/se-6-475-2015.html)). Other parameters of interest are also provided, such as the bin size, the number of classes, the method used to estimate the bin size, and the bandwidth used for the Gaussian kde according to the Silverman rule (Silverman 1986). As stated in [Lopez-Sanchez and Llana-Fúnez 2015](http://www.solid-earth.net/6/475/2015/se-6-475-2015.html), **to obtain consistent results a minimum of 433 measured grain profiles are required** (error < 4% at a 95% confidence), although we recommend to measure a minimum of 965 when possible (99% confidence). @@ -224,6 +244,29 @@ The user-defined bin size can be any number of type integer or float (*i.e.* an ![Figure 6. apparent grain size vs frequency plots](https://raw.githubusercontent.com/marcoalopez/GrainSizeTools/master/FIGURES/figure_1.png) *Figure 6. Different apparent grain size vs frequency plots of the same population returned by the find_grain_size function. These include the number- (linear) and area-weighted plots (upper part) and the logarithmic and square root apparent grain sizes (lower part)* +#### *Estimating differential stress using piezometric relations (paleopiezometry)* + +Currently, the script includes a function for estimating differential stress from the apparent grain size in quartz (new phases, such as olivine, calcite, ice, etc., will be added soon). The function requires entering the apparent grain size ***in microns*** and the piezometric relation to be used as follows: +```python +>>> quartz_piezometer(grain_size=5.7, 'Stipp') + +differential stress = 169.16 MPa +``` +The ```quartz_piezometer``` function includes the following piezometric relations: + +- ```'Stipp'``` from Stipp and Tullis (2003), used as default +- ```'Holyoke'``` with uses the Stipp and Tullis (2003) piezometer corrected by Holyoke and Kronenberg (2010) +- ```'Shimizu'``` from Shimizu (2008) +- ```'Cross'``` and ```'Cross2'``` from Cross et al. (2017), the preferred option for grains reconstructed from ebsd data +- ```'Twiss'``` from Twiss (1977) + +It is key to note that different paleopiezometers require entering **different types of apparent grain sizes** to properly estimate differential stress values. For example, the piezometer relations of Stipp and Tullis (2003), Holyoke and Kronenberg (2010), and Cross et al. (2017) requires entering the grain size as *the root mean square grain size from equivalent circular diameters with no stereological correction* (i.e. mean sqrt apparent grain size). In contrast, Shimizu (2008) paleopizometer requires to enter the *logarithmic median apparent grain size from equivalent circular diameters with no stereological correction* and provide the temperature in K during deformation (the script will ask you for this value). Regarding the Twiss (1977) paleopiezometer, originally calibrated using linear intercepts, the script requires entering the grain size as *the logarithmic mean apparent grain size from equivalent circular diameters with no stereological correction*; the script will convert this value to linear intercepts. For more details write in the shell: + +```python +>>> help(quartz_piezometer) +``` +and read the assumptions made. + #### *Derive the actual 3D distribution of grain sizes from thin sections* The function responsible to unfold the distribution of apparent grain sizes into the actual 3D grain size distribution is named ```derive3D```. The script implements two methods to do this, the Saltykov and the two-step methods. The Saltykov method is the best option for exploring the dataset and for estimating the volume of a particular grain size fraction. The two-step method is suitable to describe quantitatively the shape of the grain size distribution assuming that they follow a lognormal distribution. This means that the two-step method only yield consistent results when the population of grains considered are completely recrystallized or when the non-recrystallized grains can be previously discarded using shape descriptors or any other relevant paramater such as the density of dislocations. It is therefore necessary to check first whether the linear distribution of grain sizes is unimodal and lognormal-like (i.e. skewed to the right as in the example shown in figure 7). For more details see [Lopez-Sanchez and Llana-Fúnez (2016)](http://www.sciencedirect.com/science/article/pii/S0191814116301778). @@ -373,7 +416,7 @@ If you need to load a large number of datasets, you probably prefer not having t When you run the script for the first time, your current working directory will appear in the Python shell. Also, you can retrieve your current working directory at any time by typing in the shell ```os.getcwd()```, as well as to modify it to another path using the function ```os.chdir('new default path')```. The same rules apply when using the ```np.genfromtxt``` method. -> Note: usually the current working directory is the same directory where the script is located (although this depends on the Python environment you have installed). Hence, in general it is a good idea to locate the scrip in the same directory where the datasets are located. +> Note: usually the current working directory is the same directory where the script is located (although this depends on the Python environment you have installed). Hence, sometimes it is a good idea to locate the scrip in the same directory where the datasets are located. [next section](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/quick_tutorial.md) [table of contents](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/tableOfContents.md) diff --git a/DOCS/quick_tutorial.md b/DOCS/quick_tutorial.md index 659a8b9..90fe8ff 100644 --- a/DOCS/quick_tutorial.md +++ b/DOCS/quick_tutorial.md @@ -73,6 +73,22 @@ derive3D(diameters, numbins=12, set_limit=None, fit=True) # The script will ask you about the new guessing values derive3D(diameters, numbins=12, set_limit=None, fit=True, initial_guess=True) ``` + +#### *Estimate differential stresses using paleopizometers* + +```python +# Estimate differential stress using quartz and the piezometric +# relation of Stipp and Tullis (2003) +quartz_piezometer(grain_size=9.0, 'Stipp') + +# Estimate differential stress using olivine and the piezometric +# relation of...(AVAILABLE SOON) +olivine_piezometer(grain_size=9.0, 'Karato') + +# Estimate differential stress in other mineral/materials (calcite, +# ice, alloys, etc.) (AVAILABLE SOON) +other_piezometer(grain_size=9.0, 'calcite_Rutter') +``` [next section](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/specifications.md) [table of contents](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/tableOfContents.md) diff --git a/DOCS/specifications.md b/DOCS/specifications.md deleted file mode 100644 index 017783d..0000000 --- a/DOCS/specifications.md +++ /dev/null @@ -1,110 +0,0 @@ -Specifications of main functions in the GrainSizeTools script -------------- - -#### **extract_areas** (*filePath='auto', col_name='Area'*) -Extract the data corresponding to the areas of grain profiles from the -tabular-like text data generated by the ImageJ application. - -> **Inputs:** -> -> ***filePath***: *string* -> the file location in the OS in quotes. If 'auto' (the default) the function -> will ask you for the location of the file through a file selection dialog. -> ->***col_name***: *string; optional* -> The name of the column that contains the areas of the grain profiles. -> It is set to 'Area' by default. -> -> **Returns**: -> A numpy array with the areas of the grain profiles. - -#### **calc_diameters** (*areas, correct_diameter=0*) -Calculate the diameters from the sectional areas via the equivalent circular diameter. - -> **Inputs:** -> -> ***areas***: *array_like* -> A numpy array with the sectional areas of the grains -> -> ***correct_diameter***: *integer or float; optional* -> Correct the diameters estimated from the areas of the grains by adding the -the width of the grain boundaries. If correct_diameter is not declared, it -is considered 0. - ->**Returns**: -> A numpy array with the diameters of the grains. - -#### **find_grain_size** (*areas, diameters, plot='lin', binsize='auto'*) -Estimate different 1D measures of grain size from a population of apparent diameters -and their areas. It includes the mean, the area-weighted mean, the median and the -frequency peak grain sizes. - -> **Inputs:** -> -> ***areas***: *array_like* -> A numpy array with the areas of the grain profiles -> -> ***diameters***: *array_like* -> A numpy array with the apparent diameters of the grains -> -> ***plot***: *string; optional* -> the preferred type of plot and grain size estimation. This can be 'lin' for a -linear frequency vs diameter plot, 'log' for a frequency vs logarithmic diameter -plot, 'sqrt' for a frequency vs square root diameter plot, and 'area' for a -area-weighted frequency vs diameter plot. -> -> ***binsize***: *string, integer or float; optional* -> the method used to calculate the bin size. This can be 'auto', 'fd' (Freedman-Diaconis -rule), 'doane' (Doane's rule), 'scott' (Scott rule), 'sturges' (Sturge's rule), or a scalar -of type integer or float. If not specified, the 'auto' rule is used by default. -> ->**Returns**: -> A number of 1D grain size values to use in paleopiezometry (or paleowattmetry) studies and the chosen plot. The values includes the mean, the median, the area-weighted mean and the frequency peak via the Gaussian kernel density estimator grain sizes. It also provides other values of interest such as the bin size and bandwidth estimated as well as the methods chosen. - -#### **derive3D** (*diameters, numbins=10, set_limit=None, fit=False, initial_guess=False*) ->Estimates the actual distribution of grain size from the population of -apparent diameters measured in a thin section using two approaches: - ->i) the Saltykov method (Saltykov 1967; Sahagian and Proussevitch 1998) -ii) the two-step method (Lopez-Sanchez and Llana-Funez, 2016). - ->The Saltykov method is optimal to estimate the volume of a particular grain size -fraction as well as to obtain a qualitative view of the appearance of the actual -3D grain size population, either in uni- or multimodal populations. - ->The two-step method is aimed at estimating quantitatively the shape of the -actual 3D distribution of grain sizes. The method only works properly for -unimodal lognormal-like grain size populations (i.e. completely recrystallized -rocks) and returns the MSD (i.e. shape) and median (i.e. scale) values that -describe the lognormal population of grain sizes at their lineal scale. For -details see Lopez-Sanchez and Llana-Funez (2016). - -> **Inputs:** -> -> ***diameters***: *array_like* -> A numpy array or Python list with the apparent diameters of the grains. -> -> ***numbins***: *integer; optional* -> The number of bins/classes of the histrogram. If not declared, is set to 10 by -default. An integer. -> -> ***set_limit***: *integer or float; optional* -> If the user defines a number, the script will return the volume occupied by the -grain fraction of size less than or equal to that value. An integer or float. -> -> ***fit***: *True or False* -> If False, the standard Saltykov method is applied. If True, the two-step method -is applied. -> ->***initial_guess***: *True or False* -> If False, the script will use the default guessing values to fit the lognormal -distribution. If True, the script will ask the user to define the MSD and -median guessing values. -> ->**Returns**: -> In the case of the Saltykov method: The bin size, the frequencies (probabilities) of the different classes and a plot containing two subplots: i) the distribution of the actual grain size population according to the Saltykov method and ii) the volume-weighted cumulative distribution. The frequencies are normalized such that the integral over the range is one. Note that the sum of these values will not be equal to one unless bins of unity width are chosen. In the case of the two-step method: The optimal MSD (shape) and median (scale) values and the precision of the estimation at a 3-sigma level. Also a plot containing the unfolded population using the Saltykov method and the fitted lognormal probability density function with a trust region. - -[next section](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/imageJ_tutorial.md) -[table of contents](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/imageJ_tutorial.md) - ----------- diff --git a/DOCS/tableOfContents.md b/DOCS/tableOfContents.md index c8f450e..ebd684f 100644 --- a/DOCS/tableOfContents.md +++ b/DOCS/tableOfContents.md @@ -9,7 +9,8 @@ Table of contents * [Using the script to visualize and estimate the grain size](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/brief_tutorial.md#using-the-script-to-visualize-and-estimate-the-grain-size-features) * [Loading the data and extracting the areas of the grain profiles](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/brief_tutorial.md#loading-the-data-and-extracting-the-areas-of-the-grain-profiles) * [Estimating the apparent diameters from the areas of the grain profiles](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/brief_tutorial.md#estimating-the-apparent-diameters-from-the-areas-of-the-grain-profiles) - * [Obtaining an unidimensional value of grain size (paleopiezo/wattmetry studies)](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/brief_tutorial.md#obtaining-an-unidimensional-value-of-grain-size-paleopiezowattmetry-studies) + * [Obtaining an unidimensional value of grain size](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/brief_tutorial.md#obtaining-an-unidimensional-value-of-grain-size-paleopiezowattmetry-studies) + * [Estimating differential stress using piezometric relations (paleopiezometry)]() * [Derive the actual 3D distribution of grain sizes from thin sections](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/brief_tutorial.md#derive-the-actual-3d-distribution-of-grain-sizes-from-thin-sections) * [Comparing different grain size populations using box plots](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/brief_tutorial.md#comparing-different-grain-size-populations-using-box-plots) * [Other methods of interest](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/brief_tutorial.md#general-methods-of-interest) diff --git a/GrainSizeTools_script.py b/GrainSizeTools_script.py index 4c0539b..333ecb3 100644 --- a/GrainSizeTools_script.py +++ b/GrainSizeTools_script.py @@ -17,7 +17,7 @@ # See the License for the specific language governing permissions and # # limitations under the License. # # # -# Version 1.3.4 # +# Version 1.4 # # For details see: http://marcoalopez.github.io/GrainSizeTools/ # # download at https://github.com/marcoalopez/GrainSizeTools/releases # # # @@ -224,9 +224,9 @@ def derive3D(diameters, numbins=10, set_limit=None, fit=False, initial_guess=Fal References ---------- - | Saltykov SA (1967) doi:10.1007/978-3-642-88260-9_3 - | Sahagian and Proussevitch (1998) J. Vol. Geotherm. Res. doi:10.1029/95JB0250 - | Lopez-Sanchez and Llana-Funez (2016) J. Struc. Geol. doi:10.1016/j.jsg.2016.10.00 + | Saltykov SA (1967) http://doi.org/10.1007/978-3-642-88260-9_31 + | Sahagian and Proussevitch (1998) https://doi.org/10.1016/S0377-0273(98)00043-2 + | Lopez-Sanchez and Llana-Funez (2016) https://doi.org/10.1016/j.jsg.2016.10.008 Parameters ---------- @@ -366,6 +366,150 @@ def derive3D(diameters, numbins=10, set_limit=None, fit=False, initial_guess=Fal return None +def quartz_piezometer(grain_size, form='Stipp'): + """ Apply different quartz piezometric relations to estimate the differential + stress from 1D apparent grain sizes. The piezometric relations has the + following expression: + + diff_stress = B * grain_size**-p + + where diff_stress is the differential stress in [MPa], B is an experimentally + derived parameter in [MPa micron**p], grain_size is the aparent grain size + in [microns], and p is an experimentally derived exponent which is adimensonal. + + Parameters + ---------- + grain_size: positive integer or float + the apparent grain size in microns + + form: string + the piezometric relation, either: + | 'Cross' and 'Cross2' from Cross et al. (2017) + | 'Holyoke' from Holyoke and Kronenberg (2010) (Stipp and Tullis corrected) + | 'Shimizu' from Shimizu (2008) + | 'Stipp' from Stipp and Tullis (2003) + | 'Twiss' from Twiss (1977) + + References + ---------- + Cross et al. (2017) https://doi.org/10.1002/2017GL073836 + De Hoff and Rhines (1968) Quantitative Microscopy. Mcgraw-Hill. New York. + Holyoke and Kronenberg (2010) https://doi.org/10.1016/j.tecto.2010.08.001 + Shimizu (2008) https://doi.org/10.1016/j.jsg.2008.03.004 + Stipp and Tullis (2003) https://doi.org/10.1029/2003GL018444 + + Assumptions + ----------- + - Independence of temperature (excepting Shimizu's piezometer), total strain, + flow stress, and water content. + + - Recrystallized grains are equidimensional or close to equidimensional. + + - The piezometer relations of Stipp and Tullis (2003), Holyoke and Kronenberg (2010), + and Cross et al. (2007) requires entering the grain size as the root mean square + apparent grain size calculated using equivalent circular diameters with no + stereological correction. + + - The piezometer relation of Shimizu (2008) requires entering the grain size + as the logarithmic median apparent grain size calculated using equivalent + circular diameters with no stereological correction. + + - The piezometer of Twiss (1977) requires entering the logarithmic mean apparent + grain size calculated from equivalent circular diameters (ECD) with no stereological + correction. The function will convert this value to the mean linear intercept (LI) + grain size using the De Hoff and Rhines (1968) empirical relation LI = ECD / sqrt(4/pi) + and assuming that LI was originally multiplied by 1.5 (correction factor). Then the + final relation would be: LI = (1.5 / sqrt(4/pi)) * ECD + + Returns + ------- + The differential stress in MPa, a floating point number + """ + + if form == 'Stipp': + B = 669.0 + p = 0.79 + + elif form == 'Holyoke': + B = 490.3 + p = 0.79 + + elif form == 'Cross': + B = 593.0 + p = 0.71 + + elif form == 'Cross2': + B = 450.9 + p = 0.63 + + elif form == 'Shimizu': + B = 349.9 + p = 0.8 + T = float(input("Shimizu's paleopiezometer requires setting the temperature [in K] during deformation: ")) + + diff_stress = 352 * grain_size**(-0.8) * exp(698 / T) + + print(' ') + print('differential stress =', round(diff_stress, 2), 'MPa') + return None + + elif form == 'Twiss': + B = 603.1 # Recalculated from Twiss (1977) using [5.5 * (1000**0.68)] (Note: B is 5.5 when grain size (d) is in mm) + p = 0.68 + grain_size = (1.5 / (np.sqrt(4 / np.pi))) * grain_size # convert ECD to LI + + else: + print('Wrong from. Please choose between valid forms') + return None + + diff_stress = B * grain_size**-p + + print(' ') + print('differential stress =', round(diff_stress, 2), 'MPa') + return None + + +def olivine_piezometer(grain_size, form='Karato'): + """ Apply different olivine piezometric relations to estimate the differential + stress from 1D apparent grain sizes. The piezometric relations has the + following expression: + + diff_stress = B * grain_size**-p + + where diff_stress is the differential stress in [MPa], B is an experimentally + derived parameter in [MPa micron**p], grain_size is the aparent grain size + in [microns], and p is an experimentally derived exponent which is adimensonal. + + Parameters + ---------- + grain_size: positive integer or float + the apparent grain size in microns + + form: string + the piezometric relation, either: + | 'Karato_dry' from Karato et al. (1980) + | TODO + | TODO + + + References + ---------- + TODO + + Assumptions + ----------- + - Independence of temperature, total strain, flow stress, and water content. + + - TODO + + Returns + ------- + The differential stress in MPa, a floating point number + """ + + pass + + # ============================================================================ # # Functions used by the find_grain_size and the derive3D functions to generate # # the plots using the matplotlib capabilities. I use hex color codes to define # @@ -886,8 +1030,7 @@ def Saltykov(freq, bin_edges, binsize, mid_points, normalize=True): if normalize is True: freq = np.clip(freq, 0., 2**20) # replacing negative values with zero freq_norm = freq / sum(freq) # normalize to one - # normalize such that the integral over the range is one - freq_norm = freq_norm / binsize + freq_norm = freq_norm / binsize # normalize such that the integral over the range is one return freq_norm else: @@ -920,26 +1063,46 @@ def fit_function(x, shape, scale): texto = """ -#======================================================================================# -# # -# Welcome to GrainSizeTools script v1.3.4 # -# # -# The following methods are available: # -# # -# extract_areas # extract the areas of the grains from a text file # -# calc_diameters # calculate the diameter via the equivalent circular diameter # -# find_grain_size # estimate and visualize different apparent grain size measures # -# derive3D # estimate the actual (3D) grain size via steorology methods # -# # -# You can get information on the different methods by: # -# # -# (1) Typing help(name of the method) in the console. e.g. >>> help(derive3D) # -# # -# (2) In Spyder IDE by writing the name of the method and clicking Ctrl + I # -# # -# (3) Visit the documentation at https://marcoalopez.github.io/GrainSizeTools/ # -# # -#======================================================================================# +====================================================================================== +Welcome to GrainSizeTools script v1.4 +====================================================================================== + +GrainSizeTools is a free open-source cross-platform script to visualize and characterize +the grain size in polycrystalline materials from thin sections and estimate differential +stresses via paleopizometers. + +METHODS AVAILABLE +----------------- +================== ================================================================== +Function Description +================== ================================================================== +extract_areas Extract the areas of the grains from a text file +calc_diameters Calculate the diameter via the equivalent circular diameter +find_grain_size Estimate different apparent grain size measures and visualize populations +derive3D Estimate the actual grain size distribution via steorology methods +quartz_piezometer Estimate the differential stress for quartz using piezometers +olivine_piezometer (not yet implemented, available soon) +================== ================================================================== + +You can get information on the different methods by: + (1) Typing help(name of the function) in the console. e.g. >>> help(derive3D) + (2) In the Spyder IDE by writing the name of the function and clicking Ctrl + I + (3) Visit script documentation at https://marcoalopez.github.io/GrainSizeTools/ + + +EXAMPLES +-------- +Extracting data using the automatic mode: +>>> areas = extract_areas() + +Estimating the equivalent circular diameters: +>>> diameters = calc_diameters(areas) + +Estimate and visualize different apparent grain size measures in square root scale +>>> find_grain_size(areas, diameters, form='sqrt') + +Estimating differential stress using the paleopiezometric relations +>>> quartz_piezometer(grain_size=5.7, form='Stipp') """ print(texto) diff --git a/README.md b/README.md index a67c4e4..a39adae 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,11 @@ ![](https://raw.githubusercontent.com/marcoalopez/GrainSizeTools/master/FIGURES/new_header.png) -*This project is maintained by [Marco A. Lopez-Sanchez](https://marcoalopez.github.io/) - Last update (website): 2017/10/18* +*This project is maintained by [Marco A. Lopez-Sanchez](https://marcoalopez.github.io/) - Last update (website): 2017/11/27* [GrainSizeTools script](http://marcoalopez.github.io/GrainSizeTools/) is a free open-source cross-platform script written in [Python](https://www.python.org/) that provides several tools to visualize and characterize the grain size in polycrystalline materials from thin sections. The script is suitable to use for paleopiezometry (paleowattmetry) studies and to derive the actual 3D grain size distribution using the Saltykov and the two-step methods. The script **does not require a previous experience with Python programming language** (see [documentation](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/tableOfContents.md) or [FAQ](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/FAQ.md)). For users with coding skills, the script is organized in a modular way using Python functions, which facilitates to modify, reuse or extend the code if needed. +**Last release 2017/10/27, v1.4: Now includes the ability to estimate differential stresses via paleopiezometers! ** (including multiple paleopiezometric relations for comparison) + ## Features at a glance - Load and extract data from txt and csv files generated by the ImageJ or any other application. @@ -12,11 +14,12 @@ - It implements several algorithms to estimate the optimal bin size of histograms and the optimal bandwidth of the Gaussian KDE based on the population features. - Derive the actual 3D grain size distribution from thin sections (2D data) using the Saltykov method, including to get an estimation of the volume of a particular grain size fraction. - Estimate the shape of the 3D grain size distribution using the two-step method and a single parameter (the MSD). +- Estimate differential stresses via paleopiezometers (**New!**) - It produces different ready-to-publish plots, allowing to save the graphical output as a bitmap or vector images (see the image above for examples). ## Download -You can download the script at the following sites (**Last release 2017/10/18, v1.3.4**): +You can download the script at the following sites: https://github.com/marcoalopez/GrainSizeTools/releases http://figshare.com/articles/GrainSizeTools_script/1383130 https://sourceforge.net/projects/grainsizetools/