XChemAlign Developer Guide

Tools to generate data suitable for loading into Fragalysis.

Prerequisites

Python 3.10 or Python 3.11. 3.12 is NOT yet supported.

Getting started (to contribute)

Project dependencies are defined in the pyproject.toml file.

You will need to use Python 3.10 or 3.11 (a requirement of the pyproject.toml file). Python 3.12 cannot currently be used.

If you prefer to use conda you can create a Python 3.10 environment using the environment.yaml in this project, otherwise, if you have Python 3.10 or 3.11, you can create an environment using the built-in venv module: -

python -m venv venv
source venv/bin/activate
pip install --upgrade pip

Make sure you create the venv using Python 3.10 or 3.11 (e.g. change the first command to python3.11 -m venv venv if needed).

From your clean virtual environment you can now install the run-time and development dependencies like this: -

pip install -e .[dev]

The project also relies on CI that is run in GitHub using the actions defined in the files you’ll find in the .github/workflows directory.

We also require the use of the Git pre-commit framework. To get started review the pre-commit utility and then install the pre-commit hooks with the command: -

pre-commit install

Now the project’s rules will run on every commit, and you can check the current health of your clone with: -

pre-commit run --all-files

Tools

The main tools are implemented as the following Python modules:

Copier: xchemalign/copier.py
Collator: xchemalign/collator.py
Aligner: xchemalign/aligner.py

Rollout

There is an environment at Diamond where users run the XChem align code on their data. This can be found on the Diamond file system at /dls/science/groups/i04-1/software/xchem-align. To roll out a new version of this:

Check that the repos are up to date on the master (XCA) and main (LNA) branches.
Test locally
Tag the XCA repo and push the tag: git tag 1.2.3 and git push origin 1.2.3 (using the appropriate tag number)
ssh to Diamond and move into the /dls/science/groups/i04-1/software/xchem-align dir
git pull - update the repo
git tag - check you have the expected tag
rm -rf env_xchem_align - remove the old conda environment
conda deactivate - deactivate the current conda env (if necessary)
conda env create -f environment.yaml -p env_xchem_align - create the new conda environment

NOTE: the repo MUST be tagged before rolling out to users. Step 3 does this and is assumed to be done by the developers. If you want to roll out a new environment and the repo is not tagged follow the instructions below

Rollout if no tag is made yet

ssh to Diamond and move into the /dls/science/groups/i04-1/software/xchem-align dir
git pull - update the repo
git tag - check you have the expected tag
Tag the XCA repo and push the tag: git tag 1.2.3 and git push origin 1.2.3 (using the appropriate tag number)
rm -rf env_xchem_align - remove the old conda environment
conda deactivate - deactivate the current conda env (if necessary)
conda env create -f environment.yaml -p env_xchem_align - create the new conda environment

Staging environment rollout

There is a staging environment at Diamond where users run a test version the XChem align code on their data. This can be found on the Diamond file system at /dls/science/groups/i04-1/software/xchem-align-staging. This code is not tagged and data should only be uploaded to the staging Fragalysis. Production Fragalysis will refuse to load data from a non-tagged version of XCA.

The procedure for rolling out to the staging environment is identical to for the production site described above, except that you do this in the xchem-align-staging directory. Ensure you checkout the required branch or tag before building the conda environment.