Installation#

NB - If you have trouble installing TopoStats please do checkout the discussion for possible solutions. If your problem isn’t covered then please do not hesitate to ask a question.

TopoStats is a Python package designed to run at the command line. You may have Python installed on your system but should use a Python Virtual Environment such as Miniconda and install it under the Virtual Environment. The versions of Python supported are Python >=3.8 and so when creating your virtual environment you should specify this 3.8 as the minimum.

Setting up Conda#

Once you have downloaded and installed Miniconda you can create a virtual environment for installing TopoStats with a version of Python that meets the requirements. We will call this environment topostats (specified with the --name topostats option) and to use Python 3.10 (the option python=3.10). After creating it we can, as per the instructions printed out, activate the environment.

conda create --name topostats python=3.10
conda activate topostats

You are now ready to install TopoStats.

NB If you are using an Apple M1 Macbook then you need to install Anaconda >= 2022.05.

Installing TopoStats#

There are two options for installing TopoStats depending on your usage

Python Package Index - appropriate if you are just using TopoStats and don’t need to dig into the code.
Cloning the GitHub Repository - if you want to look at the code, contribute to it, debug errors or perhaps test a new feature before a release.

PyPI Installation#

After activating your topostats Conda environment you can install TopoStats from PyPI using the following command.

pip install topostats

This will install TopoStats under your virtual environment and the command run_topostats will be available at the command line. You will probably want to download a copy of the default_config.yaml to edit and use for running your analysis. Please see the usage section for more information on running TopoStats.

Cloning from GitHub#

NB Cloning and installing from GitHub is only required if you wish to contribute to or debug problems with TopoStats, if you only intend on using it then please install from PyPI.

If you do not have Git already installed please see Git. If you intend to contribute to the development of TopoStats please read through the contributing section.

If you are familiar with the command line then you can clone and install TopoStats with the following after activating your virtual environment.

git clone https://github.com/AFM-SPM/TopoStats.git
# If you have SSH access configured to GitHub then you can use
git clone git@github.com:AFM-SPM/TopoStats.git

Cloning Using GitKraken#

If you are using GitKraken you can clone the repository by selecting “Clone” and then “GitHub.com” and typing TopoStats into the box next to “Repository to Clone” and you should be presented with the option of selecting “TopoStats” from the AFM-SPM organisation.

Alternatively you can “Clone with URL” and enter https://github.com/AFM-SPM/TopoStats.git as the URL to clone from, selecting a destination to clone to.

Installing TopoStats from the Cloned Repository#

Once cloned you will have to open a Terminal and navigate to the directory you cloned and after activating your virtual environment install TopoStats with the following.

cd /path/to/where/topostats/was/cloned/TopoStats
pip install .

If you wish to make changes to the code and test then make a git branch, make your changes and install in editable mode, i.e. pip install -e ..

If you wish to develop features or address an existing issue please refer to the contributing section.

Tests#

One of the major changes in the refactoring is the introduction of unit tests. These require certain packages to be installed which are not installed to your virtual environment by setuptools in the above steps. If you are develop and making changes to the code base you will likely want to be able to run the tests. Install the necessary dependencies to do so with…

cd TopoStats
git checkout dev
pip install ".[tests]"
pytest

Git#

Git is a version control system for managing software development and is required to be installed on your computer in order to clone the TopoStats repository. Instructions on installing Git can be found at Git Guides - install git.

A nice Graphical User Interface for working with Git is GitKraken which includes everything you need.

Versions