py-ctln 0.1.3

A package for assisting in the research of Combinatorial Threshold Linear Networks

The py_ctln Package README

Disclaimer: Please note that this package is in its earliest beta phase. Nothing here is finalized whatsoever. Use at your own risk!

Reading this on a site other than github? You can find all of the information you may need on this package at our github repo here.

Navigation Shortcuts:

What is py_ctln?
Installation
Usage
!!! Important Usage Note !!!
Resources, References, and Background
Contributing
Acknowledgements

What is py_ctln?

py_ctln is a python package made by the applied mathematician Olivia Kaminske (Liv) as a way to provide computational tools for use in the study and research of Combinatorial Threshold Linear Networks (CTLNs).

CTLNs are a mathematical model of neural networks (like the brain) that provide insight into the dynamics of these systems. CTLNs in particular are geared toward a branch of computational neuroscience called connectomics. Connectomics is the field concerned with understanding the connection between neural connectivity and neural network behavior. In other words, we're trying to understand why the particular way in which the neurons in our brains are connected ends up creating the sophisticated brain activity we see.

CTLNs were invented by Katherine Morrison and Carina Curto some time ago, and much research has been done on the topic by them, their students, and the broader mathematics and neuroscience communities. In the course of this research, computational tools have been invaluable as a way to explore, identify, and prove ideas related to the topic. Thus far, much of this has been done in MatLab. Unfortunately, MatLab has many drawbacks including the expense, difficulty of learning, lack of resources, and so on. Python is a great solution to many of these problems, so Liv took it upon herself to bring the world of CTLNs to the python stage.

py_ctln is the result of this desire, and it is an ongoing project to convert old MatLab code into a distributable python package, as well as to provide updates, optimizations, and new functionality made possible by the versatility and ease of use of the python language.

If you're a seasoned studier of CTLNs, we hope this package can serve you well in your research. If you've never before seen or heard of CTLNs, we hope this package may be a fun and enticing introduction to the topic for those who may feel less intimidated learning of such a thing through bits of python code. If you're somewhere in between, we hope this package can serve you well in your pursuits, be they educational, recreational, or (as we often hope) fantastical.

Installation

To install the latest version of py_ctln, simply run the following command in your terminal

pip install py_ctln

If you'd like to install a specific version, you may do so in the form

pip install py_ctln==VERSION_GOES_HERE

pip has some other features that can be useful in particular cases, and more information on that can be found on pip's sites or through external sources. We typically recommend the simple installation of the latest version for the vast majority of use cases.

Installing Pre-Releases

If you're looking to install a pre-release (ie. a version that is incomplete and hosted on a branch other than the main one), you need only do the following:

1. Download and unzip the source code from github
2. Open a terminal and navigate to the folder that resulted from your unzipping
3. Run the command hatch build in that folder, which will create a subdirectory called 'dist'
4. In the 'dist' subdirectory, find the file with the extension '.whl'
5. Copy the absolute path to this file, and you may install it for any python environment of your choosing by running the command pip install path_to_file.whl

Do keep in mind that pre-releases are often unstable or have broken features. Nonetheless, if you choose to use them and have difficulty in the course of building/installing them, see hatch's documentation for more assistance.

Usage

To import the library for usage, include the following line of code with your other imports:

from py_ctln import CTLN

After importing the library, you may use any of the functions via the form

CTLN.function_name(parameters)

You can also access sets of known/collected CTLNs that come pre-packaged with the distribution of py_ctln by using the code

CTLN.collections.type_of_collection(parameters)

!!! Important Note !!!

Many of the functions in the package rely on a user's defined adjacency matrix. Do note that CTLNs use an atypical definition of such a matrix, such that the more common definition of an adjacency matrix will need to be transposed to be used as a CTLN adjacency matrix (and vice versa to go from a CTLN adjacency matrix to a typical digraph adjacency matrix).

If you encounter issues or unexpected behavior/results, this is the first place to check.

More Questions?

More in-depth usage information and instructions can be found in the official documentation.

Resources, References, and Background

A list of references will be provided here in the future, both to various papers and publications on the topic of CTLNs as well as any code snippets, referenced topics, etc. that we may want to call back to.

Beyond references, if you are looking for more information on CTLNs, how they work, and the mathematical foundations at play here, please see the wiki/docs page here where you can find more in depth explanations and resources on the topic.

Contributing

Think you have some good ideas to make the package better? Be they optimizations, new features, or something entirely different, we want to hear about them! Feel free to fork the repository and make your own edits. We'll review pull requests as best we can given our availability. Please do not take it personally if any of your edits are rejected for merging into the package.

As far as guidelines for contribution go, all we ask is that your code is well documented and fits the style of the currently existing code. For small changes/edits, maintainers may be willing to reformat things for you but for larger, more substantial, or more complex contributions, failure to adhere to the established style may result in an automatic denial of the pull request.

Beyond that, in an effort of openness, transparency, and accessibility, this project uses the AGPL-3.0 license (more on that here), which does require that any continuation of this work adheres to this same license that requires freely accessibly source code, well documented changes, etc. Please keep this in mind if you plan to contribute to or build upon this code base in any way.

Acknowledgements

Special thanks to the following people for their contributions to this body of work. This is by no means an complete or exhaustive list, and we offer our thanks to all CTLN researchers regardless of if they are listed below:

• Carina Curto: Along with Katherine Morrison, the co-inventor of the CTLN model.
• Katherine Morrison: Along with Carina Curto, the co-inventor of the CTLN model.
• Caitlyn Parmelee: A CTLN researcher at Keene State College. Undergraduate advisor of the maintainer and creator of this repository and a major help in its creation and maintenance.
• Olivia Kaminske: The creator and maintainer of this repository. A (currently) undergraduate student of Caitlyn Parmelee's who took on the task of converting old and creating new code for this project (mostly because she is insane enough to find the task fun).