|
6 | 6 |
|
7 | 7 | ## Objective |
8 | 8 |
|
9 | | -This is a Python implementation of the BC-CfE HLA algorithm. This algorithm has |
10 | | -several interpretations, including [BBLab's hla-easy.rb](https://github.com/cfe-lab/bblab-server/blob/main/alldata/hla_class/hla-easy.rb) file. This project aims |
11 | | -to consolidate all of our HLA algorithm versions into a single version. |
| 9 | +This is a Python implementation of the BC-CfE HLA algorithm. This algorithm |
| 10 | +has several implementations, including [BBLab's hla-easy.rb][bblab_hla] file. |
| 11 | +This project aims to consolidate all of our HLA algorithm versions into a |
| 12 | +single version. |
12 | 13 |
|
13 | | -## Testing |
| 14 | +[bblab_hla]: https://github.com/cfe-lab/bblab-server/blob/main/alldata/hla_class/hla-easy.rb |
14 | 15 |
|
15 | | -FIXME |
| 16 | +The `hla_algorithm` Python package provided by this repository exposes some |
| 17 | +executables as well. |
16 | 18 |
|
17 | | -The current validation method is to go to the [BBLab HLA Class tool page](https://hivresearchtools.bccfe.ca/django/tools/hla_class/), upload [test.fasta](https://github.com/cfe-lab/bblab-server/blob/main/tests/test.fasta) in `HLA Type C`, and assert that its output matches [the output kept in version control](https://github.com/cfe-lab/bblab-server/blob/main/tests/hla_class/HLA-C%20batch%20mode%20test%20data%20OUTPUT.csv). |
| 19 | +* [`interpret_from_json`][interpret_from_json]: A bare-bones script that |
| 20 | +performs interpretation on an HLA sequence specified in JSON. |
| 21 | + * This script is also available as `python -m hla_algorithm` (in the |
| 22 | + environment where the module is installed). |
| 23 | +* [`update_alleles`][update_alleles]: Retrieves alleles from IMGT/HLA (or an |
| 24 | +alternative source) and creates a YAML configuration file suitable for use with |
| 25 | +this code. This is used periodically to update our lists of alleles with |
| 26 | +up-to-date information. |
| 27 | +* [`update_frequency_file`][update_frequency_file]: Updates an "old-style" |
| 28 | +HLA frequency file into the format used by this algorithm. |
| 29 | + * As of the time of writing, the frequencies file has unknown origin and has |
| 30 | + never been updated. Under typical operation, you'll likely never use this. |
| 31 | +* [`reformat_old_alleles`][reformat_old_alleles]: Updates "old-style" HLA |
| 32 | +allele lists into a YAML configuration file suitable for use with this code. |
| 33 | +These allele lists may be either "unreduced" (with duplicates remaining) or |
| 34 | +"reduced" (with duplicates collapsed into a single representative). This |
| 35 | +script can be used to update old allele lists that you wish to continue using |
| 36 | +with this code, e.g. if you already have an old implementation of this |
| 37 | +algorithm running somewhere and wish to preserve its functionality. |
18 | 38 |
|
19 | | -## TODO |
| 39 | +[interpret_from_json]: src/hla_algorithm/interpret_from_json.py |
| 40 | +[update_alleles]: src/hla_algorithm/update_alleles.py |
| 41 | +[update_frequency_file]: src/hla_algorithm/update_frequency_file.py |
| 42 | +[reformat_old_alleles]: src/hla_algorithm/reformat_old_alleles.py |
20 | 43 |
|
21 | | -<https://waylonwalker.com/hatch-version/> |
| 44 | +### Ruby wrapper |
| 45 | + |
| 46 | +In addition to the Python module, this repository also contains a Ruby wrapper |
| 47 | +enabling this code to be used in Ruby (through system calls). The Ruby wrapper |
| 48 | +is intended as a drop-in replacement for the Ruby-based HLA algorithm that has |
| 49 | +been used at the CfE for years; once installed, this Ruby module provides an |
| 50 | +`HLAAlgorithm` class with an `analyze` method, as the old code did. |
| 51 | +Additionally, this `HLAAlgorithm` class can optionally be provided with new |
| 52 | +configuration files, so that the alleles (and frequencies, if that ever happens) |
| 53 | +can be updated without having to update the code. |
| 54 | + |
| 55 | +This Ruby module works by simply packing up its inputs into a JSON file and |
| 56 | +invoking `interpret_from_json`. Therefore, the Python module must be installed |
| 57 | +on the system where you're using the Ruby module. |
| 58 | + |
| 59 | +## Installation |
| 60 | + |
| 61 | +This code may be installed from our git repo. For example, using pip: |
| 62 | + |
| 63 | +``` |
| 64 | +pip install git+https://github.com/cfe-lab/hla_algorithm.git@[tag] |
| 65 | +``` |
| 66 | + |
| 67 | +Using uv: |
| 68 | + |
| 69 | +``` |
| 70 | +uv add git+https://github.com/cfe-lab/hla_algorithm.git@[tag] |
| 71 | +``` |
| 72 | + |
| 73 | +### Ruby wrapper |
| 74 | + |
| 75 | +Once the Python module is installed, the Ruby module can be installed from our |
| 76 | +GitHub package repository. First, you need to authenticate with the GitHub |
| 77 | +RubyGems registry. In brief, a personal access token (classic) is required to |
| 78 | +install from this registry (even though our repository is public). Then you |
| 79 | +must update your gem sources/bundler configuration with this token along with |
| 80 | +the username of the token creator. Full details may be found in |
| 81 | +[the GitHub instructions][github_rubygem_auth]. |
| 82 | + |
| 83 | +From there, you can install using either `gem` or via a Gemfile (i.e. with |
| 84 | +`bundler`). Instructions may be found on |
| 85 | +[the GitHub page for the package][github_package_page]. |
| 86 | + |
| 87 | +The Ruby module must be instructed on how to invoke `interpret_from_json`, |
| 88 | +using the environment variable `HLA_INTERPRET_FROM_JSON`. For example, if you |
| 89 | +install Python using `uv` in your project directory (as recommended), then you |
| 90 | +would set this to `uv run interpret_from_json`. If your project is |
| 91 | +Docker-based, then you can set this in your Dockerfile: |
| 92 | + |
| 93 | +``` |
| 94 | +ENV HLA_INTERPRET_FROM_JSON="uv run interpret_from_json" |
| 95 | +``` |
| 96 | + |
| 97 | +[github_rubygem_auth]: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-rubygems-registry |
| 98 | +[github_package_page]: https://github.com/cfe-lab/hla_algorithm/pkgs/rubygems/hla_algorithm |
0 commit comments