diff --git a/DOCS/FAQ.md b/DOCS/FAQ.md deleted file mode 100644 index 29effc8..0000000 --- a/DOCS/FAQ.md +++ /dev/null @@ -1,81 +0,0 @@ -# Frequently Asked Questions - -- [Who is this script for?](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/FAQ.md#who-is-this-script-for-) -- [What measure of central tendency (i.e. average) do I have to use?](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/FAQ.md#what-measure-of-central-tendency--ie-average--do-i-have-to-use-) -- [When to use the standard deviation and the confidence interval for the average?](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/FAQ.md#when-to-use-the-standard-deviation-and-the-confidence-interval-for-the-average-) -- [Why the grain size distribution plots produced by the GST script and the classic CSD charts do not use the same units on the y-axis?](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/FAQ.md#why-the-grain-size-distribution-plots-produced-by-the-gst-script-and-the-classic-csd-charts-do-not-use-the-same-units-on-the-y-axis-) -- [Why the sum of all frequencies in the histograms is not equal to one?](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/FAQ.md#why-the-sum-of-all-frequencies-in-the-histograms-is-not-equal-to-one-) -- [Specifying Script Version in Publications](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/FAQ.md#specifying-script-version-in-publications) -- [Does the script work with Python 2.7.x?](https://github.com/marcoalopez/GrainSizeTools/blob/master/DOCS/FAQ.md#does-the-script-work-with-python-27x-) - -## Who is this script for? -The script serves three primary goals: - -- Promoting best practices and reproducibility in grain size analysis through robust statistics. It aims to avoid manual steps during data processing and advocates for standard procedures in grain size characterization. -- Maintaining a curated and up-to-date database of grain-size-based paleopiezometers for various mineral phases. -- Providing a platform for the implementation and testing of new methods for grain size characterization in recrystallized materials - -Specifically, this script is designed for individuals who: - -- Want to visualize grain size distributions. - -- Estimate the magnitude of differential stress in dynamically recrystallized rocks from apparent grain sizes. - -- Aim to approximate the actual (3D) distribution of grain sizes from thin sections using stereological methods. This involves estimating the volume occupied by a particular grain size fraction and a parameter characterizing the shape of the grain size population (assuming a lognormal distribution). The stereological methods assume that grains have equant or near-equant shapes (AR < 2.0), which mostly include all recrystallized grains produced during static and dynamic recrystallization. Additional details are available [here](http://joss.theoj.org/papers/10.21105/joss.00863). - -> For igneous studies involving tabular grains far from near-equant objects, we recommend other approaches such as those implemented in the *CSDCorrections* software (Higgins 2000). See the references list section for details. - -## What measure of central tendency (i.e. average) do I have to use? - -The choice of the measure depends on your specific goals and dataset. Here are some guidelines based on [Lopez-Sanchez (2020)](https://doi.org/10.1016/j.jsg.2020.104042): - -- **Geometric mean:** This is recommended, especially for lognormal-like populations, showing superior performance across asymmetry and sample sizes. -- **Median:** Preferable when dealing with data contamination, such as outliers or observations from mixed distributions. -- **Arithmetic mean:** the most backwards-compatible average due to its common use in the past. Theoretically, it outperforms the median in low to moderately skewed distributions (MSD < 1.7) as long the presence of extreme values (outliers) is limited. However, the estimation of error margins for the arithmetic mean can be problematic in real samples, making the geometric mean or median preferable. -- **KDE-based mode:** Generally, this performs less effectively than other measures of central tendency. However, it remains robust in specific situations likely to occur in grain size studies, such as notable differences in resolution limits and size cut-offs. In these cases, it is the only useful measure of central tendency when comparing different sets of data. -- **Root mean squared (RMS) or Area-weighted mean:** Avoid them, both tend to perform poorly. - -> For those aiming to use a specific piezometer, it is crucial to **use the same average used in the piezometric calibration**. If establishing a new calibration or summarizing the distribution, the provided guidelines can assist in selecting the most suitable measure. Additional details can be found [here](https://github.com/marcoalopez/marcoalopez.github.io/blob/master/docs/2020_JSG_SG_104042.pdf) - -## When to use the standard deviation and the confidence interval for the average? - -That depends on the information you want to provide. If the message is on the spread of the grain size population (e.g. to compare between different grain size distributions) the standard deviation or the interquartile range is the metric you want. If the interest is in the precision of the average or in comparing averages between different grain size populations the confidence interval is your metric (e.g., when using paleopiezometers). More precisely: - -The **standard deviation** (s.d.) is the typical difference between each value and the mean value. So, in this case, it describes how broadly the grain size values are distributed within the sample. **Standard deviation describes a dataset**. - -The **standard error of the mean** (s.e.m.) is an estimate of how variable the means will be if the experiment or measure is repeated multiple times. The s.e.m. may serve to check whether sets of samples are likely to come from the same or a similar population. **Standard error describes an estimate**. - -The **95 % confidence interval** (C.I., 95%) means that the population mean will lie in this interval with 95% confidence. This metric is valuable when assessing the precision of the average or comparing averages between different grain size populations. It's like saying, "We're 95% confident that the true average grain size falls within this range." In simpler terms, it gives you a sense of how certain you can be about the average, considering the inherent variability in your data. - -## Why the grain size distribution plots produced by the GST script and the classic CSD charts do not use the same units on the y-axis? - -As you may notice, classic CSDs charts (Marsh, 1988) show in the vertical axis the logarithmic variation in population density or log(frequency) in mm-4, while the stereological methods put in the GrainSizeTools (GST) script returns plots with a linear frequency (per unit volume). This distinction arises from their distinct purposes. - -**Classic CSD charts** (Marsh, 1988) were originally designed for deriving two things in magmatic systems: i) nucleation rates and ii) crystal growth rates. In these systems, small grains are more abundant than large ones and the increase in quantity is typically exponential. The logarithmic scale aids in obtaining a straight line, facilitating the derivation of crystal growth rates and nucleation rates. Further, the intercept of the line at grain size equal to zero allows for estimating the nuclei population density. - -In recrystallized rocks, there is no grain size equal to zero and we usually unknown the crystallization time, so the use of CSDs is not optimal. Furthermore, the use of the logarithm in the vertical axis has two main disadvantages for microstructural studies: (i) it obscures the reading of the volume of a particular grain fraction, a common target in microtectonic studies, and (ii) it prevents the easy identification of the features of grain size distribution, which is relevant for applying the two-step method. In summary, the difference in units reflects the specific aims and considerations of each method, with the GST script tailored to microstructural studies in recrystallized rocks. - -## Why the sum of all frequencies in the histograms is not equal to one? - -The sum of all frequencies in the histograms is not equal to one due to the normalization process. After the frequencies are initially normalized to one, indicating that the integral over the range equals one, the procedure divides them by the bin size. Consequently, the sum of all frequency values will not equal one unless the bin size is one. This normalization method was deliberately chosen for several reasons: - -1. **Comparing Distributions:** It facilitates the comparison of distributions using different bin sizes, allowing for flexibility in the analysis. -2. **Two-Step Method Requirement:** This normalization method is necessary for the proper application of the two-step method, ensuring accurate and consistent results across various datasets. - -In essence, the non-summing to one outcome is a consequence of a deliberate normalization strategy that enhances the versatility and applicability of the analysis, particularly in scenarios where different bin sizes are employed. - -## Specifying Script Version in Publications - -Yes, it is highly recommended to specify the version of the script used in a publication. This practice helps ensure transparency and allows others to replicate your results. Bugs or updates in script versions may impact the outcomes, and version information aids in tracking and correcting any issues. - -When indicating the version in your manuscript, consider the following format: *"...we used the GrainSizeTools script version x..."* and then refer to the general citation: - -Lopez-Sanchez, Marco A. (2018). GrainSizeTools: a Python script for grain size analysis and paleopiezometry based on grain size. _Journal of Open Source Software_, 3(30), 863, https://doi.org/10.21105/joss.00863 - -## Does the script work with Python 2.7.x? - -No, the script does not work with Python 2 as this Python branch was officially discontinued in 2020, so it is time to move on. - - - -[return me to the home page](https://marcoalopez.github.io/GrainSizeTools/) \ No newline at end of file diff --git a/DOCS/README.md b/DOCS/README.md index f77003b..732879d 100644 --- a/DOCS/README.md +++ b/DOCS/README.md @@ -1,3 +1,3 @@ -This folder contains markdown documentation files (a mirror of the wiki) and Jupyter notebooks of the GrainSizeTools script. +This folder contains old markdown documentation files and Jupyter notebooks. The documentation of GrainSizeTools script is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (CC BY-NC-SA 4.0)](https://creativecommons.org/licenses/by-nc-sa/4.0/). \ No newline at end of file diff --git a/DOCS/imageJ_tutorial.md b/DOCS/imageJ_tutorial.md deleted file mode 100644 index a9415d7..0000000 --- a/DOCS/imageJ_tutorial.md +++ /dev/null @@ -1,69 +0,0 @@ -*last update 2024/01/31* - -How to measure the areas of the grain profiles with ImageJ -------------- - -> **Before you start:** This tutorial assumes that you have installed the ImageJ application. If this is not the case, go [here](https://imagej.net/downloads) to download and install it. You can also install different flavours of the ImageJ application that will work similarly (see [here](https://imagej.net/software/) for a summary). As a cautionary note, this is not a detailed tutorial on image analysis methods using ImageJ, but a quick systematic tutorial on how to measure the areas of the grain profiles from a thin section to later estimate the grain size and grain size distribution using the GrainSizeTools script. If you are interested in image analysis methods (e.g. grain segmentation techniques, shape characterization, etc.) you should have a look at the list of references at the end of this tutorial. - -### *Previous considerations on the Grain Boundary Maps* - -Grain size in rocks are usually measured in thin sections (2D data) through image analysis such as grain boundary maps (Fig. 1). - -![Figure 1. An example of a grain boundary map](https://raw.githubusercontent.com/marcoalopez/GrainSizeTools/master/FIGURES/GBmap.png) -*Figure 1. An example of a grain boundary map* - -These measures are mostly made on digital images consisting of pixels, known as a [raster graphic image](https://en.wikipedia.org/wiki/Raster_graphics). For example, in an 8-bit grayscale image, each pixel contains three values of information: its location in the image -their x and y coordinates- and its value of grey in a range that goes from 0 (black) to 255 (white) (i.e. it allows 256 different grey intensities). In a binary image, commonly used for grain boundary maps (Fig. 1), only two possible values exist, 0 for black pixels (the grains) and 1 for white pixels (the grain boundary). - -One of the key points about raster images is that they are resolution-dependent. This is each pixel has a physical dimension and, hence, the resolution depends on the number of pixels per unit area or length; it is usually measured in pixel per (square) inch (PPI) (see [Image resolution](https://en.wikipedia.org/wiki/Image_resolution) and [Pixel density](https://en.wikipedia.org/wiki/Pixel_density)). This concept is key as the resolution of the raw image -the image obtained directly from the device attached to the microscope- will limit the precision of the measures. Knowing the size of the pixels is therefore essential and makes it possible to set the scale of the image to correctly measure the areas of the grain sections. So be sure to track the resolution of the image at each step, from the raw image you get from the microscope to the grain boundary map on which you make the measurements. - -> [!IMPORTANT] -> It is important not to confuse the pixel resolution with the actual spatial resolution of the image. Spatial resolution refers to the true resolution of the image and this is not only limited by pixel density but also physically. For example, conventional SEM techniques have a maximum spatial resolution depending on acquisition conditions, with a maximum spatial resolution around 50 to 100 nm whatever the pixels in the image recorded. In optics, the resolution is approximated by *R = 0.61λ / A*, where *λ* is the wavelength of the light, typically taken as 0.4 μm, and *A* is the numerical aperture of the lens system. For more information see [here](https://en.wikipedia.org/wiki/Diffraction-limited_system) -> -> As an example, think in a digital image of a square inch in size and made of just one black pixel (i.e. with a resolution of PPI = 1). If we double the resolution of the image, we will obtain the same image but now formed by four black pixels instead of one. The new pixel resolution per unit length will be PPI = 2 (or 4 per unit area), however, the spatial resolution of the image remains the same. Strictly speaking, spatial resolution refers to the number of independent pixel values per unit area/length. - -The list of techniques that make possible the transition from a raw image to a grain boundary map, known as grain segmentation, is extensive and depends largely on the image source. Thus, digital images may come from a transmission or reflected light microscopy, semi-automatic techniques coupled to light microscopy such as the CIP method (e.g. Heilbronner 2000), electron microscopy either from BSD images or EBSD maps or even from electron microprobes through compositional mapping. All these techniques produce images with variable features and artefacts (i.e. different resolutions, colour *vs* greyscale, nature of the artefacts, grain size boundary *vs* phase maps, etc.). Addressing these segmentation methods is beyond the scope of this tutorial and the reader is referred to the two references cited at the end of this document. This tutorial focuses instead on showing in a very general way the features of grain boundary maps and how to measure their characteristics with the ImageJ software. - -Once the grain segmentation is done, it is crucial to ensure that the pixel boundaries of the grain are at least two or three pixels wide (Fig. 2). This will prevent the formation of undesirable artefacts since when two black pixels belonging to two different grains are placed adjacent to each other, both grains will be considered the same grain by the image analysis software. - - -*Figure 2. Detail of grain boundaries in a grain boundary map. The figure shows the boundaries (in white) between three grains in a grain boundary map. The squares represent the pixels in the image. The boundaries are two pixels wide approximately.* - -### *Measuring the areas of the grain profiles* - -1) Open the grain boundary map with the ImageJ application - -2) To measure the areas of the grain profiles it is first necessary to convert the grain boundary map into a binary image. If this was not done previously, go to ```Process>Binary``` and click on ```Make binary```. Also, make sure that the areas of grain profiles are in black and the grain boundaries in white and not the other way around. If not, invert the image in ```Edit>Invert```. - -3) Then, it is necessary to set the scale of the image. Go to ```Analize>Set Scale```. A new window will appear (Fig. 3). To set the scale, you need to know the size of a feature, such as the width of the image, or the size of an object such as a scale bar. The size of the image in pixels can be check in the upper left corner of the window, within the parentheses, containing the image. To use a particular object of the image as scale the procedure is: i) Use the line selection tool in the toolbar (Fig. 3) and draw a line along the length of the feature or scale bar; ii) go to ```Analize>Set Scale```; iii) the distance of the drawn line in pixels will appear in the upper box, so enter the dimension of the object/scale bar in the 'known distance' box and set the units in the 'Unit length' box; iv) do not check 'Global' unless you want that all your images have the same calibration and click ok. Now, you can check in the upper left corner of the window the size of the image in microns (millimetres or whatever) and pixels. - -![Figure 3. Set scale menu](https://raw.githubusercontent.com/marcoalopez/GrainSizeTools/master/FIGURES/Set%20scale.png) -*Figure 3. At left, the Set Scale window. In the upper right, the ImageJ menu and tool bars. The line selection tool is the fifth element from the left (which is actually selected). In the bottom right, the upper left corner of the window that contains the grain boundary map. The numbers are the size in microns and the size in pixels (in brackets).* - -4) The next step requires to set the measurements to be done. For this, go to ```Analize>Set Measurements``` and a new window will appear. Make sure that 'Area' is selected. You can also set at the bottom of the window the desired number of decimal places. Hit ok. - -5) To measure the areas of our grain profiles we need to go to ```Analize>Analize Particles```. A new window will appear with different options (Fig. 4). The first two are for establishing certain conditions to exclude anything that is not an object of interest in the image. The first one is based on the size of the objects in pixels by establishing a range of size. We usually set a minimum of four pixels and the maximum set to infinity to rule out possible artefacts hard to detect by the eye. This ultimately depends on the quality and the nature of your grain boundary map. For example, people working with high-resolution EBSD maps usually discard any grain with less than ten pixels. The second option is based on the roundness of the grains. We usually leave the default range values 0.00-1.00, but again this depends on your data and purpose. For example, the roundness parameter could be useful to differentiate between non-recrystallized and recrystallized grains in some cases. Just below, the 'show' drop-down menu allows the user to obtain different types of images when the particle analysis is done. We usually set this to 'Outlines' to obtain an image with all the grains measured outlined and numbered, which can be useful later to check the data set. Finally, the user can choose between different options. In our case, it is just necessary to select 'Display results'. Hit ok. - -![Figure 4. Analize Particles menu](https://raw.githubusercontent.com/marcoalopez/GrainSizeTools/master/FIGURES/AnalizeParticles.png) -*Figure 4. Analyze particles window showing the different options* - -6) After a while, several windows will appear. At least, one containing the results of the measures (Fig. 5), and others containing the image with the grains outlined and numbered. Note that the numbers displayed within the grains in the image correspond to the values showed in the first column of the results. To save the image go to the ImageJ menu bar, click on ```File>Save As```, and choose the file type you prefer (we encourage you to use PNG or TIFF for such type of image). To save the results we have different options. In the menu bar of the window containing the results, go to ```Results>Options``` and a new window will appear (Fig. 6). In the third line, you can choose to save the results as a text (.txt), CSV comma-separated (.csv) or Excel (.xls) file types. We encourage you to choose either *txt* or *CSV* since both are widely supported formats to exchange tabular data. Regarding the 'Results Table Options' at the bottom, make sure that 'Save column headers' are selected since this headers will be used by the GrainSizeTools script to automatically extract the data from the column 'Area'. Finally, in the same window go to ```File>Save As``` and choose a name for the file. You are done. - - -*Figure 5. The results windows showing all the measures done on the grains by the ImageJ application.* - -![Figure 6. ImageJ I/O options window](https://raw.githubusercontent.com/marcoalopez/GrainSizeTools/master/FIGURES/Fig_ImageJ_IOoptions.png) -*Figure 6. ImageJ I/O options window.* - -### *List of useful references* - -**Note**: This list of references is not intended to be exhaustive in any way. It simply reflects some books, articles or websites that I find interesting on the topic. I intend to expand this list over time. Regarding the ImageJ application, there are many tutorials on the web, see for example [here](http://imagej.nih.gov/ij/docs/index.html) or [here](http://imagej.net/Category:Tutorials) - -Russ, J.C., 2011. The image processing handbook. CRC Press. Taylor & Francis Group - -> This is a general-purpose book on image analysis written by professor John C. Russ from the Material Sciences and Engineering at North Carolina State University. Although the book is not specifically focused on structural geology, thin sections, or even rocks, it covers a wide variety of procedures in image analysis and contains very nice examples of image enhancement, segmentation techniques or shape characterization. I find the text very clear and well-written, so if you are looking for a general-purpose image analysis book, this is the best one I know. - -Heilbronner, R., Barret, S., 2014. Image Analysis in Earth Sciences. Springer-Verlag Berlin Heidelberg. doi:[10.1007/978-3-642-10343-8](http://link.springer.com/book/10.1007%2F978-3-642-10343-8) - -> This book focuses on image analysis related to Earth Sciences putting much emphasis on methods used in structural geology. The first two chapters deal with image processing and grain segmentation techniques using the software Image SXM, which is a different flavour of the ImageJ family applications (see [here](http://fiji.sc/ImageJ)). - -[return to GrainSizeTools website](https://marcoalopez.github.io/GrainSizeTools/)