BrainConnect 1.0.0

A flexible pipeline to integrate brain connectivity and spatial transcriptomics for downstream analysis

a flexible pipeline to integrate brain connectivity and spatial transcriptomics for downstream analysis

Installation

pip install BrainConnect

Quick Start

conda create -n neuron python=3.12
conda activate neuron
pip install BrainConnect

Help Documentation

BrainConnect [-h] [-v] <command> ...

BrainConnect - Complete neuronal data analysis workflow

options:
  -h, --help     show this help message and exit
  -v, --version  show program's version number and exit

Workflow commands:
  <command>
    download     Download Allen experimental data
    preprocess   Preprocess experimental data
    swc          SWC file processing and analysis
    feature      Feature extraction and integration
    fusion       Multimodal data fusion
    model        Model training and prediction

Complete workflow examples:

# 1. Download experimental data
BrainConnect download --experiments data/experiments.csv --download-dir data/experiment_data --annotation data/annotation_25.nrrd --limit 10

# 2. Preprocess experimental data
BrainConnect preprocess --experiments data/experiments.csv --download-dir data/experiment_data --annotation data/annotation_25.nrrd --output-dir data/experiment_data/result

# 3. Process SWC files
BrainConnect swc --annotation data/annotation_25.nrrd --input data/orig_swc_data/ --output results/swc_results.csv

# 4. Extract features
BrainConnect feature --swc-results results/swc_results.csv --adjacency data/adjacency_matrix.csv --output results/features.csv

# 5. Data fusion
BrainConnect fusion --features results/features.csv --experiment-results data/experiment_data/result/merged_results.csv --output results/fusion_results.csv

# 6. Train model
BrainConnect model --fusion-results results/fusion_results.csv --gene-data data/gene_data.csv --output results/gene_importance.csv

Requirements:

• Python 3.12+

• Dependencies: pandas, numpy, tensorflow, pyswcloader, networkx

Version: 1.0.0

Step-by-Step Workflow

1. Download Experimental Data:

   BrainConnect download [-h] --experiments EXPERIMENTS --download-dir DOWNLOAD_DIR --annotation ANNOTATION [--allen-tree ALLEN_TREE] [--acro-dict ACRO_DICT] [--limit LIMIT]

   options:
     -h, --help            show this help message and exit
     --experiments EXPERIMENTS, -e EXPERIMENTS
                           Experimental data file path
     --download-dir DOWNLOAD_DIR
                           Data download directory
     --annotation ANNOTATION, -a ANNOTATION
                           Brain annotation file path
     --allen-tree ALLEN_TREE
                           Allen brain tree file path
     --acro-dict ACRO_DICT
                           Acronym dictionary file path
     --limit LIMIT, -n LIMIT
                           Download quantity limit (0 means download all)

   Example:

   BrainConnect download \
     --experiments data/experiments.csv \
     --download-dir data/experiment_data \
     --annotation data/annotation_25.nrrd \
     --limit 10

2. Preprocess Experimental Data:

   BrainConnect preprocess [-h] --experiments EXPERIMENTS --download-dir DOWNLOAD_DIR --annotation ANNOTATION --output-dir OUTPUT_DIR [--allen-tree ALLEN_TREE] [--acro-dict ACRO_DICT] [--use-projection-density]

   options:
     -h, --help            show this help message and exit
     --experiments EXPERIMENTS, -e EXPERIMENTS
                           Experimental data file path
     --download-dir DOWNLOAD_DIR
                           Data download directory
     --annotation ANNOTATION, -a ANNOTATION
                           Brain annotation file path
     --output-dir OUTPUT_DIR
                           Preprocessing results output directory
     --allen-tree ALLEN_TREE
                           Allen brain tree file path
     --acro-dict ACRO_DICT
                           Acronym dictionary file path
     --use-projection-density
                           Use projection density data

   Example:

   BrainConnect preprocess \
     --experiments data/experiments.csv \
     --download-dir data/experiment_data \
     --annotation data/annotation_25.nrrd \
     --output-dir data/experiment_data/result

3. Process SWC Files:

   BrainConnect swc [-h] --annotation ANNOTATION --input INPUT --output OUTPUT [--resolution RESOLUTION] [--allen-tree ALLEN_TREE] [--acro-dict ACRO_DICT]

   options:
     -h, --help            show this help message and exit
     --annotation ANNOTATION, -a ANNOTATION
                           Brain annotation file path
     --input INPUT, -i INPUT
                           Input SWC file directory path
     --output OUTPUT, -o OUTPUT
                           Output results file path
     --resolution RESOLUTION, -r RESOLUTION
                           Resolution parameter
     --allen-tree ALLEN_TREE
                           Allen brain tree file path
     --acro-dict ACRO_DICT
                           Acronym dictionary file path

   Example:

   BrainConnect swc \
     --annotation data/annotation_25.nrrd \
     --input data/orig_swc_data/ \
     --output results/swc_results.csv \
     --resolution 25

4. Extract Features:

   BrainConnect feature [-h] --swc-results SWC_RESULTS --adjacency ADJACENCY --output OUTPUT [--allen-tree ALLEN_TREE] [--acro-dict ACRO_DICT] [--progress-file PROGRESS_FILE]

   options:
     -h, --help            show this help message and exit
     --swc-results SWC_RESULTS, -s SWC_RESULTS
                           SWC processing results file path
     --adjacency ADJACENCY, -adj ADJACENCY
                           Adjacency matrix file path
     --output OUTPUT, -o OUTPUT
                           Output features file path
     --allen-tree ALLEN_TREE
                           Allen brain tree file path
     --acro-dict ACRO_DICT
                           Acronym dictionary file path
     --progress-file PROGRESS_FILE
                           Progress save file path

   Example:

   BrainConnect feature \
     --swc-results results/swc_results.csv \
     --adjacency data/adjacency_matrix.csv \
     --output results/features.csv

5. Data Fusion:

   BrainConnect fusion [-h] --features FEATURES --experiment-results EXPERIMENT_RESULTS --output OUTPUT [--adjacency ADJACENCY] [--allen-tree ALLEN_TREE] [--acro-dict ACRO_DICT] [--min-path-length MIN_PATH_LENGTH]

   options:
     -h, --help            show this help message and exit
     --features FEATURES, -f FEATURES
                           Features file path
     --experiment-results EXPERIMENT_RESULTS, -er EXPERIMENT_RESULTS
                           Experimental data results file path
     --output OUTPUT, -o OUTPUT
                           Output fusion results file path
     --adjacency ADJACENCY
                           Adjacency matrix file path
     --allen-tree ALLEN_TREE
                           Allen brain tree file path
     --acro-dict ACRO_DICT
                           Acronym dictionary file path
     --min-path-length MIN_PATH_LENGTH
                           Minimum path length

   Example:

   BrainConnect fusion \
     --features results/features.csv \
     --experiment-results data/experiment_data/result/merged_results.csv \
     --output results/fusion_results.csv

6. Train Model:

   BrainConnect model [-h] --fusion-results FUSION_RESULTS --gene-data GENE_DATA --output OUTPUT [--acro-dict ACRO_DICT] [--window-size WINDOW_SIZE] [--epochs EPOCHS] [--batch-size BATCH_SIZE]

   options:
     -h, --help            show this help message and exit
     --fusion-results FUSION_RESULTS, -f FUSION_RESULTS
                           Data fusion results file path
     --gene-data GENE_DATA, -g GENE_DATA
                           Gene data file path
     --output OUTPUT, -o OUTPUT
                           Output gene importance file path
     --acro-dict ACRO_DICT
                           Acronym dictionary file path
     --window-size WINDOW_SIZE
                           Sliding window size
     --epochs EPOCHS       Training epochs
     --batch-size BATCH_SIZE
                           Batch size

   Example:

   BrainConnect model \
     --fusion-results results/fusion_results.csv \
     --gene-data data/gene_data.csv \
     --output results/gene_importance.csv

Command Reference

Global Options

• -h, --help: Show help message and exit

• -v, --version: Show program’s version number and exit

Available Commands

download

Download Allen experimental data

BrainConnect download --experiments <file> --download-dir <dir> --annotation <file> [--limit N]

preprocess

Preprocess experimental data

BrainConnect preprocess --experiments <file> --download-dir <dir> --annotation <file> --output-dir <dir>

swc

Process SWC files and analyze neuronal structures

BrainConnect swc --annotation <file> --input <dir> --output <file> [--resolution 25]

feature

Extract and integrate neuronal features

BrainConnect feature --swc-results <file> --adjacency <file> --output <file>

fusion

Perform multimodal data fusion

BrainConnect fusion --features <file> --experiment-results <file> --output <file>

model

Train machine learning models and predict gene importance

BrainConnect model --fusion-results <file> --gene-data <file> --output <file>

File Structure

Input Files

• annotation_25.nrrd: Brain region annotation file

• experiments.csv: Experimental data metadata

• adjacency_matrix.csv: Brain region connectivity matrix

• gene_data.csv: Gene expression data

• SWC files in organized directory structure

Output Files

• swc_results.csv: Processed SWC file results

• features.csv: Extracted neuronal features

• fusion_results.csv: Fused multimodal data

• gene_importance.csv: Gene importance rankings

Configuration

Default configuration can be viewed using:

from BrainConnect import Config
Config.show_info()

Dependencies

• Python 3.12+

• pandas

• numpy

• tensorflow

• pyswcloader

• networkx

Support

For issues and questions, please contact: [e-mail]