Metadata-Version: 2.4
Name: gwas-sumstats-parser
Version: 0.9.0
Summary: Vocabulary, parsing and standardisation for GWAS summary-statistics files
Author-email: Chris Finan <c.finan@ucl.ac.uk>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://cfinan.gitlab.io/gwas-sumstats-parser
Project-URL: Repository, https://gitlab.com/cfinan/gwas-sumstats-parser
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: mpmath
Provides-Extra: io
Requires-Dist: rapidgzip; extra == "io"
Requires-Dist: pysam>=0.17; extra == "io"
Provides-Extra: frame
Requires-Dist: pandas; extra == "frame"
Requires-Dist: tqdm; extra == "frame"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-dependency; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: bump2version; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pandas; extra == "dev"
Requires-Dist: tqdm; extra == "dev"
Dynamic: license-file

# gwas-sumstats-parser

__version__: `0.9.0`

gwas-sumstats-parser is a small Python library that reads GWAS
summary-statistics flat files into a standard column vocabulary, parses and
validates the values, and yields mutable scalar list rows. It is designed as
the shared ingest layer for
[merit](https://gitlab.com/cfinan/merit) and
[gwas-norm](https://gitlab.com/cfinan/gwas-norm): both consume it, neither
depends on the other.

It provides:

1. **A column vocabulary.** The canonical names for the quantities a
   summary-statistics file can carry (chromosome, position, alleles, effect
   size, standard error, p-value, allele frequency, sample sizes and so on).
   Callers explicitly map these names to source headers; aliases are not guessed.
2. **Value parsers.** Chromosome naming, allele strings, missing-value tokens
   and numeric fields, each
   with a stated rule for what is accepted, what is repaired and what is
   rejected.
3. **Scalar list-row reading.** The current reader handles directly supplied
   linear and ratio effects and retains probability and its negative base-ten
   logarithm. Sample counts can be derived from case and control counts or
   supplied globally. Allele frequencies can be derived from diploid allele
   counts or minor-allele information. Probability conversion and missing-value
   repair are supported, along with confidence intervals, t statistics,
   quantitative scores, approximate log odds and calibrated direction effects.
   No array bindings, pandas dependency or compiled parser are used.
4. **Explicit row failures.** The base reader raises a shared error with the
   original value and source row. The dropping reader skips bad rows and
   exposes failure records and counts grouped by failing method.

## What it is not

- It is **not** a normalisation pipeline. Liftover, rsID mapping, variant
  validation, bad-row files and output formatting stay in gwas-norm.
- It is **not** an analysis package. Instrument selection, Mendelian
  randomisation and colocalisation stay in merit.
- It is **not** related to the EBI GWAS Catalog's `gwas-sumstats-tools`,
  `gwas-sumstats-validator` or `gwas-sumstats-harmoniser`, despite the
  shared prefix. Those tools target the GWAS Catalog's own submission
  format. This package targets the heterogeneous files that arrive from
  consortia and individual studies, and standardises them for downstream
  Python analysis.

There is [online](https://cfinan.gitlab.io/gwas-sumstats-parser/index.html)
documentation for gwas-sumstats-parser.

## Installation instructions

Installation can be via pip or conda:

Pip:

```
pip install gwas-sumstats-parser
```

Conda:

```
conda install -c conda-forge -c bioconda -c cfin gwas-sumstats-parser
```

Runtime dependencies are `numpy`, `scipy` and `mpmath`. The optional `io`
extra installs `rapidgzip` and `pysam>=0.17` for faster gzip decoding and
indexed input:

```bash
pip install "gwas-sumstats-parser[io]"
```

The optional `frame` extra installs `pandas` and `tqdm` for the data frame
function `read_gwas` (see [Reading into a pandas data frame](https://cfinan.gitlab.io/gwas-sumstats-parser/user_guides/data_frames.html)):

```bash
pip install "gwas-sumstats-parser[frame]"
```

Reading caller-owned streams does not require those extras or either
consumer package.

Supported CPython versions are 3.11 through 3.13; development is on 3.13.

### Developer install

Clone the repository and install it in editable mode with the development
extras:

```
git clone git@gitlab.com:cfinan/gwas-sumstats-parser.git
cd gwas-sumstats-parser
python -m pip install -e ".[dev]"
```

Then run the tests from the repository root:

```
pytest tests
```

## Next steps

The full documentation is
[online](https://cfinan.gitlab.io/gwas-sumstats-parser/). Start with the
[TLDR](https://cfinan.gitlab.io/gwas-sumstats-parser/tldr.html), then the
user guide, which has one page per subject:

- [The standard column names](https://cfinan.gitlab.io/gwas-sumstats-parser/user_guides/column_names.html) - every name a mapping can use, what it holds and whether it can be mapped.
- [Opening input files](https://cfinan.gitlab.io/gwas-sumstats-parser/user_guides/opening_files.html) - plain, compressed and indexed input.
- [Regions and filters](https://cfinan.gitlab.io/gwas-sumstats-parser/user_guides/regions_and_filters.html) - genomic regions, row filters, repeated sites and progress.
- [Files that hold many studies](https://cfinan.gitlab.io/gwas-sumstats-parser/user_guides/many_studies.html) - keep one study's rows from a shared file.
- [Checking the genome assembly](https://cfinan.gitlab.io/gwas-sumstats-parser/user_guides/assembly_check.html) - which genome build an indexed file follows.
- [Reading rows](https://cfinan.gitlab.io/gwas-sumstats-parser/user_guides/reading_rows.html) - the reader, its rows and how each value is parsed.
- [Reading into a pandas data frame](https://cfinan.gitlab.io/gwas-sumstats-parser/user_guides/data_frames.html) - `read_gwas`, parsed rows and refused rows.

What changed in each release is in the
[changelog](https://gitlab.com/cfinan/gwas-sumstats-parser/-/blob/master/CHANGELOG.md).

## Command endpoints

None yet. The package is a library first; command-line endpoints will be
listed here when they are added.

## Project documentation

For contributors: the design, plans, specifications and known issues live
in the repository, under `resources/agent-docs/`. Start with
[PROJECT.md](https://gitlab.com/cfinan/gwas-sumstats-parser/-/blob/master/resources/agent-docs/PROJECT.md).
