- Introduction
- Compatibility
- Install
- Getting Started
- Troubleshooting and FAQs
- Other Information
- Legal and Compliance Information
- Updates and Release Notes
Table of contents generated with markdown-toc
A very Canadian utility for genomic clustering and distance querying.
This program is under active development and is used for creating distance matrices from allelic profiles, or for comparing groups of isolates against multiple reference sequences. This program is similar to cgmlst-dists from Torsten Seeman and gas from the Public Health Agency of Canada.
[Matthew Wells] : matthew.wells@phac-aspc.gc.ca
[Eric Marinier] : eric.marinier@phac-aspc.gc.ca
beave has only been tested on Linux, any system that supports G++ can compile the program. As only the C++ 23 standard library is used, the program may be able to be compiled on Windows system.
This program relies heavily on the compiler to optimize the program and add SIMD instructions, it is recommended to compile the program on your local computer to get the full benefit of the potential instruction sets your CPU may offer. Compilation using AVX-512 instruction sets has been tested, however in our testing the programs performance degrades likely due to throttling by the CPU.
To build the beave Python package, you will first need to install dependencies listed in the pyproject.toml file. Python version 3.13 or greater is required, along with scikit-build-core and the nanobind Python package.
Python runtime dependencies include numpy >= 2.4.0 and polars >= 1.40.1 and scipy >= 1.17.0.
Start by pulling the repository.
git clone https://github.com/phac-nml/beave
Currently only linux is supported within bioconda, if you wish to install on OSX please install from pypi for build from source. An issue has been created and OSX on bioconda will be supported in the future.
To install from bioconda simply run conda install -c bioconda beave
Users can install beave from pypi, by simply running pip install beave. If you wish to compile the project from its source code simply enter pip install . in the source code directory.
Developers can run pip install -ve .[dev] or pip install -Ceditable.rebuild=true -ve .[dev]. Further examples can be found in the nanobind documentation here: nanobind packaging. The --no-build-isolation is not included as running uv pip install with the --no-build-isolation flag tells uv to ignore the build-system.requires section from the pyproject.toml.
To build a wheel that can be distributed instead of installed, simply run pip wheel .
-
Pull the GitHub repository as described above.
-
Create the Conda environment by running
conda env create -f environment-linux.ymlfor linux andconda env create -f ./environment-osx.ymlfor mac. -
Activate the environment with:
conda activate beave -
Run
pip install ., if you wish to install development dependencies or run tests please runpip install -ve .[dev]
The main help message for the program is shown below:
>>> beave -h
usage: beave [-h] [--cores CORES] [--delimiter DELIMITER] [--columns-subset COLUMNS_SUBSET] [--count-missing] [--normalize-distance]
[--filter-threshold FILTER_THRESHOLD] [--verbose] [--version]
{cluster,match} ...
A very Canadian utility for genomic clustering and distance querying.
positional arguments:
{cluster,match} Select a program to run.
cluster Run denovo clustering.
match Run fast matching.
options:
-h, --help show this help message and exit
--cores, -c CORES Specify the number of threads to be used. [default 12]
--delimiter DELIMITER
Input alleles delimiter. [default \t] (default: )
--columns-subset, -s COLUMNS_SUBSET
A file containing a single column of the column names to subset from the passed allele profiles. (default: None)
--count-missing, -m Count missing values as differences. (default: False)
--normalize-distance, -n
Compute the normalized distance. Distance is presented as a percentage, or a value between [0.0-1.0] (default:
False)
--filter-threshold, -f FILTER_THRESHOLD
Exclude samples from analysis if they are missing more than the specified percentage of data. Must be between
[0.0-100.0]. [default 100.0] (default: 1.0)
--verbose Display logger debug messages. (default: False)
--version, -v show program's version number and exitTo run de-novo clustering use the cluster option. The long form options for cluster are shown below:
>>> beave cluster --help
usage: beave cluster [-h] [--cores CORES] [--delimiter DELIMITER] [--columns-subset COLUMNS_SUBSET] [--count-missing] [--normalize-distance] [--filter-threshold FILTER_THRESHOLD] [--verbose] --input INPUT [--output OUTPUT] --thresholds THRESHOLDS [THRESHOLDS ...]
[--linkage-method {single,average,complete}] [--branch-type {patristic,cophenetic}] [--matrix]
options:
-h, --help show this help message and exit
--cores, -c CORES Specify the number of threads to be used. (default 12)
--delimiter DELIMITER
Input alleles delimiter. (default \t)
--columns-subset, -s COLUMNS_SUBSET
A file containing a single column of the column names to subset from the passed allele profiles.
--count-missing, -m Count missing values as differences.
--normalize-distance, -n
Compute the normalized distance. Distance is presented as a percentage, or a value between [0.0-1.0]
--filter-threshold, -f FILTER_THRESHOLD
Exclude samples from analysis if they are missing more than the specified percentage of data. Must be between [0.0-100.0]. (default 100.0)
--verbose Display logger debug messages.
--input, -i INPUT Input alleles. (required)
--output, -o OUTPUT Output directory for generated tree and clusters, directory will be created if does not exist. (default: beave)
--thresholds, -t THRESHOLDS [THRESHOLDS ...]
List of threshold values to use. (required)
--linkage-method, -l {single,average,complete}
Hierarchical clustering linkage to use. (default: average)
--branch-type, -b {patristic,cophenetic}
Determine how to display tree lenghts in the Newick file. (default cophenetic)
--matrix Write the computed distance matrix to a file in the output directory called 'matrix.tsv'.
>>> # Example programs
>>> beave cluster --input src/beave/tests/data/R1KC1K.2-zeroes.does-not-exist.csv -o out -l average -nm -b cophenetic -c 2 -t 0.9 0.5 --delimiter , --matrix
>>> beave cluster --input src/beave/tests/data/R1KC1K.tsv -l average -b cophenetic -c 1 --thresholds 10 9 8The match argument may be used to compute pairwise distances between a group of query samples against a group of reference samples. The parameters for running match are described below:
>>> beave match --help
usage: beave match [-h] [--cores CORES] [--delimiter DELIMITER] [--columns-subset COLUMNS_SUBSET] [--count-missing] [--normalize-distance] [--filter-threshold FILTER_THRESHOLD] [--verbose] --reference REFERENCE --query QUERY [--threshold THRESHOLD] [--output OUTPUT]
options:
-h, --help show this help message and exit
--cores, -c CORES Specify the number of threads to be used. (default 12)
--delimiter DELIMITER
Input alleles delimiter. (default \t)
--columns-subset, -s COLUMNS_SUBSET
A file containing a single column of the column names to subset from the passed allele profiles.
--count-missing, -m Count missing values as differences.
--normalize-distance, -n
Compute the normalized distance. Distance is presented as a percentage, or a value between [0.0-1.0]
--filter-threshold, -f FILTER_THRESHOLD
Exclude samples from analysis if they are missing more than the specified percentage of data. Must be between [0.0-100.0]. (default 100.0)
--verbose Display logger debug messages.
--reference, -r REFERENCE
Profiles to compare against. Query samples will be included in comparisons. (required)
--query, -q QUERY Profiles containing new-samples for comparisons. (required)
--threshold, -t THRESHOLD
Only report distances below specified threshold. (default: infinity)
--output, -o OUTPUT Output directory for calculated distances, directory will be created if does not exist. (default: beave)
>>> # Example programs
>>> beave match -q src/beave/tests/data/R1KC1K.head.tsv -r src/beave/tests/data/R1KC1K.tail.tsv -nm --verbose
>>> beave match -q src/beave/tests/data/R1KC1K.head.tsv -r src/beave/tests/data/R1KC1K.tail.tsv -t 101 -l average -c 8The inputs for this program must be tabular, any delimiter is supported as long is it is a single character. The first column of the file must contain no duplicates or missing values. The columns are not inspected to verify unique values only, so duplicate column names will be name mangled and treated as another unique column. The characters "?", " ", "", "-", "_", and "0" are treated as missing values by the program unless the -c option is added to the program. All other values are treated as a valid alleles. Example inputs can be found in the tests folder. Thresholds are always converted to float values, however you can specify either integers not just decimals.
When running match, the query and reference profiles will be merged by the program. If duplicate ID's are detected an error will be raised by the program.
The program outputs a Newick-Format file containing the tree generated by whichever linkage metric is selected, the sample IDs and their addresses are put out in a separate file specified by the user in TSV format. Addresses are delimited by an '.'.
Example of cluster outputs:
| SampleID | level_10.0 | level_9.0 | denovo_address |
|---|---|---|---|
| CoolSample | 1 | 2 | 1.2 |
| CoolSample2 | 2 | 1 | 2.1 |
The output of match is a single file showing the query sample, the reference sample and distance.
The general structure of the match output:
| query_id | ref_id | dist_{hamming,normalized} |
|---|---|---|
| 1 | 2 | 4 |
| 1 | 3 | 8 |
| 1 | 4 | 10 |
-
There may be issues with the Python build system, please create a GitHub issue for any issues identified.
-
If there are duplicate identifiers with different profiles. The distance between the two values will still be reported as no duplicates detection is performed currently. Future iterations may add this functionality.
-
-ffast-mathis enabled during compilation to prevent sub-normals. This leads to some error in floating point operations, the affect of this is being evaluated and this compiler flag may be removed after further testing is performed.
Copyright Government of Canada [2026]
Written by: National Microbiology Laboratory, Public Health Agency of Canada
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License at:
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Please see the CHANGELOG.md.