Swarm-Contrastive Decomposition 🧠

Overview 📝

Welcome to the Swarm-Contrastive Decomposition project! This repository contains the code of our research paper on decomposition of Neurophysiological Time Series signals. The primary goal of this project is to provide an open-source implementation for fostering further research in this area.

Table of Contents 📚

• Installation
• How to use this repository
• Contributing
• License
• Citation
• Contact

Installation 🛠️

Prerequisites

Make sure you have the following software and libraries installed:

• Python 3.10 🐍
• NumPy 📦
• PyTorch 🔥

Steps

Follow these steps to set up the project locally:

1. Clone the repository:

   git clone https://github.com/AgneGris/swarm-contrastive-decomposition

2. Navigate to the project directory:

   cd swarm-contrastive-decomposition

3. Create the conda environment from the decomposition.yml file:

   conda env create -f decomposition.yml

4. Activate the environment:

   conda activate decomposition

How to use this repository 🚀

1. Upload Your Input Data:

   • Place your input data files in the data/input folder.

2. Modify Data Loading:

   • Depending on your data structure, you may need to adjust the data loading logic in main.py (lines 41-53).

3. Configure the Parameters:

   • Customize the configuration settings in main.py according to your needs:
     • device: Set to "cuda" for GPU or "cpu" for CPU.
     • acceptance_silhouette: Define the acceptance threshold for source quality.
     • extension_factor: This factor typically equals 1000 / number of channels. A higher value may improve results.
     • low_pass_cutoff: Define the cutoff frequency for the low-pass filter.
     • high_pass_cutoff: Define the cutoff frequency for the high-pass filter.
     • start_time: Set the start time for signal trimming. Use 0 to include the entire signal from the beginning.
     • end_time: Set the end time for signal trimming. Use -1 to include the entire signal until the end.
     • max_iterations: Specify the maximum number of iterations for the decomposition process.
     • sampling_frequency: Indicate the sampling frequency of your signal.
     • peel_off_window_size: Define the size of the window (in ms) for the spike-triggered average of the source.
     • output_final_source_plot: Set to True to generate a plot of the final source, or False to skip plotting.
     • use_coeff_var_fitness: Set to True if consistent activity is expected in discharge times (recommended for most EMGs); set to False for other types of data (e.g., intracortical).
     • remove_bad_fr: Set to True to filter out sources with firing rates below 2 Hz or above 100 Hz. You can adjust these thresholds in models\scd.py if needed.
   • Other configuration parameters are found in config\structures.

4. Run the Decomposition:

   • Once your data is properly loaded and configured, run the following command to start the decomposition process:

     python main.py

   • Once the decomposition process has terminated, the output data will be saved in the data/output folder.

Contributing 🤝

We welcome contributions! Here’s how you can contribute:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/newfeature).
3. Commit your changes (git commit -m 'Add some newfeature').
4. Push to the branch (git push origin feature/newfeature).
5. Open a pull request.

License 📜

This project is licensed under the CC BY-NC 4.0 License.

Citation

If you use this code in your research, please cite our paper:

@article{10643350,
  author={Grison, Agnese and Clarke, Alexander Kenneth and Muceli, Silvia and Ibáñez, Jaime and Kundu, Aritra and Farina, Dario},
  journal={IEEE Transactions on Biomedical Engineering}, 
  title={A Particle Swarm Optimised Independence Estimator for Blind Source Separation of Neurophysiological Time Series}, 
  year={2024},
  volume={},
  number={},
  pages={1-11},
  keywords={Recording;Time series analysis;Sorting;Vectors;Measurement;Electrodes;Probes;Independent component analysis;particle swarm optimisation;blind source separation;intramuscular electromyography;intracortical recording},
  doi={10.1109/TBME.2024.3446806}}

Contact

For any questions or inquiries, please contact us at:

Agnese Grison
[email protected]