Metadata-Version: 2.4
Name: aoutools
Version: 0.2.0
Summary: A library of tools for analyzing All of Us data.
Author-email: Jaehyun Joo <jaehyunjoo@outlook.com>
License: MIT License
        
        Copyright (c) 2025 Jaehyun Joo
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/dokyoonkimlab/aoutools
Project-URL: Repository, https://github.com/dokyoonkimlab/aoutools
Project-URL: Issues, https://github.com/dokyoonkimlab/aoutools/issues
Project-URL: Documentation, https://aoutools.readthedocs.io
Keywords: all-of-us,genomics,bioinformatics,prs,hail
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.2
Requires-Dist: google-cloud-storage>=2.13
Requires-Dist: packaging
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Dynamic: license-file

> **Disclaimer:** This project is **not affiliated with, endorsed by, or
> sponsored by** the *All of Us Research Program*. The software is provided
> **as is, without warranty of any kind**. It is in an **early stage of
> development**, and its functions, APIs, and signatures may change
> periodically. You are responsible for checking that any results it produces
> are correct before relying on them.

# aoutools: Tools for All of Us Researcher Workbench

aoutools is a Python library designed to simplify common analysis tasks on the
All of Us Researcher Workbench.

**aoutools targets Researcher Workbench 2.0.** Version 0.2.0 is the first
release for it, adding helpers (`init_hail`, `get_vds_path`) that wire up the
new VDS location and Hail setup. Releases 0.1.x targeted Workbench 1.0, which
was decommissioned on June 30, 2026.

The library currently focuses on the `aoutools.prs` submodule, which offers
convenient functions for:

1.  **Reading PRS Weights Files:** A flexible reader that can handle various
    file formats, both with and without headers.
2.  **Calculating PRS:** A cost-efficient strategy for calculating PRS directly
    on the All of Us VDS, with support for batch mode to calculate multiple
    scores at once.

You can install `aoutools` via `pip` using either the Python Package Index
(PyPI) or its GitHub repository. On the All of Us Researcher Workbench, you can
run the following commands directly in a Jupyter Notebook cell.

```bash
# 1. From PyPI
!pip install aoutools

# 2. From Github
!pip install git+https://github.com/dokyoonkimlab/aoutools.git
```

Please check the online [aoutools
Documentation](https://aoutools.readthedocs.io) for how-to guides and API
reference.

## Development

Assumes [pixi](https://pixi.sh) and [direnv](https://direnv.net) are already
installed.

```bash
pixi install          # build the env from pixi.lock
direnv allow          # auto-activate it on cd into the repo (once per clone)
pixi run setup-hooks  # install the ruff pre-commit hooks (once per clone)
```

Tests come in three tiers (see [`tests/README.md`](tests/README.md) and
[`notebooks/README.md`](notebooks/README.md)):

```bash
pixi run -e ci test                        # mocked hail; linux-64 only
pixi run -e integration test-integration   # real hail; macOS or Linux
```

The mocked tier checks that the code calls the right `hail` methods; the
integration tier runs real `hail` and asserts actual scores. A third tier —
the notebooks in `notebooks/` — is run by hand on the Workbench before a release
to validate against the real *All of Us* data. Changes to scoring logic should
land with an integration test.

```bash
pixi run docs         # build the Sphinx HTML docs
pixi run lint         # ruff lint + format check (what CI runs)
pixi run format       # auto-fix and format
```

Notable changes are recorded in [`CHANGELOG.md`](CHANGELOG.md).

Formatting is enforced by `ruff format`. The bulk-reformat commit is listed in
`.git-blame-ignore-revs`; to skip it in local blame, run
`git config blame.ignoreRevsFile .git-blame-ignore-revs` (GitHub applies it
automatically).
