Metadata-Version: 2.4
Name: empeaks
Version: 3.0.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Requires-Dist: numpy>=1.23.0
Requires-Dist: scipy>=1.9.0
Requires-Dist: matplotlib>=3.6.0
Requires-Dist: pandas>=1.5.0
Requires-Dist: streamlit>=1.28.0
Requires-Dist: streamlit-aggrid>=0.3.3
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: watchdog>=6.0.0
License-File: LICENSE
Summary: high-throughput spectrum peak modeling tools by using Spectrum adapted EM algorithms
Author-email: Yasunobu Ando <yasunobu.ando@cls.iir.isct.ac.jp>
License: BSD-3-Clause
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

EMPeaks
========================

This package is for high-throughput peak analysis by using Spectrum Adapted EM algorithm.
Please refer the following paper when using this package:
[Sci. Tech. Adv. Mater. 20, 733-735 (2019).](https://www.tandfonline.com/doi/full/10.1080/14686996.2019.1620123);
[Sci. Tech. Adv. Mater. method 1, 45 (2021).](https://www.tandfonline.com/doi/abs/10.1080/27660400.2021.1899449)

## Version 3.0.x (Backend in Rust & GUI Application)
Version 3.0.x brings major updates to EMPeaks, focusing on performance and usability:
* **Backend in Rust**: The core algorithms have been rewritten in Rust, achieving substantial speedups in execution time and enabling more efficient high-throughput analysis.
* **GUI Application**: We have developed a new, user-friendly GUI application. It provides an intuitive environment for interactive data visualization, parameter tuning, and peak fitting.

### Installation

**1. Install via Wheel from GitHub Releases (Recommended for v3.0.x)**
We provide pre-compiled wheel (`.whl`) files for Python 3.11 and later. Download the appropriate `.whl` file for your operating system from the [GitHub Releases](https://github.com/TeamUndeux/EMPeaks/releases) page. Then navigate to the downloaded directory in your terminal and install it using pip:

* **Windows (x64)**
  ```bash
  pip install empeaks-3.0.0-cp311-abi3-win_amd64.whl
  ```

* **macOS (Universal2 for Intel & Apple Silicon)**
  ```bash
  pip install empeaks-3.0.0-cp311-abi3-macosx_*_universal2.whl
  ```

* **Linux (x86_64)**
  ```bash
  pip install empeaks-3.0.0-cp311-abi3-manylinux_*_x86_64.whl
  ```

**2. Install via PyPI (Currently Outdated)**

You can also install EMPeaks from PyPI using pip:
```bash
pip install EMPeaks
```

> [!WARNING]
> Due to a current issue with PyPI, the `pip install EMPeaks` command may install an older version, and updating to v3.0.x via PyPI is temporarily unavailable. Please use the wheel installation from GitHub Releases to get the latest 3.0.x features.

### Usage
After installation, you can launch the new GUI application by running the following command:
```bash
empeaks deck
```

## Version 2.2.x (Deterministic Annealing & TSDC mixture model)
In version 2.2.x, fitting model of Thermally Stimulated Depolarization Current(TSDC) 
and Deterministic Annealing with Dirichlet prior for mixing ratio estimation is implemented.

You can refer the details of the implementation in these papers;
* Deterministic Annealing: [Sci. Tech. Adv. Mater. meth. 4, 2373046 (2024).](https://doi.org/10.1080/27660400.2024.2373046);
* TSDC modeling: [Sci. Tech. Adv. Mater. meth. 5, 2441102 (2025).](https://doi.org/10.1080/27660400.2024.2441102)

### TSDC modeling
TSDC modeling is available with a same way to use other models like Gaussian mixture models.
You can test the model by example object as follows:
```python
from EMPeaks import TSDCMixture

tsdc = TSDCMixture.TSDCMixtureModel()
examples = TSDCMixture.Tests.Example(K=4)

examples.adapted_em()
examples.leastsq()
```
The method of examples.adapted_em() executes fitting of TSDC mixture model via EM algorithm. 
The method of examples.leastsq_tau0() demonstrates the fitting of TSDC mixture model via 
least-square method for the variables of $E_a$, $T_p$, and $\pi$ in each component. 
$E_a$, $T_p$, and $\pi$ represent activation energy, peak temperature, and mixture ratio, respectively.

### Deterministic Annealing
Deterministic Annealing is a kind of sparse modeling. We can select important peak component 
automatically by Dirichlet prior for mixture ratio. First, enough peak number $K$ should set.
Dirichlet prior conducts mixture ratio of redundant components to zero. 
It is implemented in EMCore/_em_core.py. 
Deterministic annealing is available for all mixture models.
For example, following code shows how to use deterministic annealing 
with Gaussian mixture models.
```python
from EMPeaks import GaussianMixture

x = np.load("energy.dat")
y = np.load("intensity.dat")

gmm = GaussianMixture.GaussianMixtureModel(K=10, background='linear')
gmm.Dirichlet_alpha = 0.5
gmm.deterministic_annealing(x, y)
```
In default, Dirichlet_alpha=1.0. 
Please change it to the number less than 1.0 if you want to introduce it, for example, 0.5.

## Version 2.1.x (Background Subtraction)
In version 2.1.x, Automated background subtraction is implemented. Following background models are available now.
* uniform: uniform background model
* linear: linear background model (positive gradient)
* ramp_sum: Ramp-Sum background model

The details of these models are explained in this paper,
[Sci. Tech. Adv. Mater. Method 3,  2159753 (2023).](https://www.tandfonline.com/doi/abs/10.1080/27660400.2022.2159753)

Background models are easily implemented into model instance as follows;
```python
from EMPeaks import GaussianMixture
gmm = GaussianMixture.GaussianMixtureModel(K=3, background='uniform')
```
Keywords to set the background models are ```uniform```, ```linear```, ```ramp_sum```.

## Version 2.0.x
In version 2.0.x, Gaussian Mixture Model (GMM), Lorentzian Mixture Model (LMM), 
Pseudo Voigt Mixture model (PVMM), and Doniach-Sunijic Miture model (DSMM).
In principle, these combination models are also available but not implemented yet.

From this version, each model has the same functions but differ from version 1, 
though functions and classes in version 1 still work. Sample codes to import 
these models are followings for instance:
```python
from EMPeaks import GaussianMixture
gmm = GaussianMixture.GaussianMixtureModel(K=3)
```
```python
from EMPeaks import LorentzianMixture
lmm = LorentzianMixture.LorentzianMixtureModel(K=2)
```
Mixture model object includes a single model object.
These packages also have a class 
for single Gaussian, Lorentizan, pseudo Voigt, and DS models.
For example,
```python
from EMPeaks import GaussianMixture
gm = GaussianMixture.Gaussian(x_min=-100, x_max=100, sigma_min=0.1, sigma_max=10)
```

In version 2, we do not implement the class for optimization. 
Instead,all model classes has functions to optimize the parameters 
to fit the target data.
```python
from EMPeaks import GaussianMixture
import numpy as np

x = np.load("energy.dat")
y = np.load("intensity.dat")

gmm = GaussianMixture.GaussianMixtureModel(K=3)
gmm.fit(x, y)
# if you want to sample some initial guess and choose the highest likelihood model,
gmm.sampling(x, y, trial=10)
```
After fitting, you can plot both raw data and fitted model as follows:
```python
gmm.plot(x, y)
```

---------------
&copy; 2020-2023 National Institute of Advanced Industrial Science and Technology (AIST)\
&copy; 2024-2026 Yasunobu Ando in Science Tokyo
