Metadata-Version: 2.1
Name: fn5
Version: 2.0.6
Summary: Fast, scalable SNP distance calculation from disk.
Author-Email: Jeremy Westhead <jeremy.westhead@ndm.ox.ac.uk>
License: LICENCE TERMS FOR ACCESS TO SOFTWARE AND DATABASE FOR ACADEMIC USE
        
        These licence terms apply to all licences granted by THE CHANCELLOR, MASTERS AND SCHOLARS OF THE UNIVERSITY
        OF OXFORD whose administrative offices are at University Offices, Wellington Square, Oxford OX1 2JD,
        United Kingdom (the "University") for use of or access to fn5 software ("the Software")
        through this website (the "Website").
        
        PLEASE READ THESE LICENCE TERMS CAREFULLY BEFORE USING THE DATABASE OR THE SOFTWARE THROUGH THIS WEBSITE.
        IF YOU DO NOT AGREE TO THESE LICENCE TERMS YOU SHOULD NOT DOWNLOAD OR USE THE SOFTWARE.
        
        THE SOFTWARE ARE INTENDED FOR ACADEMICS CARRYING OUT RESEARCH AND NOT FOR USE BY CONSUMERS OR COMMERCIAL BUSINESSES.
        
        1.	Academic Use Licence
        
        1.1	The User is granted a limited non-exclusive and non-transferable royalty free licence to access and
        use the Software provided that the User will:
        
        (a)	limit their use of the Software to their own internal academic non-commercial research which is
        undertaken for the purposes of education or other scholarly use;
        
        (b)	not use the Software for or on behalf of any third party or to provide a service or integrate all
        or part of the Software into a product for sale or license to third parties;
        
        (c)	use the Software in accordance with the prevailing instructions and guidance for use given on the
        Website and comply with procedures on the Website for user identification, authentication and access;
        
        (d)	comply with all applicable laws and regulations with respect to their use of the Software;
        
        (e)	except to the extent expressly permitted under these terms, not attempt to: reverse compile, disassemble
        or copy, modify, duplicate, create derivative works from, frame, mirror, republish, download, display, transmit,
        or distribute all or any portion of the Software or Website in any form or media or by any means; and
        
        (f)	ensure that the Copyright Notice “Copyright © 2022, University of Oxford” appears prominently wherever
        results from the Software are used, and is referenced or cited with the Copyright Notice when the Software
        is described in any research publication or on any documents or other material created using the Software.
        
        1.2	the University reserves the right at any time and without liability or prior notice to the User to
        revise, modify and replace the functionality and performance of the access to and operation of the Software.
        
        1.3	The User acknowledges and agrees that the University owns all intellectual property rights in the Software.
        The User shall not have any right, title or interest in or to any results or other output from the Software.
        
        1.4	This Licence will terminate immediately and the User will no longer have any right exercise any of the
        rights granted to the User upon any breach of the conditions in Section 1.1 of this Licence.
        
        2.	Indemnity and Liability
        
        2.1	The User shall defend, indemnify and hold harmless the University against any claims, actions, proceedings,
        losses, damages, expenses and costs (including without limitation court costs and reasonable legal fees) arising
        out of or in connection with the User's possession or use of the Software, or any breach of these terms by the User.
        
        2.2	The Software are provided on an ‘as is’ basis and the User uses the Software at their own risk. No representations,
        conditions, warranties or other terms of any kind are given in respect of the Software and all statutory warranties
        and conditions are excluded to the fullest extent permitted by law. Without affecting the generality of the previous
        sentences, the University gives no implied or express warranty and makes no representation that the Software or
        any part of them: (a) will enable specific results to be obtained; or (b) meets a particular specification or is
        comprehensive within its field or that it is error free or will operate without interruption; or (c) is suitable
        for any particular, or the User's specific purposes.
        
        2.3	Except in relation to fraud, death or personal injury, the University's liability to the User for any use of
        the Software, in negligence or arising in any other way out of the subject matter of these licence terms, will not
        extend to any incidental or consequential damages or losses, or any loss of profits, loss of revenue, loss of data,
        loss of contracts or opportunity, whether direct or indirect.
        
        2.4	The User hereby irrevocably undertakes to the University not to make any claim against any employee, student,
        researcher or other individual engaged by the University, being a claim which seeks to enforce against any of them
        any liability whatsoever in connection with this agreement or its subject-matter.
        
        3.	General
        
        3.1	Severability - If any provision (or part of a provision) of these licence terms is found by any court or
        administrative body of competent jurisdiction to be invalid, unenforceable or illegal, the other provisions shall
        remain in force.
        
        3.2	Entire Agreement - These licence terms and any documents referred to in them, constitute the whole agreement
        between the parties and supersede any previous arrangement, understanding or agreement between them relating to
        the Software.
        
        3.3	Law and Jurisdiction - These licence terms and any disputes or claims arising out of or in connection with them
        shall be governed by, and construed in accordance with, the law of England. The User irrevocably submits to the
        exclusive jurisdiction of the English courts for any dispute or claim that arises out of or in connection with
        these licence terms.
        
        If you are interested in using the Software commercially, please contact Oxford University Innovation Limited to
        negotiate a licence. Contact details are enquiries@innovation.ox.ac.uk quoting reference (TBD).
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# Find Neighbour 5
Spiritual successor to [Find Neighbour 4](https://github.com/davidhwyllie/findNeighbour4) - continuing the work of David Wyllie.

[![Tests](https://github.com/oxfordmmm/FN5/actions/workflows/test.yaml/badge.svg)](https://github.com/oxfordmmm/FN5/actions/workflows/test.yaml)
[![Build FN5 images](https://github.com/oxfordmmm/FN5/actions/workflows/build.yaml/badge.svg?branch=testing-docker)](https://github.com/oxfordmmm/FN5/actions/workflows/build.yaml)

SNP matrix generation with caching to disk to allow fast reloading.

# Install
As this is compiled client side, ensure you have a functional C++ compiler such as GCC installed. Currently only tested on Linux
```
# Optional virtual environment
python -m virtualenv env
souce env/bin/activate

# Install via pip
pip install fn5
```

# Notes
This provides some of the bindings to the underlying FN5 library, but has some limitations. Most of the functionality should be exposed via the Python bindings though.

## Read FASTA files
Firstly, you'll need a reference genome, and a list of positions to mask within it. The mask is optional, but can be used to mask homoplastic or phylogenetic regions which aren't of epidemialogical interest. The mask should be line separated genome positions.
```
import fn5

reference = fn5.load_reference("<path to your reference>")
mask = fn5.load_mask("<path to your mask>")

# Alternatively ignore the mask
mask = set()
```
Then, samples can be parsed from FASTA files
```
sample1 = fn5.Sample("<path to sample1's FASTA>", reference, mask, "sample1")
sample2 = fn5.Sample("<path to sample2's FASTA>", reference, mask, "sample2")
...
```

## Save samples
For the sake of efficency, a sample can be written to (and subsequently loaded from) disk.

Note that the `fn5.save` method writes 5 files to the specified direction. `<path>/<sample ID>.A`, `<path>/<sample ID>.C`. ...
```
fn5.save("<some output directory>", sample1)
```

## Load samples
Load pre-saved samples from disk. This should be significantly faster than re-parsing the FASTA files.
```
sample1 = fn5.load("<some output directory>/sample1")
```

## Compute distances
Distances can be computed with arbitrary SNP cuttoffs.

### Single distance
If a returned distance == your cutoff + 1, the two samples are further away than the SNP cutoff.
```
sample1.dist(sample2, <some cutoff>)
```

### Distance matrix
By default this method uses 4 threads, and no cutoff. If a pair of samples is missing from the returned distance list, they are further away than the given cutoff.
```
samples = [fn5.load("<some directory>/"+f) for f in <existing filepaths>]
fn5.compute(samples)

# With more/less threads
fn5.compute(samples, thread_count=12)
fn5.compute(samples, thread_count=1)

# With a SNP cutoff
fn5.compute(samples, cutoff=12)
``` 
