Skip to main content

A fast tool to calculate Hamming distances

Project description

A small C++ tool to calculate pairwise distances between gene sequences given in fasta format.

DOI pypi releases python versions

Python interface

To use the Python interface, you should install it from PyPI:

python -m pip install hammingdist

Distances matrix

Then, you can e.g. use it in the following way from Python:

import hammingdist

# To see the different optional arguments available:
help(hammingdist.from_fasta)

# To import all sequences from a fasta file
data = hammingdist.from_fasta("example.fasta")

# To import only the first 100 sequences from a fasta file
data = hammingdist.from_fasta("example.fasta", n=100)

# To import all sequences and remove any duplicates
data = hammingdist.from_fasta("example.fasta", remove_duplicates=True)

# To import all sequences from a fasta file, also treating 'X' as a valid character
data = hammingdist.from_fasta("example.fasta", include_x=True)

# The distance data can be accessed point-wise, though looping over all distances might be quite inefficient
print(data[14,42])

# The data can be written to disk in csv format (default `distance` Ripser format) and retrieved:
data.dump("backup.csv")
retrieval = hammingdist.from_csv("backup.csv")

# It can also be written in lower triangular format (comma-delimited row-major, `lower-distance` Ripser format):
data.dump_lower_triangular("lt.txt")
retrieval = hammingdist.from_lower_triangular("lt.txt")

# If the `remove_duplicates` option was used, the sequence indices can also be written.
# For each input sequence, this prints the corresponding index in the output:
data.dump_sequence_indices("indices.txt")

# Finally, we can pass the data as a list of strings in Python:
data = hammingdist.from_stringlist(["ACGTACGT", "ACGTAGGT", "ATTTACGT"])

Duplicates

When from_fasta is called with the option remove_duplicates=True, duplicate sequences are removed before constructing the differences matrix.

For example given this set of three input sequences:

Index Sequence
0 ACG
1 ACG
2 TAG

The distances matrix would be a 2x2 matrix of distances between ACG and TAT:

ACG TAT
ACG 0 2
TAT 2 0

The row of the distances matrix corresponding to each index in the original sequence would be:

Index Sequence Row in distances matrix
0 ACG 0
1 ACG 0
2 TAT 1

This last column is what is written to disk by DataSet.dump_sequence_indices.

It can also be constructed (as a numpy array) without calculating the distances matrix by using hammingdist.fasta_sequence_indices

import hammingdist

sequence_indices = hammingdist.fasta_sequence_indices(fasta_file)

Large distance values

By default, the elements in the distances matrix returned by hammingdist.from_fasta have a maximum value of 255.

For distances larger than this hammingdist.from_fasta_large supports distances up to 65535 (but uses twice as much RAM)

Distances from reference sequence

The distance of each sequence in a fasta file from a given reference sequence can be calculated using:

import hammingdist

distances = hammingdist.fasta_reference_distances(sequence, fasta_file, include_x=True)

This function returns a numpy array that contains the distance of each sequence from the reference sequence.

You can also calculate the distance between two individual sequences:

import hammingdist

distance = hammingdist.distance("ACGTX", "AAGTX", include_x=True)

OpenMP on linux

The latest versions of hammingdist on linux are now built with OpenMP (multithreading) support. If this causes any issues, you can install a previous version of hammingdist without OpenMP support:

pip install hammingdist==0.11.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release. See tutorial on generating distribution archives.

Built Distributions

hammingdist-0.18.0-cp311-cp311-win_amd64.whl (108.6 kB view hashes)

Uploaded cp311

hammingdist-0.18.0-cp311-cp311-win32.whl (93.9 kB view hashes)

Uploaded cp311

hammingdist-0.18.0-cp310-cp310-win_amd64.whl (108.6 kB view hashes)

Uploaded cp310

hammingdist-0.18.0-cp310-cp310-win32.whl (93.2 kB view hashes)

Uploaded cp310

hammingdist-0.18.0-cp39-cp39-win_amd64.whl (108.7 kB view hashes)

Uploaded cp39

hammingdist-0.18.0-cp39-cp39-win32.whl (93.4 kB view hashes)

Uploaded cp39

hammingdist-0.18.0-cp38-cp38-win_amd64.whl (108.7 kB view hashes)

Uploaded cp38

hammingdist-0.18.0-cp38-cp38-win32.whl (94.0 kB view hashes)

Uploaded cp38

hammingdist-0.18.0-cp37-cp37m-win_amd64.whl (108.7 kB view hashes)

Uploaded cp37

hammingdist-0.18.0-cp37-cp37m-win32.whl (94.7 kB view hashes)

Uploaded cp37

hammingdist-0.18.0-cp36-cp36m-win_amd64.whl (108.6 kB view hashes)

Uploaded cp36

hammingdist-0.18.0-cp36-cp36m-win32.whl (94.7 kB view hashes)

Uploaded cp36

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page