Metadata-Version: 2.4
Name: kriterion
Version: 0.1.1
Summary: Library for signal detection theory analysis.
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: signal-detection,psychophysics,roc,psychometrics
Author: L
Author-email: 56237933+lcdunne@users.noreply.github.com
Requires-Python: >=3.12
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Dist: numpy (>=2.4.6,<3.0.0)
Requires-Dist: scipy (>=1.17.1,<2.0.0)
Project-URL: Documentation, https://kriterion.readthedocs.io
Project-URL: Homepage, https://kriterion.readthedocs.io
Project-URL: Issues, https://github.com/lcdunne/kriterion/issues
Project-URL: Repository, https://github.com/lcdunne/kriterion
Description-Content-Type: text/markdown

# Kriterion

![Kriterion logo](https://raw.githubusercontent.com/lcdunne/kriterion/main/docs/images/logo/library_logo_fixed.png)

**Kriterion** is a Python library for analysing data using [signal detection theory](https://en.wikipedia.org/wiki/Detection_theory).

Key features:

- Compute sensitivity and bias measures: d', c and more
- Fit detection models to ROC data
- Assess model fits

## Installation

It is recommend to use a virtual environment when installing python packages ([see here](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)). Then:

```sh
python -m pip install kriterion
```

## Dependencies

- NumPy
- SciPy

## Usage

Check [the docs](https://kriterion.readthedocs.io) for more details.

### Example 1: Basic signal detection theory measures

With a single true positive and false positive rate, return all common detection measures:

```python
from kriterion.measures import compute_performance


result = compute_performance(tpr=0.75, fpr=0.21)
print(result)
```

```python title="Out"
Performance(
    tpr=0.75,
    fpr=0.21,
    d_prime=1.480910997214322,
    a_prime=0.850886075949367,
    c_bias=0.06596574841107933,
    beta=1.1026202605581668,
    a_z=None
)
```

### Example 2: Receiver operating characteristic (ROC) modelling

Given a set of rating-scale responses to signal and noise trials:

```python
from kriterion.data import ROCData
from kriterion.fit import fit
from kriterion.models import  UnequalSignalDetection


data = ROCData(
    # Strongest "signal" <---> Strongest "noise"
    # All responses to signal-present trials
    signal=[505, 248, 226, 172, 144, 93],
    # All responses to signal-absent (i.e. noise) trials
    noise=[115, 185, 304, 523, 551, 397],
)

uvsdt = UnequalSignalDetection(data)

result = fit(uvsdt)
```

```python title="Out"
print(uvsdt.parameters)
{
    'd': 1.1830254066861041,
    'signal_sd': 1.337287925732202,
    'c0': 1.0405303717702958,
    'c1': 0.46634923592441596,
    'c2': -0.06932116955166004,
    'c3': -0.6973808897916125,
    'c4': -1.4561271120010804
}

print(result)
ModelSummary(
    dof=3,
    chi2=9.183606301259807,
    chi2_p=0.02694676677704899,
    g2=9.305614752213955,
    g2_p=0.02549179488508846,
    log_likelihood=-5761.067476662813,
    aic=11536.134953325625,
    bic=11579.184187136441,
    sse=0.0004422615018773785
)
```

![uvsdt-fit](https://raw.githubusercontent.com/lcdunne/kriterion/main/docs/images/examples/uvsdt_fit.png)

## License

This project is licensed under the terms of the GPL-3.0 license.

