asmc-preparedecoding 2.2.5
Prepare decoding quantities for ASMC & FastSMC
Requires Python: >=3.9

[![Unit tests: Ubuntu](https://github.com/PalamaraLab/PrepareDecoding/workflows/Unit%20tests:%20Ubuntu/badge.svg)](https://github.com/PalamaraLab/PrepareDecoding/actions)
[![Unit tests: macOS](https://github.com/PalamaraLab/PrepareDecoding/workflows/Unit%20tests:%20macOS/badge.svg)](https://github.com/PalamaraLab/PrepareDecoding/actions)
[![Regression test](https://github.com/PalamaraLab/PrepareDecoding/workflows/Regression%20test/badge.svg)](https://github.com/PalamaraLab/PrepareDecoding/actions)

[![Static analysis checks](https://github.com/PalamaraLab/PrepareDecoding/workflows/Static%20analysis%20checks/badge.svg)](https://github.com/PalamaraLab/PrepareDecoding/actions)
[![Sanitiser checks](https://github.com/PalamaraLab/PrepareDecoding/workflows/Sanitiser%20checks/badge.svg)](https://github.com/PalamaraLab/PrepareDecoding/actions)
[![codecov](https://codecov.io/gh/PalamaraLab/PrepareDecoding/branch/main/graph/badge.svg)](https://codecov.io/gh/PalamaraLab/PrepareDecoding)

# ASMC Prepare Decoding

Tool to compute decoding quantities.

This is a Python-wrapped C++ project with prebuilt CPython wheels targeting manylinux_2_28 on Linux and macOS 11.0+.

| Platform \ CPython          | ≤3.8 | 3.9 | 3.10 | 3.11 | 3.12 | 3.13 | 3.14 |
|-----------------------------| ---- | --- | ---- | ---- | ---- | ---- | ---- |
| Linux x86_64                | ❌    | ✅   | ✅    | ✅    | ✅    | ✅    | ✅    |
| Linux aarch64               | ❌    | ✅   | ✅    | ✅    | ✅    | ✅    | ✅    |
| macOS Intel (x86_64)        | ❌    | ✅   | ✅    | ✅    | ✅    | ✅    | ✅    |
| macOS Apple Silicon (arm64) | ❌    | ✅   | ✅    | ✅    | ✅    | ✅    | ✅    |


## Quickstart

### Install the Python package from PyPI

Most functionality is available through a Python package which can be installed with:

```bash
pip install asmc-preparedecoding
```

### Example notebook

Examples for using the Python package can be found in the following Jupyter notebook:
- [creating decoding quantities](https://github.com/PalamaraLab/PrepareDecoding/blob/main/notebooks/CreatingDecodingQuantities.ipynb)

Please note that to run the notebook you should first clone the repository and install Jupyter:

```bash
git clone https://github.com/PalamaraLab/PrepareDecoding.git
cd PrepareDecoding

pip install jupyter
jupyter-notebook notebooks/CreatingDecodingQuantities.ipynb
```

### API documentation

A description of the API can be found here:
- [api docs](https://github.com/PalamaraLab/PrepareDecoding/blob/main/docs/api.md)

### File formats

Descriptions of the file formats used can be found here:
- [file formats](https://github.com/PalamaraLab/PrepareDecoding/blob/main/docs/file_formats.md)

## License

This project is currently released under the GNU General Public License Version 3.
# Release Notes

## v2.2.5 (2025-09-26)

Fix some typos and broken links.
No change in functionality.

## v2.2.4 (2025-09-26)

Wheels now available for ARM64 (Linux and macOS).
Wheels now available for Python 3.9-3.14 (inclusive).
No change in functionality.

## v2.2.3 (2023-02-22)

Infrastructure updates and building wheels for newer Python versions.
No change in functionality.

## v2.2.2 (2021-09-28)

Improved documentation, now available [here](https://github.com/PalamaraLab/PrepareDecoding/tree/main/docs).
No change in functionality.

## v2.2.1 (2021-09-01)

Very minor fix to links in documentation.
No change in functionality.

## v2.2 (2021-09-01)

You can now specify discretizations in the following manner:
- as a file: `discretization='/path/to/discretization.disc'` (existing functionality)
- as a number of quantiles, which will be calculated at runtime: `discretization=[100]`
- as a number of pre-specified quantiles plus a number of additional quantiles calculated at runtime: `discretization=[[30.0, 12], [100.0, 15], 39]`
  - this will create 12 discretization points at a spacing of 30.0 (starting from 0.0), followed by 15 at a spacing of 100, followed by 39 additional quantiles

You can now specify built-in frequencies information. Currently, the only supported frequencies are from UKBB. Frequencies can now be specified in the following manner:
- as a file: `frequencies='/path/to/frequencies.frq'` (existing functionality)
- as a string: `frequencies='UKBB'`

### Breaking changes

- The Python API has been simplified, and the strong types mentioned in the v2.1 release are no longer required in Python. 
  Please see the Jupyter Notebook for examples of the current API.
- The strong types remain in the C++ API.
  Please see the file `TestPrepareDecoding.cpp` for examples of the C++ library API.
- There is now a single top-level method `prepare_decoding` (Python) and `prepareDecoding` (C++).
  If the CSFS file parameter is a valid file, CSFS will be loaded from file.
  If the CSFS file parameter is an empty string, CSFS will be calculated at runtime.
  
### Other changes

Various other minor changes have been made.

## v2.1 (2021-05-13)

Default demographies are now bundled with Prepare Decoding.
You can now either supply your own demography file, or choose from the following default demographies:
- ACB, ASW, BEB, CDX, CEU, CHB, CHS, CLM, ESN, FIN, GBR, GIH, GWD, IBS, ITU, JPT, KHV, LWK, MSL, MXL, PEL, PJL, PUR, STU, TSI, YRI

### Breaking changes

- When using the C++ or Python libraries, methods that previous specified a demography file as a string now require an instance of a lightweight strong type `Demography`:
  - In C++, to specify a file: `Demography d("/path/to/demography.demo");`
  - In C++, to specify a default: `Demography d("CEU");`
  - In Python, to specify a file: `d = Demography('/path/to/demography.demo')`
  - In C++, to specify a default: `d = Demography('CEU')`
- A default-constructed Demography will use the default CEU.

### Other changes

- None

## v2.0 (2021-04-22)

Computing CSFS values is now bundled with this project, and no longer relies on the optional `smcpp` dependency.

### Breaking changes

- Python method `create_from_precomputed_csfs` is renamed `prepare_decoding_precalculated_csfs`, but it behaves identically.
- Python method `create_from_scratch` is renamed `calculate_csfs_and_prepare_decoding`, and no longer requires the Python package `smcpp`.

### Other changes

- Some floating point numbers in output files are now written with higher precision.

## v1.1 (2021-03-19)

Minor fixes.

### Breaking changes

- None

### Other changes

- Python wheels now also built for Windows as well as macOS and Linux.
- Corrected syntax in package README.

## v1.0 (2021-03-18)

First public release of ASMC Prepare Decoding, with functionality as described and used in [these notebooks](https://github.com/PalamaraLab/PrepareDecoding/tree/main/notebooks).