A research-grade Python package for LFADS-style sequential autoencoder analysis of birdsong syntax and neural dynamics. This package provides comprehensive tools for data generation, model training, evaluation, and advanced latent space analysis of birdsong sequences.
Developed at The Neural Syntax Lab at the Weizmann Institute of Science, this package implements sequential autoencoders inspired by the LFADS (Latent Factor Analysis via Dynamical Systems) framework for analyzing the temporal structure and syntax of birdsong.
# Install in development mode
pip install -e .
# Install with development dependencies
pip install -e .[dev]# Train with default configuration
birdsong-train --config configs/default.yaml
# Train with custom parameters
birdsong-train --config configs/default.yaml --epochs 100 --batch-size 32# Evaluate a trained checkpoint
birdsong-eval --checkpoint checkpoints/model_epoch_50.pt
# Generate plots and metrics
birdsong-eval --checkpoint checkpoints/model_epoch_50.pt --output-dir results/# Analyze latent space with PCA
birdsong-analyze --checkpoint checkpoints/model_epoch_50.pt --data-path data.h5 --reduction-method pca
# Analyze with t-SNE and clustering
birdsong-analyze --checkpoint checkpoints/model_epoch_50.pt --data-path data.h5 --reduction-method tsne --clustering-method kmeans --n-clusters 5
# Interactive analysis with UMAP
birdsong-analyze --checkpoint checkpoints/model_epoch_50.pt --data-path data.h5 --reduction-method umap --interactivefrom birdsong import BirdsongLFADSModel2, BirdsongDataset, BirdsongTrainer
from birdsong.analysis import LatentSpaceAnalyzer
# Load data
dataset = BirdsongDataset("path/to/data.h5")
# Create model
model = BirdsongLFADSModel2(
input_size=dataset.input_size,
hidden_size=128,
latent_size=32
)
# Train model
trainer = BirdsongTrainer(model, dataset)
trainer.train(epochs=100, batch_size=32)
# Analyze latent representations
analyzer = LatentSpaceAnalyzer(model, device)
analysis_results = analyzer.analyze_latent_space(
latent_type='factors',
reduction_method='pca',
clustering_method='kmeans'
)src/birdsong/
├── data/ # Data loaders and simulation
├── models/ # LFADS model and loss functions
├── training/ # Training loop and utilities
├── evaluation/ # Evaluation and plotting
├── analysis/ # Latent space analysis tools
└── cli/ # Command-line interfaces
# Run all tests
pytest
# Run with coverage
pytest --cov=src/birdsong
# Run specific test file
pytest tests/test_regression.py# Format code
black src/ tests/
# Lint code
ruff check src/ tests/docs/motivation.md- Research motivation and backgrounddocs/architecture.md- Package architecture and design decisions
This work was inspired by and builds upon the LFADS framework:
Pandarinath, C., O'Shea, D.J., Collins, J., Jozefowicz, R., Stavisky, S.D., Kao, J.C., Trautmann, E.M., Kaufman, M.T., Ryu, S.I., Hochberg, L.R. and Henderson, J.M., 2018. Inferring single-trial neural population dynamics using sequential auto-encoders. Nature methods, 15(10), pp.805-815.
Special thanks to the broader birdsong research community and the neural computation community for their foundational work in understanding the neural basis of learned vocal behavior.
The Neural Syntax Lab
Weizmann Institute of Science
Department of Brain Sciences
Lab Website: https://www.weizmann.ac.il/brain-sciences/labs/cohen/
Lab GitHub: @NeuralSyntaxLab
Author: Nadav Elami (nadav.elami@weizmann.ac.il)
GitHub: @Nadav-Elami
For bug reports, feature requests, or research collaborations, please open an issue or contact us directly.
MIT License - see LICENSE file for details.
Copyright (c) 2025 Nadav Elami, The Neural Syntax Lab, Weizmann Institute of Science