Metadata-Version: 2.4
Name: nileredquant
Version: 0.2.0
Summary: Tool for automated quantification of lipid accumulation in yeasts based on the Nile Red plate assay
Project-URL: Homepage, https://github.com/zganjarmia/NileRedQuant
Project-URL: Repository, https://github.com/zganjarmia/NileRedQuant
Project-URL: Issues, https://github.com/zganjarmia/NileRedQuant/issues
Author-email: Mia Žganjar <zganjar.mia@gmail.com>
Maintainer-email: Mia Žganjar <zganjar.mia@gmail.com>
License: SPDX-License-Identifier: MIT License
        
        Copyright (c) 2025, Mia Žganjar
        
        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.
        
License-File: LICENSE
Keywords: HTS,Nile Red,fluorescence,lipid,plate assay,plate reader,yeast
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: <3.12,>=3.9
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: openpyxl>=3.1.2
Requires-Dist: pandas>=2.2.0
Requires-Dist: pingouin>=0.5.3
Requires-Dist: scipy>=1.11.4
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: build; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: sphinx-autobuild; extra == 'docs'
Requires-Dist: sphinx>=7; extra == 'docs'
Description-Content-Type: text/markdown

# ***NileRedQuant*** — Tool for Automated Neutral Lipid Quantification in Yeasts

*Table of Contents*
- [Overview](#Overview)
  - [Citing](#Citing)
  - [Key features](#Keyfeatures)
- [Installation](#Installation)
- [Input Format](#InputFormat)
- [Quick Start](#Quickstart)
- [Documentation](#Documentation)
- [Licence](#Licence)


## Overview
**NileRedQuant** is a tool designed for automated analysis and data processing of Nile red-based plate assays used to quantify neutral lipids in yeasts.

It provides an analysis pipeline to turn raw fluorescence intensities into quality-checked, biomass-normalized lipid readouts, with optional calibration to a reference method (e.g., Gravimetric analysis, TLC, …) for lipid content prediction. **NileRedQuant** supports both 96-well and 384-well assay formats, offering increased throughput and flexibility.

Starting from plate reader exports, it imports and reshapes data, subtracts *'blanks'* and background fluorescence intensities, normalizes the fluorescence signal to biomass (*Absorbance*) providing the *`Lipid`* signal and flags outliers per *`Strain`* × *`Condition`*.

The module *`standard_curve()`* offers optional calibration of control strains/individuals against a reference method to compute predicted *lipid content*.

### Key features
1. **I/O & plate utilities**
  1. Import `.csv`, `.tsv`, or `.xlsx` files;
  1. convert between microtiter plate layouts and long (tidy) format;
  1. attach metadata.

1. **Blank & background fluorescence handling**
  1. Subtract blank absorbance per *`Condition`* using either a numeric value(s) or a designated string label  in *`Strain`* column.

$$ Absorbance = Abs - Abs_{blank} $$

  1. Subtract background fluorescence intensity and compute the fluorescence signal as:

$$ Fluorescence = FI_{fp} − FI_{bg} $$

1. **Biomass normalization & variance-stabilisation**
  1. Derive the *`Lipid`* signal as:

$$ Lipids = \frac{Fluorescence}{Absorbance} $$

  1. Variance stabilisation:

$$ Ln(Lipids) = Ln(\frac{Fluorescence}{Absorbance}) $$

1. **Plate-level QC**
  1. Detect outliers per *`Strain`* × *`Condition`*  using one of the implemented methods IQR (default), Z-score or MAD-median available.
  1. Provide convenience plots (histograms, strip+box, strip+violin, QQ-plot, heatmaps) to review data quality.

1. **Standard-curve fitting & method agreement (optional)**
  Calibrate NileRedQuant `Lipids` signal to a reference method per `Condition`.
  The `method='auto'` selects among implemented linear regressions:
  1. ODR (errors-in-variables / Deming) when both axes have replicate SE or a stable variance ratio $\lambda = \frac{\sigma_x^2}{\sigma_y^2}$ can be estimated.
  1. WLS when all reference groups (`Strain` × `Condition`) are singletons, and for each group the within-group variance of the reference method can be computed.
  WLS uses weights proportional to its inverse: ($\text{weights} \propto n/\text{variance}$).Falls back to OLS if weights aren’t available
  (variance missing or fewer than 3 positive, finite weights remain).
  1. Passing–Bablok (non-parametric, robust) fallback method when not enough SE on both axes or no stable λ are available.

  Outputs include per-Condition slope/intercept, predictions written back to your data, and optional standard-curve & Bland–Altman plots.

### Citing

Please cite the peer-reviewed article describing full methodological details and validation of NileRedQuant.

   > [Authors] (2025). ***NileRedQuant: Automated analysis and calibration of Nile red plate assays for neutral lipid quantification in yeasts***. [Link text - doi]()

## Installation

Users (PyPI)
```bash
   pip install nileredquant
```

Developers (editable install)::
```bash
  # Clone the repo
   git clone https://github.com/zganjarmia/NileRedQuant
   cd NileRedQuant

   # Create a separate environment & install
   python -m venv .venv && source .venv/bin/activate
   pip install -e .
```

Supported Python versions: 3.9–3.11

*Dependencies:*
- pandas (≥2.2.0),
- scipy (≥1.11.4),
- penguin (≥0.5.3),
- matplotlib (≥3.8.0)
- openpyxl (≥3.1.2)



## Quickstart

Import `NileRedQuant`
```python
  from nileredquant import utils, analyse, standard_curve, qc
```


```python
  # Import data .csv file
  data = utils.read_file(filename="./raw_data.csv")

  # Or Excel
  data = utils.read_file(
    filename="./raw_data.xlsx",
    sheet_name=None  # <-- First sheet is taken, if column name not provided
  )
```

Analayse the data and compute the `Lipids` [RFU] & `Log(Lipids)` [Log[RFU]] variables.

```python
  # `B` value represents the unique identifier of the `Blank` in `Strain` column.
  data, data_wo_outliers, outilers =  analyse.analyse(
    filename=data,  # Can be either Path or pandas.DataFrame
    blanks="B",
    contamination_thr=0.2,
    outlier_method='IQR',
    outlier_columns=['Lipids'],   # detect outliers only in the `Lipids` variable
    save = True)
```


Prepare standard curve of control strains & predict values for other strains in data frame.

```python

  # Import data of reference method (e.g. gravimetric, TLC, ...)

  data_reference_method = utils.read_file(filename="./data_example_reference_method.csv")

  # Fit standard curve & predict
  data_predicted, agreement_table =  standard_curve.fit_standard_curve(
    df_method1=data,
    df_method2=data_reference_method,
    m1_column='Lipids',
    m2_column="TLC_mg/gCDW",
    method='auto',
    plot=True,
    save=True,
  )
```
See **[usage_examples/](./usage_examples/)** for more details.

## Documentation
The API reference is available in the  [usage_examples/00_API.html](./usage_examples/00_API.html) file.

Browse the [usage_examples/](./usage_examples/) directory for end-to-end workflows and function-level demos. Each example is self-contained and runnable with the provided data once dependencies are installed.


## License

MIT © 2025 Mia Žganjar. See ``LICENSE``.

