pyspi: Python Toolkit of Statistics for Pairwise Interactions
## Installation 📥 The simplest way to get the _pyspi_ package up and running is to install the package using `pip install`. For access to the full library of SPIs, the code requires GNU's [Octave](https://octave.org/download) to be installed on your system. #### 1. Pre-Install Octave (Optional) While you can safely install _pyspi_ without first installing `Octave`, you will not have access to the full library of SPIs #### 2. 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`. #### 3. Install with _pip_ Using `pip` for [`pyspi`](https://pypi.org/project/pyspi/): ``` pip install pyspi ``` For a more detailed guide on how to install _pyspi_, as well as how you can use _pyspi_ without first installing Octave, please see the [full documentation](https://time-series-features.gitbook.io/pyspi/installation/installing-pyspi). Additionally, we provide a comprehensive [troubleshooting guide](https://time-series-features.gitbook.io/pyspi/installation/troubleshooting) for users who encounter issues installing _pyspi_ on their system, as well as [alternative installation options](https://time-series-features.gitbook.io/pyspi/installation/alternative-installation-options). ## Getting Started 🚀 Once you have installed _pyspi_, you can learn how to apply the package by checking out the [walkthrough tutorials](https://time-series-features.gitbook.io/pyspi/usage/walkthrough-tutorials) in our documentation. Click any of the examples below to access the tutorials in our full documentation: - [Simple demonstration](https://time-series-features.gitbook.io/pyspi/usage/walkthrough-tutorials/getting-started-a-simple-demonstration) - [Finance: stock price time series](https://time-series-features.gitbook.io/pyspi/usage/walkthrough-tutorials/finance-stock-price-time-series) - [Neuroimaging: fMRI time series)](https://time-series-features.gitbook.io/pyspi/usage/walkthrough-tutorials/neuroimaging-fmri-time-series) ### Advanced Usage For advanced users, we offer several additional guides in the [full documentation](https://time-series-features.gitbook.io/pyspi/usage/advanced-usage) 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](https://time-series-features.gitbook.io/pyspi/spis/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](https://time-series-features.gitbook.io/pyspi/spis/spi-descriptions) page of our documentation. ## Documentation The full documentation is hosted on [GitBooks](https://time-series-features.gitbook.io/pyspi/). Use the following links to quickly access some of the key sections: - [Full installation guide](https://time-series-features.gitbook.io/pyspi/installation) - [Troubleshooting](https://time-series-features.gitbook.io/pyspi/installation/troubleshooting) - [Alternative installation options](https://time-series-features.gitbook.io/pyspi/installation/alternative-installation-options) - [Usage guide](https://time-series-features.gitbook.io/pyspi/usage) - [Distributing _pyspi_ computations](https://time-series-features.gitbook.io/pyspi/usage/advanced-usage/distributing-calculations-on-a-cluster) - [Table of SPIs and descriptions](https://time-series-features.gitbook.io/pyspi/spis) - [FAQ](https://time-series-features.gitbook.io/pyspi/usage/faq) - [API Reference](https://time-series-features.gitbook.io/pyspi/api-reference) - [Development guide](https://time-series-features.gitbook.io/pyspi/development) ## 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](https://time-series-features.gitbook.io/pyspi/development/contributing-to-pyspi) about how to proceed. In contributing to _pyspi_, all participants are expected to adhere to our [code of conduct](https://time-series-features.gitbook.io/pyspi/development/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](https://github.com/DynamicsAndNeuralSystems/pyspi/projects) 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](https://doi.org/10.1038/s43588-023-00519-x), _Nature Computational Science_ (2023). Note that [preprint](https://arxiv.org/abs/2201.11941) and [free-to-read](https://rdcu.be/dn3JB) versions of this article are available.