Estimating receptive fields for individual cells via separable LN models

The ln-model package provides a complete framework for fitting separable Linear-Nonlinear (LN) models to neural data, with support for multiple model types, cross-validation, and synthetic data generation. It is designed for electrophysiology data analysis with a focus on receptive field estimation using separable temporal and spatial filters in particular.

Features

• 🧠 Multiple Model Types: Support for Poisson, linear, and logistic regression models
• 🎯 Separable Filters: Efficient temporal-spatial decomposition for receptive field estimation
• 🔄 Cross-Validation: Automated hyperparameter selection with LNModelCV

Installation

1. Add the ln-model directory to your MATLAB path:

   addpath('path/to/ln-model');

2. Or place the +lnModel package directory in your working directory.

Basic Usage

Quick Start

% Create and fit a basic LN model
% Note: stimulus matrix should be [nTimePoints x nSpatialPositions]
model = lnModel.LNModel(20, 'poireg');     % 20 temporal lags, adaptive Poisson model
model.fit(stimulus, responses);            % Fit to your data
predictions = model.predict(testStimulus); % Generate predictions

% Access learned filters
filters = model.getSeparableFilters();     % {temporal, spatial} cell array
combinedFilter = model.getCombinedFilter(); % Full spatiotemporal filter

Cross-Validation for Hyperparameter Selection

% Automatic regularization parameter selection
modelCV = lnModel.LNModelCV(20, 'poireglin', ...
    'regCValues', logspace(-4, 2, 10), 'scoring', 'objective');
modelCV.fit(stimulus, responses);
fprintf('Best regularization: %.2e\n', modelCV.BestRegC);

% Make predictions with optimized model
predictions = modelCV.predict(testStimulus);

Model Types and Configuration

% Available model types
model1 = lnModel.LNModel(20, 'poireglin');  % Adaptive link Poisson (default)
model2 = lnModel.LNModel(20, 'poireg');     % Standard Poisson GLM  
model3 = lnModel.LNModel(20, 'linreg');     % Linear regression
model4 = lnModel.LNModel(20, 'logreg');     % Logistic regression

% With custom regularization
model.fit(stimulus, responses, 'regC', 1e-3);

% With baseline handling
model.fit(stimulus, responses, baseline);    % Fixed baseline
model.fit(stimulus, responses, []);          % Learned bias (default)

Model Types

The package supports four model types: 'poireglin', 'poireg', and 'logreg' are intended for spike data, whereas 'logreg' can be used for input currents.

Advanced Usage

Multi-repetition Cross-Validation

% For multi-repetition data (each column is a repetition)
responses = [rep1, rep2, rep3, rep4, rep5];  % [nTimePoints x nReps]
modelCV = lnModel.LNModelCV(20, 'poireg');

% Each repetition becomes a CV fold automatically
modelCV.fit(stimulus, responses);

Debug and Diagnostics

% Enable detailed debugging
model = lnModel.LNModel(20, 'poireglin');
model.DebugLevel = 2;  % Enables gradient validation
model.fit(stimulus, responses);

% Debug levels:
% 0 - Silent (default)
% 1 - Basic convergence info
% 2 - Gradient validation (errors on failure)  
% 3 - Full diagnostic output

Project Structure

+lnModel/                    % Main package namespace
├── LNModel.m               % Primary model class with fit/predict interface
├── LNModelCV.m             % Cross-validated model with hyperparameter selection
├── +datagen/               % Synthetic data generation utilities
│   ├── generateSyntheticData.m    % Core synthetic response generation
│   └── +stimulus/          % Stimulus generation functions
│       └── whiteNoise.m    % White noise stimulus generator
├── +models/                % Model type implementations
│   ├── BaseModel.m         % Abstract base class for all model types
│   ├── PoiRegLinModel.m    % Adaptive link Poisson model
│   ├── PoiRegModel.m       % Standard Poisson GLM  
│   ├── LinRegModel.m       % Linear regression model
│   ├── LogRegModel.m       % Logistic regression model
│   └── +optimization/      % Mathematical optimization methods
│       ├── NewtonMethod.m  % Newton's method implementation
│       └── LeastSquares.m  % Closed-form least squares
├── +rf/                    % Receptive field estimation components
│   ├── ReceptiveField.m    % Receptive field state management
│   └── RFEstimator.m       % Alternating optimization engine
scripts/                    % Usage examples and tutorials
├── exampleUsage.m          % Comprehensive tutorial with synthetic RGC data
tests/                      % Validation and testing utilities
├── testLinkFunctions.m     % Link function validation tests
docs/                       % Documentation and guidelines
└── STYLEGUIDE.md          % Code style conventions

Key Components

Core Classes

• LNModel: Main interface for model creation, fitting, and prediction
• LNModelCV: Cross-validated version with automatic hyperparameter selection
• ReceptiveField: Manages separable filter representations and computations
• RFEstimator: Implements alternating minimization optimization algorithm

Data Flow

Stimulus → Padding → Filter Convolution → Link Function → Predictions
    ↓           ↓            ↓               ↓            ↓
[n×p] → [(n+k-1)×p] → [n×1] → Link(z) → Response [n×1]

Examples

Complete Workflow Example

% Run the comprehensive tutorial
run('scripts/exampleUsage.m');

This tutorial demonstrates:

• Synthetic RGC data generation with biphasic temporal and center-surround spatial filters
• Model fitting with cross-validation
• Performance evaluation and filter recovery
• Complete visualization of results
• Detailed explanation of matrix padding and convolution operations

Mathematical Framework

Model Equation

All models implement the separable LN framework:

z = (w_temporal ⊗ w_spatial) * X + baseline + bias
y = invLink(z) + noise

Link Functions

• PoiRegLinModel: g(y) = log(y + k) - log(k) for adaptive scaling
• PoiRegModel: g(y) = log(y + ε) for standard Poisson
• LinRegModel: g(y) = y for linear relationship
• LogRegModel: g(y) = logit(y) for binary data

Optimization

Models automatically select appropriate optimization:

• Newton's Method: Nonlinear models (Poisson, logistic)
• Closed-Form: Linear models with analytical solutions
• Alternating Minimization: Coordinate descent for separable filters

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow the style guidelines
4. Add tests for new functionality
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

This project is released under the MIT License.