This repository contains code for dimensional analysis of heavy mineral grains in reflected light LA-ICP-MS alignment images using Google-Colab-compatable Jupyter notebooks, with or without the aid of deep-learning-based instance segmentation models. Because processing can be done in Google Colab, this method should be available to anyone with an internet connection and access to Google services. Users who lack one or both of these can instead run the notebooks on a local machine after a lengthier installation process. Detectron2 was used for model training and is used for Colab/Jupyter implementation.
The code in this repo enables organization (e.g., matching zircon/heavy mineral mosaic images to .scancsv scanlists), data extraction (e.g., mapping shots to subimages of mosaics), and post-segmentation processing (e.g., extracting accurate grain dimensions from segmentation masks) of mosaic-scanlist and single-shot-per-image reflected light zircon/heavy mineral image datasets from LA-ICP-MS facilities using Chromium targeting software. RCNN instance segmentation of grains is handled by Detectron2 and implemented in ready-to-run Google Colab/Jupyter notebooks (see 'Links'). Said code and notebooks have been tested with and fully support processing of image datasets from the University of Arizona LaserChron Center and the UCSB LA-ICP-MS facility; datasets from other facilities using Chromium should work with colab_zirc_dims but have not been tested. Users with reflected image datasets lacking Chromium image metadata can segment their images (see 'single image-per-shot' notebook below) with some additional project folder organization and/or after manually adding image scaling information, but they (and researchers with non-reflected-light images) should also consider using AnalyZr.
In datasets with good image quality and well-exposed grains (i.e., with full cross-sections visible above mounts(s)), automated colab_zirg processing achieves measurements comparable to those produced by humans (with average absolute error along long and short axes <10 μm vs. humans in 17/19 tested samples) in a fraction of the time. See below for an example analysis of a single spot.
| Analysis | Area (µm^2) | Convex area (µm^2) | Eccentricity | Equivalent diameter (µm) | Perimeter (µm) | Major axis length (µm) | Minor axis length (µm) | Circularity | Long axis rectangular diameter (µm) | Short axis rectangular diameter (µm) | Best long axis length (µm) | Best short axis length (µm) | Best axes calculated from | Scale factor (µm/pixel) |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Spot 95 | 1037.1 | 1078.3 | 0.898 | 36.3 | 133.6 | 54.9 | 24.2 | 0.730 | 54.4 | 24.8 | 54.9 | 24.2 | 2nd central moments | 1.027 |
See our Processing Outputs page for more details.
In sub-optimal datasets, automated processing is less successful and can produce inaccurate segmentations. To mitigate this, a semi-automated Colab/Jupyter-based GUI (extended from TensorFlow object detection utils code) that allows users to view and edit automatically-generated segmentations before export has also been implemented. Semi-automated processing is recommended for production of publication-quality measurement datasets.
Various functions for processing mosaic image datasets are available in (among others) modules czd_utils, mos_match, and mos_proc.
A variety of Detectron2-based instance segmentation models are available for application to images via the provided notebooks. You can check them out in our model library.
Please refer to the training datasets section of this repository to learn more about and/or download the datasets used to train models for application in colab_zirc_dims.
Colab/Jupyter notebooks are available for:
- Matching ALC mosiacs to .scancsv files (dataset preparation)
- Automatically and/or semi-automatically segmenting and measuring grains from mosaics - v1.0.10
A template project folder is available here.
Template project folders are available for:
- Datasets where sample, shot information can be extracted from image filenames (e.g., from UCSB)
- Datasets where shot images have been manually organized by user(s)
The notebooks provided can be run as basic Jupyter notebooks in a local Anaconda environment. Some setup is required, though. Please refer to the advanced local installation instructions.
A distribution of this package is available through the Python Package Index. It is recommended that this package only be used with the provided notebooks, but some functions could be useful to users working with mosaic or .Align files.
To install inside of Google Colab, add:
!pip install colab_zirc_dims
to a cell, then run the cell.
To install outside of Google Colab (without segmentation functionalities), open command line and enter:
pip install colab_zirc_dims
then press enter.
To install outside of Google Colab with full segmentation functionalities, please refer to the advanced local installation instructions.
- All features are functional. Bugs may exist, and are most likely to be encountered when using the package outside of the provided notebooks.
- All notebooks will now run as Jupyter notebooks in local Anaconda environments.
- New 'best axes' measurement that mitigates inaccuracies in moment-based axial measurements by defering to minimum-area rectangle measurements for most high-aspect ratio grains.
- Added new dataset, new models, and documentation pages.
- Automated processing notebooks updated on 05/19/2022 with V1.0.8.1 hotfix for incompatibility between latest Detectron2 binary release and new standard Colab PyTorch installation (v1.11).
- Any changes and/or additions necessary to ensure compatibility with datasets from LA-ICP-MS facilities other than ALC and UCSB. Contact me if you have a dataset from a non-ALC, non-UCSB facility that does not seem to work with colab-zirc-dims!
- Model retraining; will be done as needed given new architectures or hyperparameter tuning schemes that could significantly improve segmentation performance.
- Refactoring. The colab_zirc_dims package is fairly sprawling and probably doesn't need to be.
- Miscellaneous processing speed improvements. As of v1.0.10, there is a lot of room for improvement here, especially w/r/t maximizing GPU utilization.
- Training and large-n zircon measurement datasets for this project were provided by Dr. Ryan Leary (New Mexico Tech). Also, motivation; see his recent work on the utility of augmenting LA-ICP-MS data with grain size data.
- Some additional training data are from the UCSB Petrochronology Center.
- Although models were trained on (and tests have only been performed on) detrital zircon mosaic images, I think that this method could probably be applied to LA-ICP-MS mosaics/samples of other minerals (e.g., monazite) without further model training.
- Any suggestions, comments, or questions about this project are also welcome.
This project has been written up as a technical note in collaboration with Dr. Ryan Leary and published (open access) in Geochronology. You can find the technical note (along with associated links to additional datasets and replication code) here. If you use colab_zirc_dims or associated datasets/models in your work, please use the following citation:
Sitar, M. C. and Leary, R. J.: Technical note: colab_zirc_dims: a Google Colab-compatible toolset for automated and semi-automated measurement of mineral grains in laser ablation–inductively coupled plasma–mass spectrometry images using deep learning models, Geochronology, 5, 109–126, https://doi.org/10.5194/gchron-5-109-2023, 2023.
Michael Cole Sitar
M.S. student, Colorado State University Department of Geosciences
email: mcsitar@colostate.edu
Yuxin Wu, Alexander Kirillov, Francisco Massa and Wan-Yen Lo, & Ross Girshick. (2019). Detectron2. https://github.com/facebookresearch/detectron2.
TensorFlow Developers: TensorFlow, Zenodo, https://doi.org/10.5281/zenodo.5949169, 2022.