Within-session non-rigid motion, coherent regions, clearer option names

Download Simulate_Ca_Imaging_video.zip below. It unzips to a single folder; put
that folder on the MATLAB path and Simulate_Ca_video is ready to use. Nothing
else is needed.

For scripted downloads the link never changes:

https://github.com/vergaloy/Simulate_Ca_Imaging_video/releases/latest/download/Simulate_Ca_Imaging_video.zip

Simulate_Ca_Imaging_video_1.3.zip is the same archive under the versioned name
used by earlier releases.

Breaking change: the motion options were renamed

Two separate things move the image, and the old names did not say which was
which. Every name now starts with the timescale it acts on. Old names raise an
error naming their replacement, so nothing fails quietly.

Old	New
NR_misalignment	across_session_nonrigid
motion_sz	across_session_nonrigid_scale
translation_misalignment	across_session_translation
session_motion_std	within_session_translation_std
session_nonrigid_std	within_session_nonrigid_std
nonrigid_grid	within_session_nonrigid_grid
session_motion_phi	within_session_motion_smoothness
session_motion_max	within_session_motion_max
session_motion_seed	within_session_motion_seed

across_session_* is one fixed warp per session, which is what an inter-session
alignment stage has to undo. within_session_* is a different shift on every
frame, which is what motion correction has to undo. They are independent, so
a session can be misaligned without shaking, shake without being misaligned, or
both.

Two things the old names hid: across_session_nonrigid_scale is a Gaussian sigma
in pixels, meaning how broad the warp is, not how strong it is. And
across_session_translation is the length of the shift in pixels, not an on/off
flag.

New in this release

• Within-session non-rigid motion. within_session_nonrigid_std bends each
  frame on top of the whole-frame shake, so a piecewise-rigid corrector has
  something real to find. The control points and their trajectories come back as
  ground truth. 0, the default, keeps the motion purely rigid as before.
• A different motion amplitude per session. within_session_translation_std
  now takes one value per session. Equal amplitudes give sessions that end up
  within a pixel or two of each other, which never tests a pipeline that crops
  each session to its own valid region.
• Neurons in regions, with coherent activity. region_areas, region_n,
  region_min_dist and region_corr place neurons in irregular grown regions or
  in 2x2 quadrants, each with its own density and its own activity correlation.
  The correlation that was actually achieved on the calcium traces is measured
  and returned, never assumed.
• Burst clustering. burst_tau makes spikes cluster in time. Thresholding an
  isolated spike train destroys most of the latent correlation, so this is what
  lets the trace correlation reach useful values.
• Denser patches of neurons. dense_region and dense_frac raise the neuron
  density inside given rectangles.
• Fixed: the sign of the simulated non-rigid field. The ground truth was the
  negative of the motion actually applied, which made it anti-correlated with the
  video it described.

Add control to save different variables

Full Changelog: v1.2...v1.22

Add translation motion artifacts to individual sessions

Full Changelog: v1.1...v1.2

Improvements for memory management

v1.1

Improvements to memory manage

First relase

Simulate Ca Video

This project provides a MATLAB function Simulate_Ca_video to simulate calcium imaging videos with various parameters and options. This documentation will guide you through the usage, parameters, and inner workings of the function.

Quick Start

To get started, you can call the function with default or customized parameters:

[out, Mot, outpath, file_name, A] = Simulate_Ca_video('Nneu', 100, 'ses', 2, 'CA1_A', true, 'PNR', 1);

For detailed information on each parameter and sub-function, please refer to the Function Documentation section.

Function Documentation

Syntax

[out, Mot, outpath, file_name, A] = Simulate_Ca_video(varargin)

Description

The Simulate_Ca_video function generates simulated calcium imaging videos with neural data, motion artifacts, and noise. It allows for customization of various parameters including the number of neurons, sessions, frame rate, and more.

Parameters

• 'outpath': Output path where simulation results will be saved.
• 'min_dist': Minimum distance between neurons in the simulated data.
• 'Nneu': Number of neurons to be simulated.
• 'PNR': Peak-to-Noise Ratio for the simulated data.
• 'd': Dimensions of the simulated video frames (width and height) in pixels.
• 'F': Frame rate (frames per second) for the simulated calcium video data.
• 'overlap': Proportion of neurons remapping across multiple sessions.
• 'motion': Inter-session misalignment amplitude.
• 'motion_sz': Size of the motion effect applied to the frames.
• 'translation': Add translation misalignment in addition to Non-rigid motion.
• 'ses': Number of sessions to be generated.
• 'seed': Random number generator seed.
• 'B': Baseline id for different baseline images.
• 'spike_prob': Probability distribution parameters for spike events.
• 'save_files': Flag to save simulation results.
• 'create_mask': Flag to create a mask during the simulation.
• 'comb_fact': Combination factor used in the simulation process.
• 'drift': Presence of drifting activities in the simulated data.
• 'LFP': Flag to simulate Local Field Potentials data.
• 'sf': Scaling factor used in the simulation process.
• 'plotme': Flag to generate plots during simulation.
• 'invtRise': Parameters related to the rising phase of calcium signals.
• 'invtDecay': Parameters related to the decaying phase of calcium signals.
• 'disappearBV': Erode baseline value.
• 'CA1_A': Change neurons shapes across sessions using CA1 data.
• 'A2': Use CA1 neurons shapes instead of DG.
• 'force_active': Ensure all neurons have at least one Calcium transient per session.

Usage Examples

% Example 1
[out, Mot, outpath, file_name, A] = Simulate_Ca_video('Nneu', 100, 'ses', 2, 'CA1_A', true, 'PNR', 1);

% Example 2
[out, Mot, outpath, file_name, A] = Simulate_Ca_video('Nneu', 50, 'ses', 1, 'F', 18000, 'LFP', 8, 'spike_prob', [-4.91, 0.83], 'sf', 60);

% Example 3
[out, Mot, outpath, file_name, A] = Simulate_Ca_video('Nneu', 300, 'ses', 20, 'F', 1500, 'motion', 0, 'min_dist', 2, 'spike_prob', [-2, 0.83], 'A2', true, 'overlap', 0.2);

Detailed Function Workflow

1. Initialize Variables: Using int_var to parse input parameters.
2. Create Baselines: Generate baseline images using create_baseline.
3. Create Neural Data: Generate neural data using create_neuron_data.
4. Apply Overlapping Mask: Apply remapping and drifting effects to the data.
5. Add Non-Rigid Motion: Introduce motion artifacts to the sessions using Add_NRmotion.
6. Create Noise Data: Generate and add noise to the simulated data.
7. Integrate Model: Combine all components to form the final simulated video.
8. Save Results: Save the output if the save_files flag is set.

Sub-Functions

int_var

Parses and initializes input parameters for the simulation.

get_out_path

Determines the output path for saving simulation results.

create_baseline

Generates baseline images for the simulation.

add_remapping_drifting

Applies remapping and drifting effects to the neural data.

Add_NRmotion

Adds non-rigid motion artifacts to the sessions.

saveash5

Saves data in HDF5 format.