Skip to content

Nadav-Elami/adaptive-syntax-filter

Repository files navigation

Adaptive Syntax Filter

Python 3.11+ License: MIT Research

A Python research package implementing an adaptive Kalmanโ€“EM algorithm for learning time-varying syntax rules in behavioral sequences, with applications to canary song analysis and real-time behavioral monitoring.

Research Group: Neural Syntax Lab at the Weizmann Institute of Science

๐ŸŽฏ Research Overview

Canary songs exhibit rich, history-dependent phrase sequencing whose syntax rules drift on timescales from a few songs to several weeks. This package presents an adaptive Kalmanโ€“EM algorithm that learns:

  • Block-diagonal state-transition matrix F and control vector u
  • Process variance Sigma and initial logit vector x0
  • Time-varying logit vectors that govern soft-max transition probabilities between song phrases

By unifying Bayes' rule, the Chapmanโ€“Kolmogorov equation, and a soft-max observation model, the filterโ€“smoother achieves sub-song latency and detects syntax changes across multiple timescalesโ€”an essential step toward real-time behavioral monitoring in songbirds.

Core Research Question: Can a state-space filtering approach accurately characterize canary-syntax dynamics across timescales from minutes to weeks?

๐Ÿš€ Features

  • Adaptive Kalman Filtering: Real-time parameter estimation with block-diagonal dynamics
  • Higher-Order Markov Models: Support for 1st through 5th order Markov chains
  • Comprehensive Testing: Full test suite with 300+ tests
  • Research Pipeline: Complete experimental framework with visualization
  • Jupyter Integration: Notebooks for experimentation and analysis
  • Modular Architecture: Clean separation of core algorithms, data processing, and visualization

๐Ÿ“ฆ Installation

Prerequisites

  • Python 3.11 or higher
  • pip package manager

Install from Source

# Clone the repository
git clone https://github.com/Nadav-Elami/adaptive-syntax-filter.git
cd adaptive-syntax-filter

# Install in development mode
pip install -e .

# Install development dependencies (optional)
pip install -e ".[dev]"

Quick Verification

# Run the test suite
pytest

# Run a quick demo
python cli.py run --config configs/minimal.yml

๐ŸŽฎ Quick Start

Basic Usage

import numpy as np
from adaptive_syntax_filter.core import EMAlgorithm, StateSpaceManager
from adaptive_syntax_filter.data import SequenceGenerator

# Create a simple first-order Markov model
alphabet = ['<', 'a', 'b', '>']
state_manager = StateSpaceManager(alphabet_size=len(alphabet), markov_order=1)

# Generate synthetic data
generator = SequenceGenerator(alphabet, order=1)
sequences = generator.generate_sequences(n_sequences=10, max_length=20)

# Initialize and run EM algorithm
em = EMAlgorithm(state_manager, max_iterations=10)
results = em.fit(sequences)

print(f"Converged: {results.final_params}")

Command Line Interface

# Run with default configuration
python cli.py run --config configs/minimal.yml

# Run with custom parameters
python cli.py run --config configs/higher_order.yml

# Export results
python export_cli.py --experiment_id my_experiment

๐Ÿ“ Project Structure

adaptive-syntax-filter/
โ”œโ”€โ”€ src/adaptive_syntax_filter/     # Core package
โ”‚   โ”œโ”€โ”€ core/                       # EM algorithm, Kalman filter
โ”‚   โ”œโ”€โ”€ data/                       # Data generation, constraints
โ”‚   โ”œโ”€โ”€ viz/                        # Visualization tools
โ”‚   โ””โ”€โ”€ config/                     # Configuration management
โ”œโ”€โ”€ tests/                          # Comprehensive test suite
โ”œโ”€โ”€ configs/                        # Experiment configurations
โ”œโ”€โ”€ notebooks/                      # Jupyter notebooks
โ”œโ”€โ”€ documentation/                  # Complete documentation
โ”œโ”€โ”€ results/                        # Experiment results
โ””โ”€โ”€ cli.py                         # Command line interface

๐Ÿ”ฌ Research Components

Core Algorithms

  • EM Algorithm: Expectation-maximization for parameter estimation
  • Kalman Filter: Forward filtering and RTS smoothing
  • State Space Management: Higher-order Markov model support
  • Observation Model: Soft-max probability computation

Data Processing

  • Sequence Generation: Synthetic birdsong data generation
  • Constraint System: Syntax rule enforcement
  • Temporal Evolution: Time-varying parameter models
  • Dataset Builder: Research dataset creation

Visualization

  • Logit Evolution: Parameter trajectory visualization
  • Probability Evolution: Transition probability analysis
  • Performance Assessment: Algorithm evaluation tools
  • Publication Figures: Publication-ready plots

๐Ÿ“Š Configuration

The package uses YAML configuration files for experiments:

experiment_id: my_experiment

data:
  alphabet: ['<', 'a', 'b', 'c', '>']
  order: 2
  n_sequences: 100
  max_length: 25
  evolution_type: linear

em:
  max_iterations: 20
  tolerance: 1e-4
  regularization_lambda: 0.001
  damping_factor: 0.1
  adaptive_damping: true

๐Ÿงช Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src/adaptive_syntax_filter

# Run specific test categories
pytest tests/test_core/
pytest tests/test_data/
pytest tests/test_viz/

๐Ÿ“š Documentation

๐ŸŽฏ Research Applications

Birdsong Analysis

  • Real-time syntax rule detection
  • Multi-timescale evolution tracking
  • Behavioral monitoring systems

General Sequence Analysis

  • Time-varying Markov models
  • Adaptive filtering applications
  • Behavioral pattern recognition

๐Ÿค Contributing

We welcome contributions! Please see our Development Guide for details on:

  • Code style and standards
  • Testing requirements
  • Documentation guidelines
  • Research contribution process

๐Ÿ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

๐Ÿ™ Acknowledgments

  • Neural Syntax Lab at the Weizmann Institute of Science
  • Research collaborators and advisors
  • Open source community

๐Ÿ“ž Contact


Note: This is a research package. For production use, additional validation and testing may be required.

Releases

No releases published

Packages

No packages published