PR to bring HLAfreq 0.0.5

.github/dependabot.yml

@@ -0,0 +1,19 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 14
+  - package-ecosystem: "github-actions" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 14

.github/workflows/docs.yaml

@@ -0,0 +1,52 @@
+name: website
+
+# build the documentation whenever there are new commits on main
+on:
+  push:
+    branches:
+      - main
+    # Alternative: only build for tags.
+    # tags:
+    #   - '*'
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      # ADJUST THIS: install all dependencies (including pdoc)
+      - run: pip install -e .
+      - run: pip install pdoc
+      - run: pip install jupyter
+      # ADJUST THIS: build your documentation into docs/.
+      # We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here.
+      # - run: python docs/make.py
+      - run: pdoc -d google -o docs/ HLAfreq
+      - run: jupyter nbconvert --to html --output-dir docs/HLAfreq/examples examples/*.ipynb
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/
+
+  # Deploy the artifact to GitHub pages.
+  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

.github/workflows/python-package.yaml

@@ -0,0 +1,43 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Python package
+
+on:
+  push:
+    branches: [ "main", "dev" ]
+  pull_request:
+    branches: [ "main", "dev" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+    - uses: actions/checkout@v6
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install flake8 pytest pytest-cov
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - name: Install HLAfreq
+      run: |
+        pip install .
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Test with pytest
+      run: |
+        pytest --cov=HLAfreq

.gitignore

@@ -0,0 +1,9 @@
+data/
+writeup/
+*__pycache__/
+*.code-workspace
+envs/.venv
+build/
+dist/
+src/*.egg-info/
+.coverage

CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Community guidelines
+Thank you for using `HLAfreq`!
+It's great that you'd like to contribute in any form!
+Asking questions as issues is an important contribution.
+See below for particular information to include. If you see an
+issue you can help with, your answer would be greatly appreciated.
+When creating or answering issues please be kind!
+
+## Seek support
+If you need help using this tool, the first port of call is the
+examples and documentation [here](https://barinthusbio.github.io/HLAfreq/HLAfreq.html).
+But if the answer is not there, please open an [issue](https://github.com/BarinthusBio/HLAfreq/issues).
+
+## Report problems with the software
+If the software isn't working or you think you've found a bug,
+please open an [issue](https://github.com/BarinthusBio/HLAfreq/issues). Please include:
+- the version of `HLAfreq`
+- code to reproduce the error
+- any error message/the result
+- what you expected/think should have happened instead
+
+## Contribute to the software
+If you want to add to `HLAfreq` that's great! Fork the
+repo and create a branch named after the change you're making.
+Make your contribution to the new branch on your fork and add
+tests to verify that your code runs as expected. The tests should
+pass when run by nox before submitting a pull request. See this
+[guide](https://learn.scientific-python.org/development/guides/tasks/)
+on using nox.
+
+When you're happy with your changes and the tests are passing,
+submit a pull request. In the pull request describe the motivation
+for your changes, their impact, and the tests you have written for
+them.
+
+# Thank you for contributing!

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Vaccitech PLC
+
+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.

README.md

@@ -0,0 +1,178 @@
+# HLAfreq
+
+`HLAfreq` allows you to download and combine HLA allele
+frequencies from multiple datasets, e.g. combine data from
+several studies within a country or combine countries.
+Useful for studying regional diversity in immune genes
+and, when paired with epitope prediction, estimating a population's
+ability to mount an immune response to specific epitopes.
+
+Automated download of allele frequency data download from 
+[allelefrequencies.net](https://www.allelefrequencies.net/).
+
+Full documentation at [HLAfreq/docs](https://BarinthusBio.github.io/HLAfreq/HLAfreq.html). Source code is available at [BarinthusBio/HLAfreq](https://github.com/BarinthusBio/HLAfreq).
+
+## Details
+Estimates are combined by modelling allele frequency as a 
+Dirichlet distribution which defines the probability of drawing each
+allele. When combining studies their estimates are weighted as 2x sample size by
+default. Sample size is doubled as each person in the study
+contributes two alleles. Alternative weightings can be used,
+for example population size when averaging across countries.
+
+When selecting a panel of HLA alleles to represent a population,
+allele frequency is not the only thing to consider. Depending on
+the purpose of the panel, you should include a range of loci and
+supertypes (grouped alleles sharing binding specificies).
+
+## Install
+`HLAfreq` is a `python` package available on windows, mac, and linux. We recommend installing
+with `conda`.
+```
+conda create -n hlafreq bioconda::hlafreq
+conda activate hlafreq
+```
+
+### Troubleshooting
+`HLAfreq` uses `pymc` to estimate credible intervals,
+which is the source of most installation difficulty, see
+[pymc installation guide](https://www.pymc.io/projects/docs/en/stable/installation.html) and [tips and tricks](https://conda-forge.org/docs/user/tipsandtricks/#using-multiple-channels).
+
+You may see an error about g++ and degraded performance:
+```
+WARNING (pytensor.configdefaults): g++ not detected!  PyTensor will be unable to compile C-implementations and will default to Python. Performance may be severely degraded. To remove this warning, set PyTensor flags cxx to an empty string.
+```
+
+This means that one of the pymc backends is missing and estimating confidence
+intervals will be very slow. But don't worry, try one of these fixes below:
+
+- Set the channel priority to strict, then install as above (using conda-forge then bioconda channels).
+```
+conda config --set channel_priority strict
+```
+
+- Install a conda compiler to handle g++ based on your os.
+```
+conda create -n hlafreq -c conda-forge -c bioconda hlafreq cxx-compiler
+```
+
+When running entire scripts on windows, you may see an error about
+"Safe importing of main module", multiprocessing, and starting
+new processes. To fix this, main guard your code with
+`if __name__ == "__main__":` after the `import`s as demonstrated in
+[`examples/quickstart.py`](https://github.com/BarinthusBio/HLAfreq/blob/main/examples/quickstart.py).
+
+If you do run into trouble please open an [issue](https://github.com/BarinthusBio/HLAfreq/issues).
+
+### conda
+If you're new to conda see the miniconda [installation guide](https://conda.io/projects/conda/en/stable/user-guide/install/index.html) and [documentation](https://docs.conda.io/projects/conda/en/stable/user-guide/index.html)
+to get started with `conda`.
+
+Enter the install command from above into your conda prompt to create and
+activate a conda environment with `HLAfreq` installed.
+Typing `python` into this activated environment will start
+a python session where you can enter your python code such as
+the HLAfreq [minimal example](#minimal-example) below.
+
+If you prefer to write your python code as scripts using an IDE such as
+PyCharm or VScode, you'll need to look up how to configure a conda
+virtual environment with those tools.
+
+### pip
+If you don't intend to use credible intervals you can install
+with pip: `pip install HLAfreq`.
+However, if you do import `HLAfreq_pymc` you may get warnings
+about degraded performance.
+
+See the [pip documentation](https://pip.pypa.io/en/stable/)
+to get started with pip. If you do have issues with pip,
+try installing with conda as described above.
+
+## Minimal example
+Download HLA data using `HLAfreq.HLAfreq.makeURL()` and `HLAfreq.HLAfreq.getAFdata()`.
+All arguments that can be specified in the webpage form are available,
+see the [`makeURL()` docs](https://barinthusbio.github.io/HLAfreq/HLAfreq/HLAfreq.html#makeURL) for details.
+```
+import HLAfreq
+base_url = HLAfreq.makeURL("Uganda", locus="A")
+aftab = HLAfreq.getAFdata(base_url)
+```
+
+After downloading the data, it must be filtered so that all studies
+sum to allele frequency 1 (within tolerence). Then we must ensure
+that all studies report alleles at the same resolution.
+Finaly we can combine frequency estimates, for more details see
+the [`combineAF()` api documentation](https://barinthusbio.github.io/HLAfreq/HLAfreq/HLAfreq.html#combineAF).
+```
+aftab = HLAfreq.only_complete(aftab)
+aftab = HLAfreq.decrease_resolution(aftab, 2)
+caf = HLAfreq.combineAF(aftab)
+```
+
+To add confidence intervals to estimates see
+[`examples/quickstart.py`](https://github.com/BarinthusBio/HLAfreq/blob/main/examples/quickstart.py).
+
+## Detailed examples
+For more detailed walkthroughs see [HLAfreq/examples](https://barinthusbio.github.io/HLAfreq/HLAfreq/examples.html).
+
+- [Single country](https://BarinthusBio.github.io/HLAfreq/HLAfreq/examples/single_country.html) download and combine
+- [Multi-country](https://BarinthusBio.github.io/HLAfreq/HLAfreq/examples/multi_country.html) download and combine, weight by population coverage
+- [Using priors](https://BarinthusBio.github.io/HLAfreq/HLAfreq/examples/working_with_priors.html)
+- [Credible intervals](https://BarinthusBio.github.io/HLAfreq/HLAfreq/examples/credible_intervals.html)
+
+## Docs
+Full documentation at [HLAfreq/docs](https://BarinthusBio.github.io/HLAfreq/HLAfreq.html).
+API documentation for functions are under the submodules on the left.
+- `HLAfreq.HLAfreq` documents most functions, specifically download and combine
+allele data.
+- `HLAfreq.HLAfreq_pymc` is functions using pymc to acurately estimate credible intervals on allele frequency estimates.
+
+For help on specific functions view the docstring, `help(function_name)`.
+
+Run `pdoc -d google -o docs/ HLAfreq` to generate the
+documentation in `./docs`.
+<!-- Documentation generated by pdoc should not be commited
+as it is auto generated by a github action. -->
+
+## Community guidelines
+Thank you for using `HLAfreq`! Contributions in any form
+are immensely helpful: asking questions, answering issues,
+and pull requests are all great.
+
+For full details see [CONTRIBUTING.md](https://github.com/BarinthusBio/HLAfreq/blob/main/CONTRIBUTING.md). In short, if the answer to
+your question is not in the docs, open an [issue](https://github.com/BarinthusBio/HLAfreq/issues). If you'd like to improve `HLAfreq` create a fork and a pull request.
+
+<!-- ## Developer notes
+Install in dev mode
+pip install -e HLAfreq
+pip install -e .
+
+Update version in setup.py
+
+Update documentation with: `pdoc -d google -o docs/ HLAfreq`.
+Note that github actions will automatically run this when pushed
+to `main` branch.
+
+Run tests `pytest`
+Or allow nox to do it `nox`. Nox will also run linting.
+On push github actions will run linting and pytest
+
+Clear old build info
+rm -rf build dist src/*.egg-info 
+
+Build with `python -m build`.
+
+twine check dist/*
+
+Upload to test pypi
+twine upload --repository testpypi dist/*
+
+Install from test pypi
+python3 -m pip install --extra-index-url https://test.pypi.org/simple/ HLAfreq
+
+Upload to pypi
+twine upload dist/*
+-->
+
+## Citation
+Wells, D. A., & McAuley, M. (2023). HLAfreq: Download and combine HLA allele frequency data. bioRxiv, 2023-09. https://doi.org/10.1101/2023.09.15.557761