pyspi: Python Toolkit of Statistics for Pairwise Interactions

pyspi is a comprehensive python library for computing statistics of pairwise interactions (SPIs) from multivariate time-series (MTS) data. The toolbox provides easy access to hundreds of methods for evaluating the relationship between pairs of time series, from simple statistics (like correlation) to advanced multi-step algorithms (like Granger causality). The code is licensed under the GNU GPL v3 license (or later).

Feel free to reach out for help with real-world applications. Feedback is much appreciated through issues, or pull requests.

Installation 📥

The simplest way to get the pyspi package up and running is to install the package using pip install.

1. Create a conda environment (Optional, Recommended)

While you can also install pyspi outside of a conda environment, it depends on a lot of user packages that may make managing dependencies quite difficult. So, we would also recommend installing pyspi in a conda environment. Firstly, create a fresh conda environment:

conda create -n pyspi python=3.9.0

Once you have created the environment, activate it using conda activate pyspi.

2. Install with pip

Using pip for pyspi:

pip install pyspi

For a more detailed guide on how to install pyspi, please see the full documentation. Additionally, we provide a comprehensive troubleshooting guide for users who encounter issues installing pyspi on their system, as well as alternative installation options.

Getting Started 🚀

Once you have installed pyspi, you can learn how to apply the package by checking out the walkthrough tutorials in our documentation. Click any of the examples below to access the tutorials in our full documentation:

• Simple demonstration

• Finance: stock price time series

• Neuroimaging: fMRI time series

• Motion tracking

Advanced Usage

For advanced users, we offer several additional guides in the full documentation on how you can distribute your pyspi jobs across PBS clusters, as well as how you can construct your own subsets of SPIs.

SPI Descriptions 📋

To access a table with a high-level overview of the pyspi library of SPIs, including their associated identifiers, see the table of SPIs in the full documentation. For detailed descriptions of each SPI, as well as its associated estimators, we provide a full breakdown in the SPI descriptions page of our documentation.

Documentation

The full documentation is hosted on GitBooks. Use the following links to quickly access some of the key sections:

• Full installation guide
• Troubleshooting
• Alternative installation options
• Usage guide
• Distributing pyspi computations
• Table of SPIs and descriptions
• FAQ
• API Reference
• Development guide

Contributing to pyspi 👨‍👨‍👦‍👦

Contributions play a vital role in the continual development and enhancement of pyspi, a project built and enriched through community collaboration. If you would like to contribute to pyspi, or explore the many ways in which you can participate in the project, please have a look at our detailed contribution guidelines about how to proceed. In contributing to pyspi, all participants are expected to adhere to our code of conduct.

SPI Wishlist

We strive to provide the most comprehensive toolkit of SPIs. If you have ideas for new SPIs or suggestions for improvements to existing ones, we are eager to hear from and collaborate with you! Any pairwise dependence measure, provided it is accompanied by a published research paper, typically falls within the scope for consideration in the pyspi library. You can access our SPI wishlist via the projects tab in this repo to open a request.

Acknowledgement 👍

If you use this software, please read and cite this article:

• 📗 O.M. Cliff, A.G. Bryant, J.T. Lizier, N. Tsuchiya, B.D. Fulcher. Unifying pairwise interactions in complex dynamics, Nature Computational Science (2023).

Note that preprint and free-to-read versions of this article are available.

@article{Cliff2023:UnifyingPairwiseInteractions,
	title = {Unifying pairwise interactions in complex dynamics},
	volume = {3},
	issn = {2662-8457},
	url = {https://www.nature.com/articles/s43588-023-00519-x},
	doi = {10.1038/s43588-023-00519-x},
	number = {10},
	journal = {Nature Computational Science},
	author = {Cliff, Oliver M. and Bryant, Annie G. and Lizier, Joseph T. and Tsuchiya, Naotsugu and Fulcher, Ben D.},
	month = oct,
	year = {2023},
	pages = {883--893},
}

Other highly comparative toolboxes 🧰

If you are interested in trying other highly comparative toolboxes like pyspi, see the below list:

• hctsa, the highly comparative time-series analysis toolkit, computes over 7000 time-series features from univariate time series.
• hcga, a highly comparative graph analysis toolkit, computes several thousands of graph features directly from any given network.
• pyhctsa, a python implementation of the highly comparative time-series analysis toolkit.

Our Contributors 🌟

We are thankful for the contributions of each and everyone who has helped make this project better. Whether you've added a line of code, improved our documentation, or reported an issue, your contributions are greatly appreciated! Below are some of the leading contributors to pyspi:

License 🧾

pyspi is released under the GNU General Public License.