Metadata-Version: 2.4
Name: lasertramdb
Version: 2.0.0
Summary: Dashboard for Time Resolved Analysis of LA-ICP-MS Data
Author-email: Jordan Lubbers <jlubbers@usgs.gov>
License-Expression: MIT
License-File: LICENSE
Keywords: LA-ICP-MS,data analysis,geochemistry,laser ablation,mass spectrometry
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.10
Requires-Dist: lasertram>=1.0.6
Requires-Dist: matplotlib<3.11,>=3.7
Requires-Dist: numpy>=1.24
Requires-Dist: openpyxl
Requires-Dist: pandas>=2.0
Requires-Dist: pyqt6-webengine>=6.4
Requires-Dist: pyqt6>=6.4
Requires-Dist: python-dotenv
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-qt; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# LaserTRAM-DB

Welcome to LaserTRAM-DB, a PyQt6-based graphical user interface for processing LA-ICP-MS (Laser Ablation Inductively Coupled Plasma Mass Spectrometry) data using the [**`lasertram`**](https://code.usgs.gov/vsc/petro/tools/lasertram) library.

## Migrating from previous versions

Previously, LaserTRAM-DB had been built using Plotly-Dash and hosted on [**GitHub**](https://github.com/jlubbersgeo/laserTRAM-DB). That repository has now been archived and all current development will be happening in this repository, as all new dev work by me will be done on USGS time, rather than when I was a grad student. It is _HIGHLY_ recommended you abandon using the GitHub version of the dashboard as it is no longer supported and switch over to this one.

## Motivation

LaserTRAM-DB is a dashboard for the complete processing pipeline of Laser Ablation Inductively Coupled Plasma Mass Spectrometry (LA-ICP-MS) data in complex materials such as geologic samples. As LA-ICP-MS data in geologic samples frequently have multiple phases, inclusions, and other compositional complexities within them that do not represent the material of interest, user interaction is required to filter unwanted signals out of the overall ablation signal. LaserTRAM-DB allows the user to filter which portion of the ablation peak is utilized in calculating concentrations, subsequently allowing for more accurate data to be obtained. It allows easy inspection of any sort of calculation done to the data and just about everything is exportable from tables and figures displayed within the dashboard.


## Installation

It is recommended you do this in a fresh virtual environment. For example, using `conda`:

```bash
# create lasertramdb virtual environment
# using specifically python 3.13
conda create -n lasertramdb python=3.13
```

Then with your virtual environment activated clone the repository to your local machine wherever you like:

```bash
# Clone or download the repository
# and navigate to it on your machine
cd lasertramdb
conda activate lasertramdb

# install normally
pip install .

# Or install in development mode with dev dependencies
pip install -e ".[dev]" 
```

## Launching the Application

```bash
# with the virtual environment activated
# and library installed
lasertramdb
```


## Basic Structure
The dashboard is comprised of four parts:

_Note_ to get more information all the annotated widgets below, with the installation complete, simply activate your virtual environment and:

```bash
lasertramdb --help
```

The first time you run this command, it will take a bit to start up as it is compiling the application. After that, it should start up much faster. 

### Preprocessing

Below is an annotated LaserTRAM preprocessing tab from LaserTRAM-DB. This tab is used for taking a folder of `.csv` files, each containing the raw counts per second data for a single spot analysis, and combining them into one coherent dataset that can then be processed using the `LaserTRAM` tab. Each `.csv` file is the untouched file off the mass spectrometer for a single spot analysis. Rather than dealing with a collection of hundreds of files, this tab allows the user to consolidate all that information into one place.

![lasertram tab](src/lasertramdb/resources/docs/lasertram-db2_preprocessing.png)

### LaserTRAM

Below is an annotated LaserTRAM tab from LaserTRAM-DB. This tab is used for determining which portion of a signal is utilized for further processing. As many geologic materials contain heterogeneities, this time resolved analysis is crucial in accurately calculating concentrations for materials of interest. Everything in this tab is designed to make that process efficient and quantifiable. 

![lasertram tab](src/lasertramdb/resources/docs/lasertram-db2_lasertram.png)

### LaserTRAM reprocessing

Below is an annotated LaserTRAM-reprocessing tab from LaserTRAM-DB. This tab is used for "redoing" the lasertram process with already chosen intervals (i.e., the results of a previous experiemnt). Its purpose is to allow the user to use intervals from a previous session to either re-normalize to a different internal standard, apply (or not) a despiking algorithm to the data, or both! The overall goal is to make it such that the most time consuming part of laser ablation data processing - the choosing of ablation intervals that reflect the material of interest - is only done once.

![reprocessing tab](src/lasertramdb/resources/docs/lasertram-db2_reprocessing.png)

### LaserCalc

Below is an annotated LaserCalc tab from LaserTRAM-DB. The purpose of this tab is to take data that have been filtered for the desired signal region and normalized to an internal standard and calculate concentrations based on the known concentrations of:

1. a user specified calibration standard reference material
2. the internal standard in the unknown analyses.

For more information on the math behind this, the user is referred to the `lasertram` [**documentation**](https://jlubbersgeo.github.io/lasertram/latest/explanation/). There are also widgets within the LaserCalc tab for inspecting the behavior or analytes in the calibration standard over time. As these data are extremely important in calculating final concentrations, checking their quality and behavior over an analytical session helps maximize final concentration quality.

![lasercalc tab](src/lasertramdb/resources/docs/lasertram-db2_lasercalc.png)


## Usage

After installation, to fire up the application run from the command line (within whichever envrironment the dashboard is installed. The first time you run this command, it will take a bit to start up as it is compiling the application. After that, it should start up much faster.):

```bash
lasertramdb
```

Or from Python:

```python
from lasertramdb.app import main
main()
```

On application startup a File Dialog will prompt the user to choose a directory. This will be the "home" directory for the data processing session and the default location that all other File Dialogs will open up to and save files to. It is also where each session log file will be saved. This can be updated at any point in the session.

### Workflow

It is recommended that users first become familiar with basic laser ablation ICP-MS data processing workflows. This can be done by referencing the `lasertram` documentation. Specifically the following sections:

- [**Background**](https://jlubbersgeo.github.io/lasertram/latest/explanation/)
- [**Basic Usage**](https://jlubbersgeo.github.io/lasertram/latest/lasertram_tutorial/)

In many ways you can think of this dashboard as a graphical user interface for the `lasertram` library where the widgets help you efficiently inspect how choosing different ablation intervals, internal standards, and calibration standards affect your final calculated concentrations. 

### Demo Videos

_Coming Soon_

For now we refer users to the _old_ videos [**here**](https://youtube.com/playlist?list=PLxZuo_RAAq_c4pd23NQzQ03hZgHjJ6AAN&si=OXQMr69vSi2tgw-w), as much of the logic and general workflow can be found there.


## Referencing

The underlying math and data structures are outlined in the following manuscript:

> Lubbers, J., Kent, A. J., & Russo, C. (2025). lasertram: A Python library for time resolved analysis of laser ablation inductively coupled plasma mass spectrometry data. Applied Computing and Geosciences, 25, 100225. https://doi.org/10.1016/j.acags.2025.100225

The dashboard itself is also citeable:

> Lubbers, J., (2026). lasertramdb, version 2.0.0: U.S. Geological Survey software release https://doi.org/10.5066/P14VNQMY

## Contributing

I am more than happy to have contributors. If you feel that you have ideas you would like implemented or want to help contribute please reach out:

***Maintainer:*** Jordan Lubbers jlubbers at usgs dot gov
