Metadata-Version: 2.4
Name: brine-equalizer
Version: 0.2.0
Summary: Computes BRINE (Blind Resolvent-based Iterative Noise Equalizer) and related low rank approximations of the input data
Keywords: BRINE,Dyson Equalizer,low rank approximation
Author-email: Boris Landa <boris.landa@yale.edu>, Francesco Strino <francesco.strino@pcmgf.com>, Yuval Kluger <yuval.kluger@yale.edu>, Fabio Parisi <fabio.parisi@pcmgf.com>, Ruiqi Li <ruiqi.li@yale.edu>
Maintainer-email: Francesco Strino <francesco.strino@pcmgf.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: BSD License
Classifier: Intended Audience :: Science/Research
License-File: LICENSE
Requires-Dist: matplotlib>=3.6
Requires-Dist: numpy>=1.25
Requires-Dist: scikit-learn>=1.2.2
Requires-Dist: pytest ; extra == "dev"
Requires-Dist: flit_core ; extra == "dev"
Requires-Dist: flit_scm ; extra == "dev"
Project-URL: Bug Tracker, https://github.com/KlugerLab/BRINE/issues
Project-URL: Documentation, https://klugerlab.github.io/BRINE
Project-URL: Repository, https://github.com/KlugerLab/BRINE.git
Provides-Extra: dev

# BRINE #

This package is a Python implementation of BRINE (Blind
Resolvent-based Iterative Noise Equalizer), a data-driven procedure that iteratively rescales the
rows and columns of the observed matrix to equalize the average noise variance across both
dimensions.

The method builds on the Dyson Equalizer, described in detail in the article [The Dyson Equalizer: Adaptive Noise Stabilization for Low-Rank Signal Detection and Recovery
](https://doi.org/10.48550/arXiv.2306.11263). 

The documentation is available at [https://klugerlab.github.io/BRINE](https://klugerlab.github.io/BRINE).

## Installation ##
The main version of the package can be installed as 
```
pip install brine-equalizer
```

The development version of the package can be installed as 
```
pip install git+https://github.com/Klugerlab/BRINE.git
```

## Getting started ##

To import the package and apply BRINE to a test matrix

```python
from brine.examples import generate_Y_with_heteroskedastic_noise
from brine.brine import BRINE

Y = generate_Y_with_heteroskedastic_noise()
brine = BRINE(Y).run()

```

The `BRINE` result class will contain the following attributes
- `Y`: The original data matrix
- `x_scale`: The row scaling factors
- `y_scale`: The column scaling factors
- `Y_hat`: The normalized data matrix so that the variance of the error is 1
- `X_bar`: The estimated signal matrix. It has rank `r_hat`
- `r_hat`:  The estimated rank of the signal matrix
- `S`: The principal values of the data matrix `Y`
- `S_hat`:  The principal values of the data matrix `Y_hat`

The original, non-iterative `DysonEqualizer` is still available (`brine.dyson_equalizer.DysonEqualizer`)
for one-shot use or comparison against BRINE.

Detailed examples are available on the [Examples](https://klugerlab.github.io/BRINE/examples.html) 
page.

