oilftir 0.1.1__tar.gz

oilftir-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NahueMendez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oilftir-0.1.1/PKG-INFO

@@ -0,0 +1,293 @@
+Metadata-Version: 2.4
+Name: oilftir
+Version: 0.1.1
+Summary: FTIR-based condition monitoring of lubricating oils — ASTM E2412 toolkit
+Author: Nahuel Mendez
+Author-email: Nahuel Mendez <nahueldanielmendez@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/NahueMendez/oilftir
+Project-URL: LinkedIn, https://www.linkedin.com/in/ingnahuelmendez/
+Keywords: ftir,astm-e2412,lubricating-oil,condition-monitoring,spectroscopy,tribology
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Manufacturing
+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
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: pybaselines
+Provides-Extra: specio
+Requires-Dist: specio; extra == "specio"
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+# oilftir
+
+**FTIR-based condition monitoring of lubricating oils — ASTM E2412**
+
+`oilftir` is a Python library for processing and analysing FTIR spectra of
+used lubricating oils following the
+[ASTM E2412](https://www.astm.org/e2412-23.html) standard.  
+It provides spectrum loading, baseline correction, net area integration for
+all standard degradation and contamination bands, concentration estimation
+from calibration curves, spectral library search (HQI), and publication-ready
+plots.
+
+---
+
+## Features
+
+| Feature | Description |
+|---|---|
+| **Spectrum loading** | CSV / TXT and PerkinElmer `.sp` (optional) |
+| **Baseline correction** | Modified polynomial (ModPoly) via `pybaselines` |
+| **ASTM E2412 areas** | Oxidation, nitration, sulfation, water, glycol, petrol, diesel, ZDDP, soot |
+| **Calibration** | Generic polynomial curve — bring your own standards |
+| **Reference subtraction** | Least-squares scaling + difference spectrum |
+| **Library search** | Hit Quality Index (HQI), parallel brute-force |
+| **Plotting** | Dual-panel (absorbance + transmittance), multi-spectrum overlay |
+
+---
+
+## Installation
+
+```bash
+pip install oilftir
+```
+
+To read PerkinElmer `.sp` files, install the optional dependency:
+
+```bash
+pip install oilftir[specio]
+```
+
+### From source
+
+```bash
+git clone https://github.com/your-username/oilftir.git
+cd oilftir
+pip install -e .
+```
+
+---
+
+## Quick start
+
+```python
+from oilftir.astm_utils import load_spectrum, remove_baseline, astm_areas
+
+# Load and correct a spectrum
+df, meta = load_spectrum("used_oil.csv", magnitude="A")
+df = remove_baseline(df)
+
+# Compute all ASTM E2412 band areas
+areas = astm_areas(df)
+print(areas)
+# {
+#   'oxidation':     0.2341,
+#   'nitration':     0.0812,
+#   'sulfation':     0.1503,
+#   'water':         4.7620,
+#   'glycol':        0.0000,
+#   'fuel_petrol':   0.0034,
+#   'fuel_diesel':   0.0198,
+#   'antiwear_zddp': 8.3410,
+#   'soot':         12.5000,
+# }
+```
+
+See [`example.py`](example.py) for a full walkthrough including concentration
+estimation, reference subtraction, plotting, and library search.
+
+---
+
+## Input file format
+
+Plain-text files must be two-column (wavenumber, amplitude), comma- or
+space-delimited, with `#` for comment lines:
+
+```
+# wavenumber (cm-1), absorbance
+4000.0  0.0031
+3999.0  0.0028
+...
+```
+
+---
+
+## API reference
+
+### Loading
+
+```python
+load_spectrum(path, magnitude='A') → (DataFrame, dict)
+```
+`magnitude`: `'A'` (absorbance) or `'T'` (transmittance, 0–1 or 0–100).
+
+### Pre-processing
+
+```python
+remove_baseline(df, units='A', poly_order=5) → DataFrame
+scale_reference(df_sample, df_ref, units='A') → DataFrame
+subtract_reference(df_sample, df_ref, wavenumber_range, units='A')
+    → (y_diff, k, y_ref_scaled)
+```
+
+### ASTM E2412 band areas
+
+```python
+astm_areas(df)          → dict   # all bands at once
+area_oxidation(df)      → float  # 1670–1800 cm⁻¹
+area_nitration(df)      → float  # 1600–1650 cm⁻¹
+area_sulfation(df)      → float  # 1120–1180 cm⁻¹
+area_water(df)          → float  # 3150–3500 cm⁻¹
+area_glycol(df)         → float  # 1030–1100 cm⁻¹
+area_fuel_petrol(df)    → float  # 745–755 cm⁻¹
+area_fuel_diesel(df)    → float  # 805–815 cm⁻¹
+area_antiwear_zddp(df)  → float  # 960–1025 cm⁻¹
+soot_load(df)           → float  # absorbance at 2000 cm⁻¹ × 100
+```
+
+All area functions return a net integrated area in absorbance·cm⁻¹ (≥ 0).
+
+### Calibration
+
+```python
+area_to_concentration(area, calibration_areas, calibration_concentrations,
+                       poly_order=3) → float
+```
+
+Provide your own (area, concentration) calibration pairs — the function fits
+a polynomial and evaluates it at `area`.
+
+### Library search
+
+```python
+library_search(query_path, library_dir, top_n=5, extension='*.sp')
+    → list[dict]   # sorted by HQI descending
+```
+
+```python
+hqi(x_query, y_query, x_ref, y_ref) → float   # 0–100 %
+```
+
+### Plotting
+
+```python
+plot_spectra(data_dict, title, xlim, ylim_A, ylim_T, save_path)
+    → (fig, axes)
+```
+
+`data_dict` format:
+```python
+{
+    "Label": {
+        "df":        <DataFrame>,   # required
+        "color":     "steelblue",   # optional
+        "alpha":     1.0,           # optional
+        "linewidth": 1.5,           # optional
+    }
+}
+```
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---|---|
+| `numpy` | Numerical operations |
+| `pandas` | Spectrum data frames |
+| `scipy` | Spearman correlation (HQI fallback) |
+| `matplotlib` | Plotting |
+| `pybaselines` | Baseline correction |
+| `specio` *(optional)* | PerkinElmer `.sp` file reading |
+
+---
+
+## Contributing
+
+Contributions are welcome. Please open an issue or pull request on GitHub.
+
+---
+## Authors
+`oilftir` was developed at the Chemistry Laboratory of CENADIF ([Centro Nacional de Desarrollo e Innovación Ferroviaria](https://www.argentina.gob.ar/transporte/fase/cenadif)), Argentina, in the context of used-oil condition monitoring for the local railway industry.
+
+### Lead developer
+
+**Nahuel Mendez** — R&D Engineer/Physical Data Scientist, CENADIF |
+
+[![GitHub](https://img.shields.io/badge/GitHub-NahueMendez-181717?logo=github)](https://github.com/NahueMendez)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-ingnahuelmendez-0A66C2?logo=linkedin)](https://www.linkedin.com/in/ingnahuelmendez/)
+[![Email](https://img.shields.io/badge/Email-nahueldanielmendez%40gmail.com-D14836?logo=gmail)](mailto:nahueldanielmendez@gmail.com)
+
+
+### Collaborators
+
+| Name | Role |
+| :--- | :--- |
+| **Hernán Gomez Molino**, Eng. | Head of Laboratories, CENADIF |
+| **Leandro Asens**, Eng. | Head of the Chemistry Laboratory, CENADIF |
+---
+
+## Citing
+
+If you use `oilftir` in your research or academic work, please cite both the ASTM standard and this software library:
+
+### 1. The Software Library
+> Mendez, N., Gomez Molino, H., & Asens, L. (2026). *oilftir: A Python library for FTIR-based condition monitoring of lubricating oils following ASTM E2412*. https://doi.org/10.5281/zenodo.20137147
+
+### 2. The Implemented Standard
+> ASTM E2412-23, *Standard Practice for Condition Monitoring of Used Lubricants by Trend Analysis Using Fourier Transform Infrared (FT-IR) Spectrometry*, ASTM International, West Conshohocken, PA.
+
+You can also use the following BibTeX entry for your reference manager:
+
+```bibtex
+@software{mendez_oilftir_2026,
+  author       = {Mendez, Nahuel and Gomez Molino, Hern{\'a}n and Asens, Leandro},
+  title        = {oilftir: A Python library for FTIR-based condition monitoring of lubricating oils following ASTM E2412},
+  month        = may,
+  year         = 2026,
+  publisher    = {Zenodo},
+  doi          = {10.5281/zenodo.20137147},
+  url          = {doi.org}
+}
+```
+---
+
+## License
+
+```
+MIT License
+
+Copyright (c) 2026 oilftir contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

oilftir-0.1.1/README.md

@@ -0,0 +1,259 @@
+# oilftir
+
+**FTIR-based condition monitoring of lubricating oils — ASTM E2412**
+
+`oilftir` is a Python library for processing and analysing FTIR spectra of
+used lubricating oils following the
+[ASTM E2412](https://www.astm.org/e2412-23.html) standard.  
+It provides spectrum loading, baseline correction, net area integration for
+all standard degradation and contamination bands, concentration estimation
+from calibration curves, spectral library search (HQI), and publication-ready
+plots.
+
+---
+
+## Features
+
+| Feature | Description |
+|---|---|
+| **Spectrum loading** | CSV / TXT and PerkinElmer `.sp` (optional) |
+| **Baseline correction** | Modified polynomial (ModPoly) via `pybaselines` |
+| **ASTM E2412 areas** | Oxidation, nitration, sulfation, water, glycol, petrol, diesel, ZDDP, soot |
+| **Calibration** | Generic polynomial curve — bring your own standards |
+| **Reference subtraction** | Least-squares scaling + difference spectrum |
+| **Library search** | Hit Quality Index (HQI), parallel brute-force |
+| **Plotting** | Dual-panel (absorbance + transmittance), multi-spectrum overlay |
+
+---
+
+## Installation
+
+```bash
+pip install oilftir
+```
+
+To read PerkinElmer `.sp` files, install the optional dependency:
+
+```bash
+pip install oilftir[specio]
+```
+
+### From source
+
+```bash
+git clone https://github.com/your-username/oilftir.git
+cd oilftir
+pip install -e .
+```
+
+---
+
+## Quick start
+
+```python
+from oilftir.astm_utils import load_spectrum, remove_baseline, astm_areas
+
+# Load and correct a spectrum
+df, meta = load_spectrum("used_oil.csv", magnitude="A")
+df = remove_baseline(df)
+
+# Compute all ASTM E2412 band areas
+areas = astm_areas(df)
+print(areas)
+# {
+#   'oxidation':     0.2341,
+#   'nitration':     0.0812,
+#   'sulfation':     0.1503,
+#   'water':         4.7620,
+#   'glycol':        0.0000,
+#   'fuel_petrol':   0.0034,
+#   'fuel_diesel':   0.0198,
+#   'antiwear_zddp': 8.3410,
+#   'soot':         12.5000,
+# }
+```
+
+See [`example.py`](example.py) for a full walkthrough including concentration
+estimation, reference subtraction, plotting, and library search.
+
+---
+
+## Input file format
+
+Plain-text files must be two-column (wavenumber, amplitude), comma- or
+space-delimited, with `#` for comment lines:
+
+```
+# wavenumber (cm-1), absorbance
+4000.0  0.0031
+3999.0  0.0028
+...
+```
+
+---
+
+## API reference
+
+### Loading
+
+```python
+load_spectrum(path, magnitude='A') → (DataFrame, dict)
+```
+`magnitude`: `'A'` (absorbance) or `'T'` (transmittance, 0–1 or 0–100).
+
+### Pre-processing
+
+```python
+remove_baseline(df, units='A', poly_order=5) → DataFrame
+scale_reference(df_sample, df_ref, units='A') → DataFrame
+subtract_reference(df_sample, df_ref, wavenumber_range, units='A')
+    → (y_diff, k, y_ref_scaled)
+```
+
+### ASTM E2412 band areas
+
+```python
+astm_areas(df)          → dict   # all bands at once
+area_oxidation(df)      → float  # 1670–1800 cm⁻¹
+area_nitration(df)      → float  # 1600–1650 cm⁻¹
+area_sulfation(df)      → float  # 1120–1180 cm⁻¹
+area_water(df)          → float  # 3150–3500 cm⁻¹
+area_glycol(df)         → float  # 1030–1100 cm⁻¹
+area_fuel_petrol(df)    → float  # 745–755 cm⁻¹
+area_fuel_diesel(df)    → float  # 805–815 cm⁻¹
+area_antiwear_zddp(df)  → float  # 960–1025 cm⁻¹
+soot_load(df)           → float  # absorbance at 2000 cm⁻¹ × 100
+```
+
+All area functions return a net integrated area in absorbance·cm⁻¹ (≥ 0).
+
+### Calibration
+
+```python
+area_to_concentration(area, calibration_areas, calibration_concentrations,
+                       poly_order=3) → float
+```
+
+Provide your own (area, concentration) calibration pairs — the function fits
+a polynomial and evaluates it at `area`.
+
+### Library search
+
+```python
+library_search(query_path, library_dir, top_n=5, extension='*.sp')
+    → list[dict]   # sorted by HQI descending
+```
+
+```python
+hqi(x_query, y_query, x_ref, y_ref) → float   # 0–100 %
+```
+
+### Plotting
+
+```python
+plot_spectra(data_dict, title, xlim, ylim_A, ylim_T, save_path)
+    → (fig, axes)
+```
+
+`data_dict` format:
+```python
+{
+    "Label": {
+        "df":        <DataFrame>,   # required
+        "color":     "steelblue",   # optional
+        "alpha":     1.0,           # optional
+        "linewidth": 1.5,           # optional
+    }
+}
+```
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---|---|
+| `numpy` | Numerical operations |
+| `pandas` | Spectrum data frames |
+| `scipy` | Spearman correlation (HQI fallback) |
+| `matplotlib` | Plotting |
+| `pybaselines` | Baseline correction |
+| `specio` *(optional)* | PerkinElmer `.sp` file reading |
+
+---
+
+## Contributing
+
+Contributions are welcome. Please open an issue or pull request on GitHub.
+
+---
+## Authors
+`oilftir` was developed at the Chemistry Laboratory of CENADIF ([Centro Nacional de Desarrollo e Innovación Ferroviaria](https://www.argentina.gob.ar/transporte/fase/cenadif)), Argentina, in the context of used-oil condition monitoring for the local railway industry.
+
+### Lead developer
+
+**Nahuel Mendez** — R&D Engineer/Physical Data Scientist, CENADIF |
+
+[![GitHub](https://img.shields.io/badge/GitHub-NahueMendez-181717?logo=github)](https://github.com/NahueMendez)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-ingnahuelmendez-0A66C2?logo=linkedin)](https://www.linkedin.com/in/ingnahuelmendez/)
+[![Email](https://img.shields.io/badge/Email-nahueldanielmendez%40gmail.com-D14836?logo=gmail)](mailto:nahueldanielmendez@gmail.com)
+
+
+### Collaborators
+
+| Name | Role |
+| :--- | :--- |
+| **Hernán Gomez Molino**, Eng. | Head of Laboratories, CENADIF |
+| **Leandro Asens**, Eng. | Head of the Chemistry Laboratory, CENADIF |
+---
+
+## Citing
+
+If you use `oilftir` in your research or academic work, please cite both the ASTM standard and this software library:
+
+### 1. The Software Library
+> Mendez, N., Gomez Molino, H., & Asens, L. (2026). *oilftir: A Python library for FTIR-based condition monitoring of lubricating oils following ASTM E2412*. https://doi.org/10.5281/zenodo.20137147
+
+### 2. The Implemented Standard
+> ASTM E2412-23, *Standard Practice for Condition Monitoring of Used Lubricants by Trend Analysis Using Fourier Transform Infrared (FT-IR) Spectrometry*, ASTM International, West Conshohocken, PA.
+
+You can also use the following BibTeX entry for your reference manager:
+
+```bibtex
+@software{mendez_oilftir_2026,
+  author       = {Mendez, Nahuel and Gomez Molino, Hern{\'a}n and Asens, Leandro},
+  title        = {oilftir: A Python library for FTIR-based condition monitoring of lubricating oils following ASTM E2412},
+  month        = may,
+  year         = 2026,
+  publisher    = {Zenodo},
+  doi          = {10.5281/zenodo.20137147},
+  url          = {doi.org}
+}
+```
+---
+
+## License
+
+```
+MIT License
+
+Copyright (c) 2026 oilftir contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```