cathpy 0.4.1
CathPy - Python Bioinformatics Toolkit for CATH (Protein Classification).

# cathpy

[![Documentation Status](https://readthedocs.org/projects/cathpy/badge/?version=latest)](https://cathpy.readthedocs.io/en/latest/?badge=latest)
[![Build Status](https://travis-ci.com/UCL/cathpy.svg?branch=master)](https://travis-ci.com/UCL/cathpy)
[![codecov](https://codecov.io/gh/UCL/cathpy/branch/master/graph/badge.svg)](https://codecov.io/gh/UCL/cathpy)

`cathpy` is a Bioinformatics toolkit written in Python. It is developed and maintained by the
[Orengo Group](http://orengogroup.info/) at [UCL](https://www.ucl.ac.uk/orengo-group/) and is used for maintaining the [CATH protein structure database](http://www.cathdb.info) (and associated research).


## Getting Started

The easiest way to use this code is by installing the latest version into a virtual environment via `pip`:

```sh
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install cathpy
```

If everything is installed and working properly then the following should work:

```sh
$ cath-align-summary -d tests/data/funfams/
file aln_len seq_count dops gap_per
tests/data/funfams/1.10.8.10-ff-14534.reduced.sto                          69     51  61.53  12.53
tests/data/funfams/1.10.8.10-ff-15516.reduced.sto                          66    429 100.00  13.04
tests/data/funfams/1.10.8.10-ff-5069.reduced.sto                           59     14   7.81   3.15
tests/data/funfams/1.10.8.10-ff-15593.reduced.sto                          63    203  95.88  17.70
```

Now go and [have a look at the documentation](https://cathpy.readthedocs.io/en/latest/).

## Contributing

There are many ways to contribute, all of which are most welcome.

 * If something is not clear then you have identified a gap in the documentation, please let us know by [raising a new issue](https://github.com/UCL/cathpy/issues/new) 
 * If it looks like you should be able to do something that you can't then you've either identified a new feature request or a documentation gap - please let us know by [raising a new issue](https://github.com/UCL/cathpy/issues/new)
 * If you have noticed some unexpected behaviour, you may have found a bug - please let us know by [raising a new issue](https://github.com/UCL/cathpy/issues/new)

When you do raise an issue, it is extremely helpful if you first check that a similar issue has not already been registered. It would also be great if you can be as clear, concise and specific as possible. If you are reporting a potential bug, please try to provide steps that will allow us to reproduce the unexpected behaviour.

If you accompany your issue with a Pull Request that actually solves the documentation / feature request / bug fix then you may well be eligible for doughnuts.

## Development

If you are developing, then this is the general recommended flow:

Get access to the latest version of the code and create a new branch (with a descriptive summary of your new feature/bugfix):

```sh
$ git clone git@github.com:UCL/cathpy.git
$ cd cathpy
$ git checkout -b my-awesome-new-feature
```

Install the code (as editable package) into virtual environment

```sh
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install -e .
```

Write your tests, make your changes then make sure your tests (and all the other tests) still pass:

```sh
$ vim tests/my_new_feature_test.py
$ vim cathpy/my_new_feature.py
$ pytest
```

Then push your changes back to GitHub and raise a pull request through the web pages.

```sh
$ git push
```

## FAQ

**What is cathpy?**

`cathpy` is a python package that contains bioinformatics tools and libraries
used in [CATH](http://cathdb.info) (protein structure classification resource at UCL).

**Hmmm.. that sounds like Yet Another Python Bioinformatics Toolkit?**

Well it is... sort of.

**Should I be using it?**

If you are looking for a general Bioinformatics toolkit, you should look at [BioPython](https://biopython.org/) first.

The `cathpy` project does contain some generic functionality that may overlap with BioPython,
however we are definitely not trying to rewrite that library. It has been published mainly for 
internal use (within CATH), however it has been released as open source in case others find the tools helpful.

## External software

This code base contains external tools that are not written and maintained by the authors
of this project. If you use the results of these tools, please reference the relevant papers.

#### GroupSim

Characterization and Prediction of Residues Determining Protein Functional Specificity.
**Capra JA and Singh M (2008).**<br>
*Bioinformatics, 24(13): 1473-1480, 2008.*

#### Scorecons

Scoring residue conservation.
**Valdar WSJ (2002)**<br>
*Proteins: Structure, Function, and Genetics. 43(2): 227-241, 2002.*

## References

The most recent paper describing the CATH protein structure database:

CATH: expanding the horizons of structure-based functional annotations for genome sequences.
**Sillitoe I, et al (2018)**<br>
*Nucleic Acids Research, Volume 47, Issue D1, 08 January 2019, Pages D280–D284, https://doi.org/10.1093/nar/gky1097*