Metadata-Version: 2.1
Name: cd_network
Version: 0.1.3
Summary: A framework designed to calculate the output of neurons based on non-homogeneous Poisson processes and rate statistic calculations
Home-page: https://github.com/nuniz/CoincidenceDetectionNetwork
Author: Asaf Zorea
Author-email: zoreasaf@gmail.com
License: MIT
Project-URL: Bug Tracker, https://github.com/nuniz/CoincidenceDetectionNetwork/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy <2
Requires-Dist: scipy
Provides-Extra: dev
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: check-manifest ; extra == 'dev'
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: matplotlib ; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: coverage ; extra == 'test'

# CD-Network

CD-Network is a Python library designed for the analytical derivation of the stochastic output of coincidence detector (
CD) cells.
These cells receive inputs modeled as non-homogeneous Poisson processes (NHPP) with both excitatory and inhibitory
components.

![cd_scheme](cd.png)

## Features

### Dynamic Connections (CD Network)

Define how cells are interconnected within the network and how external inputs affect cell
responses. 

```python
import numpy as np
from cd_network.network import NeuralNetwork

if __name__ == '__main__':
    # Load the neural network configuration from a JSON file
    config_path = r'config.json'  # Path to the configuration file
    network = NeuralNetwork(config_path)

    # Define external inputs for the network
    external_inputs = {
        'external1': np.random.randn(1000),
        'external2': np.random.randn(1000),
        'external3': np.random.randn(1000)
    }

    # Run the network with the provided external inputs
    outputs = network.run_network(external_inputs)

    # Print the outputs of the network
    print(outputs)

```

### Configuration File

The CD network simulation uses a JSON configuration file. Below is a breakdown of the configuration structure:

    fs: Sampling frequency in Hz. This value is used across all cells for time-based calculations.

    cells: An array of objects where each object represents a neural cell and its specific parameters:
        type: Specifies the type of the cell (e.g., ei, simple_ee, cd).
        id: A unique identifier for the cell.
        params: Parameters specific to the cell type, such as delta_s for the time window in seconds and n_spikes for the minimum number of spikes required.

    connections: An array defining the connections between cells or from external inputs to cells:
        source: Identifier for the source of the input. This can be an external source or another cell.
        target: Identifier for the cell receiving the input.
        input_type: Specifies whether the input is excitatory or inhibitory.

[Example Configuration File](examplenotebooks/config.yaml)

### CD Cells

#### `ei(excitatory_input, inhibitory_inputs, delta_s, fs)`

Computes the output of an excitatory-inhibitory (EI) neuron model.
The model outputs spikes based on the excitatory inputs, except when inhibited by any preceding spikes within a
specified time window from the inhibitory inputs.

- **Parameters:**
    - `excitatory_input (np.ndarray)`: 1D array of spike times or binary spikes from the excitatory neuron.
    - `inhibitory_inputs (np.ndarray)`: 1D or 2D array of spike times or binary spikes from one or more inhibitory
      neurons.
    - `delta_s (float)`: Coincidence integration duration in seconds, defining the time window for inhibition.
    - `fs (float)`: Sampling frequency in Hz.

- **Returns:**
    - `np.ndarray`: Output spike times or binary spike array after applying the excitatory-inhibitory interaction.

#### `simple_ee(inputs, delta_s, fs)`

Simplifies the model of excitatory-excitatory (EE) interaction where an output spike is generated whenever both inputs
spike within a specified time interval.

- **Parameters:**
    - `inputs (np.ndarray)`: 2D array of excitatory input spikes.
    - `delta_s (float)`: Coincidence integration duration in seconds.
    - `fs (float)`: Sampling frequency in Hz.

- **Returns:**
    - `np.ndarray`: Output spike times or binary spike array after applying the EE interaction.

#### `ee(inputs, n_spikes, delta_s, fs)`

A general excitatory-excitatory (EE) cell model that generates a spike whenever at least a minimum number of its inputs
spike simultaneously within a specific time interval.

- **Parameters:**
    - `inputs (np.ndarray)`: 2D array of excitatory input spikes.
    - `n_spikes (int)`: Minimum number of inputs that must spike simultaneously.
    - `delta_s (float)`: Coincidence integration duration in seconds.
    - `fs (float)`: Sampling frequency in Hz.

- **Returns:**
    - `np.ndarray`: Output spike times or binary spike array based on the input conditions.

#### `cd(excitatory_inputs, inhibitory_inputs, n_spikes, delta_s, fs)`

Models the output of a coincidence detector (CD) cell which generates spikes based on the relative timing and number of
excitatory and inhibitory inputs within a defined interval.

- **Parameters:**
    - `excitatory_inputs (np.ndarray)`: 2D array of excitatory input spikes.
    - `inhibitory_inputs (np.ndarray)`: 2D array of inhibitory input spikes.
    - `n_spikes (int)`: Minimum excess of excitatory spikes over inhibitory spikes required to generate an output spike.
    - `delta_s (float)`: Interval length in seconds.
    - `fs (float)`: Sampling frequency in Hz.

- **Returns:**
    - `np.ndarray`: Output spike array after applying the CD interaction based on the relative timing and number of
      inputs.

## Installation

You can install CD-Network directly from pypi:

```bash
pip install cd_network
```

Or you can install CD-Network directly from the source code:

```bash
git clone https://github.com/nuniz/CoincidenceDetectionNetwork.git
cd CoincidenceDetectionNetwork
pip install .
```

## Contribution

run pre-commit to check all files in the repo.

```bash 
pre-commit run --all-files
```

## Reference

Krips R, Furst M. Stochastic properties of auditory brainstem coincidence detectors in binaural perception.
J Acoust Soc Am. 2009 Mar;125(3):1567-83. doi: 10.1121/1.3068446. PMID: 19275315.
