Update HIVdb from version 9.4 to 9.8

docs/contrib.md

@@ -154,6 +154,80 @@ original theme project.
 [Ruby Version Manager]: https://rvm.io/rvm/install
 [Bulma Clean Theme]: https://github.com/chrisrhymes/bulma-clean-theme
 
+### Updating HIVdb
+
+When a new version of the Stanford HIV Drug Resistance Database is released,
+follow these steps to update MiCall:
+
+1. **Download the new rules file**: Visit [https://hivdb.stanford.edu/](https://hivdb.stanford.edu/)
+   and download the latest XML algorithm file. The file can typically be found
+   in the algorithm/downloads section or by searching for "ASI XML" or "algorithm XML".
+
+2. **Note the version details**: Record the version number (e.g., 9.8) and the
+   modification date from the XML file or the HIVdb website.
+
+3. **Add the new XML file**: Place the downloaded XML file in `micall/resistance/`
+   with the naming convention `HIVDB_X.X.xml` (e.g., `HIVDB_9.8.xml`).
+
+4. **Update `HIV_RULES_PATH`**: In `micall/resistance/resistance.py`, update
+   the path to point to the new XML file:
+   ```python
+   HIVDB_VERSION = 'X.X'
+   HIV_RULES_PATH = os.path.join(os.path.dirname(__file__), f'HIVDB_{HIVDB_VERSION}.xml')
+   ```
+
+5. **Update version in genreport**: In `micall/resistance/genreport.yaml`,
+   update the version number and modification date in the `generated_by_text`
+   field (look for "Stanford HIVdb"):
+   ```yaml
+   generated_by_text: >
+     Generated by MiCall {} on Illumina BaseSpace using Stanford HIVdb
+     X.X, modified on YYYY-MM-DD.
+   ```
+
+6. **Handle new drugs** (if applicable): If the new HIVdb version introduces
+   new drugs, add them to the appropriate drug class in `genreport.yaml`.
+   For example, to add a new INSTI drug:
+   ```yaml
+   INSTI:
+     - [BIC, Bictegravir]
+     - [NEW, New Drug Name]  # Add new drug here
+     - [DTG, Dolutegravir]
+   ```
+   Use the format: `[ABBREVIATION, Full Drug Name]`. The order determines how
+   drugs appear in the report.
+
+7. **Check pyvdrm compatibility**: Verify the current pyvdrm version in
+   `pyproject.toml` supports the new HIVdb version. The pyvdrm library parses
+   the HIVdb XML format. If compatibility issues arise:
+   - Check the [pyvdrm repository](https://github.com/cfe-lab/pyvdrm) for updates
+   - Update the version in `pyproject.toml` if needed:
+     ```toml
+     "pyvdrm @ git+https://github.com/cfe-lab/[email protected]"
+     ```
+
+8. **Update tests**: Modify test files to reflect the new version and any
+   algorithm behavior changes:
+   - `micall/tests/test_resistance.py`: Update version number assertions
+   - `micall/tests/test_asi_algorithm.py`: Update expected resistance scores
+     if the algorithm produces different results
+
+9. **Run tests**: Execute the test suite to ensure everything works:
+    ```shell
+    pytest micall/tests/test_resistance.py
+    pytest micall/tests/test_asi_algorithm.py
+    pytest  # Run all tests
+    ```
+
+10.  **Manual verification**: Process a sample dataset through the pipeline and
+    review the generated resistance reports to ensure output is correct and
+    formatting is preserved.
+
+**Note on CA (Capsid) region**: Some HIVdb versions include the CA region for
+Capsid Inhibitors. If present and not yet supported in MiCall, the region is
+automatically skipped by the `get_algorithm_regions()` function in
+`resistance.py`. Decide whether to add CA support based on clinical needs.
+
 ### Releases
 This section assumes you already have a working server up and running, and you
 just want to publish a new release. If you're setting up a new server, follow