Metadata-Version: 2.1
Name: pycascor
Version: 0.1.0
Summary: Cascade Correlation Network Simulator
Author-email: Caroline Simpson <pycascor@hoojiboo.com>
Maintainer-email: Caroline Simpson <pycascor@hoojiboo.com>
License: MIT License
        
        Copyright (c) 2024 Caroline Simpson
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Repository, https://gitlab.com/cpsimpson/cascade-correlation-network-simulator
Project-URL: Bug Tracker, https://gitlab.com/cpsimpson/cascade-correlation-network-simulator/-/issues
Keywords: Cascade Correlation,neural network,cascor
Classifier: Programming Language :: Python
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy==1.26.4
Requires-Dist: matplotlib==3.8.3

# PyCasCor

## Description
A python implementation of a Cascade Correlation Network Simulator

## Installation

### Easiest Option - Install from PyPi

`pip install pycascor`

### Using the source repository

1. clone the repository locally
1. create and activate virtual environment
   1. `python -m venv venv`
   1. `. venv/bin/activate`
1. install dependencies
   1. `pip install .`

## Usage

Example of Training on XOR

### Cascade Correlation Network

```python
from pycascor.network import CCNetwork
from pycascor.activation_functions import Sigmoid
from pycascor.trainer import Trainer

xor_inputs = [[0, 0], [0, 1], [1, 0], [1, 1]]
xor_targets = [[-0.5], [0.5], [0.5], [-0.5]]
      
trainer = Trainer([(8, Sigmoid())])
net = CCNetwork(2, 1, Sigmoid())

net = trainer.train_network(xor_inputs, xor_targets, net)

for x in xor_inputs:
    net.full_forward_pass(x)

output_values = [node.value for node in net.output_nodes]
```

### Small Magnitude Weight Pruning
```python
from pycascor.network import PrunableCCNetwork
from pycascor.activation_functions import Sigmoid
from pycascor.trainer import PruneTrainer

xor_inputs = [[0, 0], [0, 1], [1, 0], [1, 1]]
xor_targets = [[-0.5], [0.5], [0.5], [-0.5]]
      
trainer = PruneTrainer([(8, Sigmoid())])
net = PrunableCCNetwork(2, 1, Sigmoid())

net = trainer.train_network(xor_inputs, xor_targets, net)

for x in xor_inputs:
    net.full_forward_pass(x)

output_values = [node.value for node in net.output_nodes]
```

### Optimal Brain Damage Pruning
```python
from pycascor.network import PrunableCCNetwork
from pycascor.activation_functions import Sigmoid
from pycascor.trainer import OptimalBrainDamageTrainer

xor_inputs = [[0, 0], [0, 1], [1, 0], [1, 1]]
xor_targets = [[-0.5], [0.5], [0.5], [-0.5]]
      
trainer = OptimalBrainDamageTrainer([(8, Sigmoid())])
net = PrunableCCNetwork(2, 1, Sigmoid())

net = trainer.train_network(xor_inputs, xor_targets, net)

for x in xor_inputs:
    net.full_forward_pass(x)

output_values = [node.value for node in net.output_nodes]
```

## Simulator Examples
In addition to the library code `pycascor`, you will find an `examples` directory this repository. 
This contains a simulator script `simulation.py` which is able to run multiple trials of various 
datasets across the 3 versions of the network training algorithms. This includes some data which comes 
from the Proben1 benchmarking dataset project originally compiled by Lutz Prechelt. A copy of the data
is linked as a submodule.

```commandline
. venv/bin/activate
pip install .
python examples/simulation.py <example> <number-of-trials>
```
Example options: spirals, cancer, glass, xor

Various output files will be written to a `result` folder for your analysis.

spirals trains the networks on a subset of the [two-spirals classification problem](https://www.researchgate.net/publication/269337640_Learning_to_Tell_Two_Spirals_Apart). 
The resulting networks are then validated and tested on the remaining points

cancer trains the networks on the 
["Wisconsin breast cancer database"](https://github.com/cpsimpson/proben1/tree/master/cancer) from the UCI 
machine learning dataset included in the [Proben1](https://github.com/cpsimpson/proben1) repository.

glass trains the networks on the ["glass"](https://github.com/cpsimpson/proben1/tree/master/glass) from the UCI 
machine learning dataset included in the [Proben1](https://github.com/cpsimpson/proben1) repository.

xor trains and tests the networks on the XOR dataset.

## Support
Feel free to create an Issue or MR if you find a bug or want to add a contribution.

## Contributing

### Running Tests
To run the tests you can run `pytest` from the project root directory.


## Authors and acknowledgment
This implementation is based on the code of Scott Fahlman and Thomas Shultz. 
Thanks to Dr. Britt Anderson, Hanbin Go, James Houle, Julia Schirmeister, 
Vivian DiBerardino, and Ciaran Neely for contributing to my understanding 
of the algorithm and inspiring this project.

## License
This code and related materials is made available under the MIT License. 

## Project status
This is a project that I created for a directed studies course at while studying at University of Waterloo.
