Metadata-Version: 2.4
Name: replicaverse
Version: 0.0.1
Summary: Evaluation suite for computational psycholinguistics
Author: The REPLICA Team
Author-email: Samuel Kiegeland <samuel.kiegeland@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://replicaverse.org
Project-URL: Documentation, https://replicaverse.org
Project-URL: Repository, https://github.com/replicaverse/replica
Project-URL: Issues, https://github.com/replicaverse/replica/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: pyyaml>=6.0
Requires-Dist: scikit-learn>=1.7
Requires-Dist: scipy>=1.14
Requires-Dist: statsmodels>=0.14
Requires-Dist: pandas>=2.2
Requires-Dist: pyarrow>=14.0
Requires-Dist: huggingface-hub>=0.24
Requires-Dist: certifi>=2024.0
Provides-Extra: models
Requires-Dist: transformers<5,>=4.45; extra == "models"
Requires-Dist: torch>=2.4; extra == "models"
Requires-Dist: accelerate>=1.0; extra == "models"
Provides-Extra: kenlm
Requires-Dist: kenlm>=0.2; extra == "kenlm"
Requires-Dist: mosestokenizer>=1.2; extra == "kenlm"
Provides-Extra: lens
Requires-Dist: replicaverse[models]; extra == "lens"
Requires-Dist: tuned-lens>=0.2; extra == "lens"
Provides-Extra: readers
Requires-Dist: pyreadr>=0.5; extra == "readers"
Requires-Dist: nibabel>=5.0; extra == "readers"
Requires-Dist: openpyxl>=3.1; extra == "readers"
Requires-Dist: xlrd>=2.0.1; extra == "readers"
Provides-Extra: frequency
Requires-Dist: wordfreq[cjk]>=3.0; extra == "frequency"
Provides-Extra: character-surprisal
Requires-Dist: replicaverse[models]; extra == "character-surprisal"
Requires-Dist: genlm-bytes>=0.2.0; extra == "character-surprisal"
Provides-Extra: r
Requires-Dist: rpy2<3.6,>=3.5.11; extra == "r"
Provides-Extra: lmer-rs
Requires-Dist: lme_python>=0.2.5; extra == "lmer-rs"
Requires-Dist: polars>=1.0; extra == "lmer-rs"
Requires-Dist: pandas>=2.0; extra == "lmer-rs"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-socket>=0.7; extra == "test"
Requires-Dist: sacremoses>=0.1.1; extra == "test"
Requires-Dist: nltk>=3.9; extra == "test"
Provides-Extra: zuco
Requires-Dist: h5py>=3.10; extra == "zuco"
Provides-Extra: information-value
Requires-Dist: spacy>=3.7; extra == "information-value"
Requires-Dist: scipy>=1.10; extra == "information-value"
Requires-Dist: nltk>=3.9; extra == "information-value"
Provides-Extra: similarity-surprisal
Requires-Dist: flair>=0.13; extra == "similarity-surprisal"
Requires-Dist: sacremoses>=0.1.1; extra == "similarity-surprisal"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == "viz"
Requires-Dist: pillow>=10.0; extra == "viz"
Provides-Extra: docs
Requires-Dist: quartodoc>=0.11; extra == "docs"
Provides-Extra: typecheck
Requires-Dist: mypy>=1.10; extra == "typecheck"
Provides-Extra: mmc
Requires-Dist: langdetect>=1.0.9; extra == "mmc"
Provides-Extra: dev
Requires-Dist: replicaverse[character-surprisal,frequency,mmc,models,readers,test,typecheck,zuco]; extra == "dev"
Requires-Dist: ruff==0.15.14; extra == "dev"
Provides-Extra: all
Requires-Dist: replicaverse[dev,docs,information-value,kenlm,lens,lmer-rs,mmc,r,similarity-surprisal,test,viz,zuco]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="https://replicaverse.org/assets/wordmark_replica.svg" alt="REPLICA" width="840">
</p>

REPLICA is a toolkit for replication and reproduction in computational
psycholinguistics. It combines dataset loading, feature extraction and
cross-validated model comparison through configurable interfaces.

[Website](https://replicaverse.org) ·
[Datasets](https://replicaverse.org/datasets) ·
[Tutorials](#tutorials) · [Architecture](https://github.com/replicaverse/replica/blob/main/docs/guides/architecture.md) ·
[Contributing](https://github.com/replicaverse/replica/blob/main/CONTRIBUTING.md)

## Install

Use Python 3.11 or newer:

```bash
python -m pip install replicaverse
```

The Python import and command are named `replica`. The base package supports
tabular analysis and precomputed predictors. The getting-started example uses
`replicaverse[models,r]` and requires R with `lme4` for the default mixed-effects
backend. See the [environment guide](https://github.com/replicaverse/replica/blob/main/docs/guides/environment.md) for setup,
optional dependencies and source installation.

## Tutorials

Start with [Getting started](https://github.com/replicaverse/replica/blob/main/docs/tutorials/getting_started.ipynb) to load a
dataset, evaluate a language-model predictor and interpret the results.

| Notebook | Topics |
|---|---|
| [Benchmarking](https://github.com/replicaverse/replica/blob/main/docs/tutorials/benchmarking.ipynb) | Compare datasets and models |
| [Loading datasets](https://github.com/replicaverse/replica/blob/main/docs/tutorials/loading_any_dataset.ipynb) | Catalog, variants and loader options |
| [Segmentation](https://github.com/replicaverse/replica/blob/main/docs/tutorials/segmentation.ipynb) | Character, word and sentence units |
| [Surprisal methods](https://github.com/replicaverse/replica/blob/main/docs/tutorials/surprisal_methods.ipynb) | Compare predictor calculations |
| [Adding a study](https://github.com/replicaverse/replica/blob/main/docs/tutorials/extending_replica.ipynb) | Integrate and validate a study recipe |

Dataset walkthroughs: [eye-tracking](https://github.com/replicaverse/replica/blob/main/docs/datasets/eye_tracking.ipynb),
[self-paced reading](https://github.com/replicaverse/replica/blob/main/docs/datasets/spr.ipynb), [EEG](https://github.com/replicaverse/replica/blob/main/docs/datasets/eeg.ipynb)
and [fMRI](https://github.com/replicaverse/replica/blob/main/docs/datasets/fmri.ipynb).

## Datasets and storage

Explore available datasets with `replica datasets` or the
[catalog](https://replicaverse.org/datasets). Download a supported source with
`replica fetch DATASET`; some sources require manual acquisition or licensed
materials, as described in their catalog entries.

Data and caches use automatic defaults; no path settings are required.
The [environment guide](https://github.com/replicaverse/replica/blob/main/docs/guides/environment.md#data-and-cache-locations)
explains how to change their locations. The
[predictor-store guide](https://github.com/replicaverse/replica/blob/main/docs/guides/predictor-store.md) covers precomputed predictors.

## Contributing

The [architecture guide](https://github.com/replicaverse/replica/blob/main/docs/guides/architecture.md) describes the package and
its extension points. Follow the [contributor guide](https://github.com/replicaverse/replica/blob/main/CONTRIBUTING.md) and
[test guide](https://github.com/replicaverse/replica/blob/main/tests/README.md) to develop and validate changes, then open a PR.

Related projects: [ModelBlocks](https://github.com/modelblocks/modelblocks-release),
[pymovements](https://pymovements.readthedocs.io/en/stable/) and
[EyeBench](https://github.com/EyeBench/eyebench).
