CATAStrophy is a python program which can be used as a python module or via a command-line interface. It can be installed from PyPI https://pypi.org/project/catastrophy/ using pip.
It is tested to work with python 3.6+, and it depends on numpy and BioPython. The install procedures below will install these for you automatically.
python3 -m pip install --user catastrophy
The --user
flag tells pip to install to a user directory rather than a system directory (e.g. somewhere under /usr/
or Program Files
).
To install as root or in Windows you can omit the --user
flag, but you may need root or administrator permission.
Note that the --user
subdirectory containing scripts (<userdir>/bin
on linux/mac or <userdir>\Scripts
on Windows), may not automatically be on your path.
The user directory installed to is given by the python command import site; print(site.USER_BASE)
.
Generally on linux this is ~/.local
.
You can change this directory by setting the $PYTHONUSERBASE
environment variable.
You can then add the Script
or bin
subdirectory to your $PATH
environment variable
(e.g. Linux and MacOS, or Windows, or just google it ;) ).
Power users may also be interested in the pip install --prefix
flag, but this will also require you to update your $PYTHONPATH
environment variable or use .pth
files .
Nonetheless, it's useful for module software management.
Generally it's a good idea to install python packages in a python virtual environment This protects versions of packages required for your operating system to work, from being updated (potentially breaking older code).
Here's a basic rundown of the virtualenv
workflow.
# If it isn't installed already run one of these
# Try to use the system package managers if possible to avoid mixing up system dependencies.
# Mac users may be interested in homebrew.
sudo python3 -m pip install virtualenv
sudo apt install python3-virtualenv # Ubuntu and probably Debian
sudo dnf install python3-virtualenv # Fedora 24+
# Change dir to where you want the envronment to live (usually a project dir).
cd my_project
# Create a virtualenv in a folder ./env
# python3 can be substituted with your version of python.
python3 -m venv env
# Loads the virtualenv (essentially this changes PYTHONPATH and some other environment variables).
source env/bin/activate
which python3
# ./env/bin/python3
python3 -m pip install catastrophy
catastrophy --help
This time we don't need to use sudo or tell pip to install as --user
because it will install all files in the ./env
folder.
Note however, that whenever you start a new terminal and want to use this environment you'll need to repeat the source env/bin/activate
.
If you want to exit the virtual environment, you can type deactivate
on the command line or just start a new terminal.
You can also install directly from the git repository to get the latest and greatest features. We use git-lfs to handle some filetypes, so you'll need to install that before running anything below.
To install most recent commit on the master
branch:
python3 -m venv env
source env/bin/activate
python3 -m pip install git+git@bitbucket.org:ccdm-curtin/catastrophy.git
Note that we installed the package in a virtual environment, which is always recommended. See the section above for more details.
You can also clone the repository yourself and then install from that.
git clone https://<your_username>@bitbucket.org/ccdm-curtin/catastrophy.git ./catastrophy
cd catastrophy
python3 -m venv env
source env/bin/activate
python3 -m pip install .
This is particularly useful if you want to modify the code. You can install the module in a way that allows changes you make to be automatically installed.
# Use this after cloning.
python3 -m venv env
source env/bin/activate
python3 -m pip install -e ".[dev,test]"
The [dev,test]
thing just installs some extra packages used for testing etc.