mesoscopy
Widefield calcium imaging analysis pipeline.
Usage:
Options:
Subcommands
- align: Write behaviour-aligned frame timestamps to a preprocessed or registered HDF5 recording.
- convert: No description was provided with this command.
- export: Export mesoscopy-generated files.
- inspect: Inspect a calcium recording session and associated preprocessing output. Files must be in NWB format.
- postprocess: No description was provided with this command.
- preprocess: This command will preprocess a single session dual-channel mixed recording to extract a deltaF signal corrected for the haemodynamic response.
- process: No description was provided with this command.
- register: Register recordings to a template.
- report: Generate an HTML report for a mesoscopy processing step.
- sample: Sample an image frame from an HDF5 file and export it as a PNG.
- start-time: Print a recording's start time.
align
Write behaviour-aligned frame timestamps to a preprocessed or registered HDF5 recording.
Usage:
Options:
--session-start TEXT Behaviour session start time, ISO 8601. Mutually
exclusive with --behaviour-json.
--behaviour-json FILE Visiomode behaviour session JSON file; its
'timestamp' key gives the session start.
--behaviour-id TEXT Behaviour session identifier. Required with
--session-start, defaults to the JSON file stem
otherwise.
--max-offset FLOAT Largest allowed offset, in seconds, between the first
frame and the behaviour session start. [default:
600.0]
--help Show this message and exit.
convert
Usage:
Options:
Subcommands
- h5: Convert a raw mesoscale calcium recording session from HDF5 to an NWB file compatible with mesoscopy.
- video: Convert a raw mesoscale calcium recording session from video to an NWB file compatible with mesoscopy.
h5
Convert a raw mesoscale calcium recording session from HDF5 to an NWB file compatible with mesoscopy.
Usage:
Options:
-o, --out-dir PATH Output directory for converted file, defaults
to current working directory. Will be created
if it doesn't exist.
-l, --link-only Create a link to the HDF5 dataset instead of
copying it over. If this is enabled, you MUST
keep the raw HDF5 file - if you delete it, the
data will also be gone.
-f, --frames-group TEXT HDF group path under which frame data is
stored.
-t, --timestamps-group TEXT HDF group path under which timestamp data is
stored.
-m, --meta PATH Path to animal metadata file. Must be YAML or
JSON format.
--subject-id TEXT Metadata field - subject identifier.
--sex [m|f] Metadata field - subject sex.
--genotype TEXT Metadata field - subject genotype.
--species TEXT Metadata field - subject species.
--strain TEXT Metadata field - subject strain.
--dob TEXT Metadata field - subject date of birth in YYYY-
MM-DD format (i.e. 1900-01-31).
--description TEXT Metadata field - session description.
--experimenter TEXT Metadata field - experimenter name.
--lab TEXT Metadata field - lab experiment was done in.
--institution TEXT Metadata field - institution experiment was
done in.
--help Show this message and exit.
video
Convert a raw mesoscale calcium recording session from video to an NWB file compatible with mesoscopy.
Usage:
Options:
-o, --out-dir PATH Output directory for converted file, defaults to
current working directory. Will be created if it
doesn't exist.
-t, --ts-path PATH Path to timestamps file. Must be plain text or
delimited.
-d, --ts-delimiter [,| | ] Timestamp file delimiter, if file is delimited.
-c, --ts-column INTEGER Column in timestamp file to be used as
timestamps. Must be provided if file is
delimited and has more than one column.
--ts-has-header Flag signifying whether or not the timestamps
file has a header row.
-l, --hdf5-only Generate an HDF5 linker file only without
converting to NWB.
-m, --meta PATH Path to animal metadata file. Must be YAML or
JSON format.
--subject-id TEXT Metadata field - subject identifier.
--sex [m|f] Metadata field - subject sex.
--genotype TEXT Metadata field - subject genotype.
--species TEXT Metadata field - subject species.
--strain TEXT Metadata field - subject strain.
--dob TEXT Metadata field - subject date of birth in YYYY-
MM-DD format (i.e. 1900-01-31).
--description TEXT Metadata field - session description.
--experimenter TEXT Metadata field - experimenter name.
--lab TEXT Metadata field - lab experiment was done in.
--institution TEXT Metadata field - institution experiment was done
in.
--help Show this message and exit.
export
Export mesoscopy-generated files.
Usage:
Options:
Subcommands
- deltaf: Export delta F frames as a video file.
- nwb: Create a sharable copy of an NWB file by resolving external data links.
- timestamps: Export timestamps as a text file.
deltaf
Export delta F frames as a video file.
Usage:
Options:
--out-path PATH Path to save the exported video file.If not provided, the
output file will be named as the input file with
'_deltaf.mp4' appended.
--help Show this message and exit.
nwb
Create a sharable copy of an NWB file by resolving external data links.
Usage:
Options:
--out-path FILE Path to save the exported NWB file. If not provided, the
output file will be named as the input file with
'_export.nwb' appended.
--help Show this message and exit.
timestamps
Export timestamps as a text file.
Usage:
Options:
inspect
Inspect a calcium recording session and associated preprocessing output. Files must be in NWB format.
Usage:
Options:
postprocess
Usage:
Options:
preprocess
This command will preprocess a single session dual-channel mixed recording to extract a deltaF signal corrected for the haemodynamic response.
Usage:
Options:
-o, --out_dir PATH Output directory for preprocessed recording.
--chunks INTEGER Number of chunks to load in memory.
--crop INTEGER Number of pixels to crop from the edges of the
recording.
--bins INTEGER Recording pixel binning factor.
--channel-means-only Extract the channel means and exit without extracting
a delta F series.
--use-means Separate channels using means histogram instead of
standard deviation.
--flip-channels Flip channel order.
--interim_dir PATH
--skip-start INTEGER Number of frames to skip at the start of the
recording.
--skip-end INTEGER Number of frames to skip at the end of the recording.
--no-qa Skip automatic quality control checks.
--help Show this message and exit.
process
Usage:
Options:
Subcommands
- connectivity: Measure pairwise connectivity between regions, over the cue-to-response epoch or over whole traces.
- decode: Decode the stimulus or the lever push of each trial from region activity.
- metrics: Extract per-trial response metrics and per-session variability from peri-event traces.
- peri-event: Extract per-trial windows around a behavioural event from a behaviour-aligned recording.
- regions: Extract ∆F signal averages from ABA-defined regions, custom region masks, or both.
- regression: Perform pixel-wise ridge regression on a preprocessed ∆F/F recording.
- smooth: Generate a smoothed DeltaF/F recording using a Laplace of Gaussian filter.
- zscore: Pixel-wise z-score ∆F/F signal.
connectivity
Measure pairwise connectivity between regions, over the cue-to-response epoch or over whole traces.
PATH is the long-format _perievent.csv written by process peri-event, or the _regions.csv written by
process regions. Writes process metrics, extended past the
response by --response-pad; without the cue_onset and response_time columns the whole response window is used.
Go/no-go sessions are grouped by sdt_type, go/no-go stimulus and lever push, as well as all trials. With
--with-rolling it also writes
A regions CSV gives the metrics over the whole recording instead, as the all-trials rows only, without the residual and per-trial columns. The trial options and --with-rolling do not apply.
Usage:
Options:
-o, --out_dir PATH Output directory for the connectivity table.
--response <FLOAT FLOAT>... Response window START END, seconds relative
to the event, end inclusive. Defaults to all
post-event samples. Peri-event input only.
-t, --trials FILE Trials CSV to join by trial_index, for peri-
event files without trials columns. Peri-
event input only.
--min-trials INTEGER RANGE Trial groups with fewer trials get empty
metrics. The all-trials metrics are always
taken. Peri-event input only. [default: 10;
x>=1]
--mask-response / --no-mask-response
End cue-aligned epochs at each trial's
response; trials without one end at the
median response time. Peri-event input only.
[default: mask-response]
--min-rt FLOAT RANGE Drop trials with a response time below this,
in seconds. Peri-event input only.
[default: 0.2; x>=0]
--response-pad FLOAT RANGE Extend each epoch past the response by this,
in seconds. Cue-aligned epochs still end
within the response window. Peri-event input
only. [default: 0.0; x>=0]
--max-lag FLOAT RANGE Largest lag searched for the peak cross-
correlation, in seconds. [default: 0.5;
x>=0]
--mi-neighbours INTEGER RANGE Neighbours for the mutual information
estimator. [default: 3; x>=1]
--with-mi / --no-mi Estimate the mutual information of each
pair, the slowest part. [default: with-mi]
--te-history INTEGER RANGE Past samples of the target the transfer
entropy conditions on. [default: 1; x>=1]
--te-surrogates INTEGER RANGE Surrogates for the transfer entropy
z-scores: trial shuffles on peri-event
input, circular shifts on a regions CSV. 0
leaves the z-scores out. [default: 200;
x>=0]
--with-te / --no-te Estimate the transfer entropy of each pair
in both directions. [default: no-te]
--with-rolling / --no-rolling Also take r, r_residual, mi and mi_residual
in windows sliding over the whole peri-event
window, written to <stem>_connectivity-
rolling.csv. Peri-event input only.
[default: no-rolling]
--rolling-window FLOAT RANGE Length of the rolling windows, in seconds,
rounded to whole samples. [default: 0.5;
x>0]
--rolling-step FLOAT RANGE Time between the starts of consecutive
rolling windows, in seconds, rounded to
whole samples. [default: 0.1; x>0]
--seed INTEGER Random seed for the surrogates. [default:
42]
--help Show this message and exit.
decode
Decode the stimulus or the lever push of each trial from region activity.
PATH is the long-format *_perievent.csv written by process peri-event for a go/no-go session. A logistic
regression and a linear discriminant decoder are fitted to each region's mean activity between the cue and the
median response time, and to all regions together, under repeated stratified cross-validation, over all trials
and within the groups that hold the other variable constant. Writes
Usage:
Options:
-o, --out_dir PATH Output directory for the decoding tables.
-l, --label [stim|response] What to decode. stim is the go against the
no-go stimulus, response the lever push
against no push. [default: stim]
--response <FLOAT FLOAT>... Response window START END, seconds relative
to the event, end inclusive. Defaults to all
post-event samples.
-t, --trials FILE Trials CSV to join by trial_index, for peri-
event files without trials columns.
--min-trials INTEGER RANGE Trials each class needs in a trial group.
Groups with fewer get empty scores.
[default: 10; x>=1]
--mask-response / --no-mask-response
End the epoch at the response rather than at
the response window end. [default: mask-
response]
--per-trial-end End each trial's epoch at its own response
instead of the median response time.
--min-rt FLOAT RANGE Drop trials with a response time below this,
in seconds. [default: 0.2; x>=0]
--response-pad FLOAT RANGE Extend the epoch past the response by this,
in seconds, within the response window.
[default: 0.0; x>=0]
--folds INTEGER RANGE Folds of the stratified cross-validation.
[default: 5; x>=2]
--repeats INTEGER RANGE Repeats of the cross-validation, each with a
fresh split. [default: 10; x>=1]
--shuffles INTEGER RANGE Label shuffles for the chance level and
p-values. 0 leaves the columns out.
[default: 200; x>=0]
--with-rolling / --no-rolling Also decode in windows sliding over the
whole peri-event window, written to
<stem>_label-<label>_decoding-rolling.csv.
[default: no-rolling]
--rolling-window FLOAT RANGE Length of the rolling windows, in seconds,
rounded to whole samples. [default: 0.5;
x>0]
--rolling-step FLOAT RANGE Time between the starts of consecutive
rolling windows, in seconds, rounded to
whole samples. [default: 0.1; x>0]
--baseline <FLOAT FLOAT>... Window START END, seconds relative to the
event, end exclusive, whose mean gives the
chance level of the rolling table. Defaults
to every sample before the event.
--seed INTEGER Random seed for the splits and the shuffles.
[default: 42]
--help Show this message and exit.
metrics
Extract per-trial response metrics and per-session variability from peri-event traces.
PATH is the long-format *_perievent.csv written by process peri-event. Writes
Also writes
Usage:
Options:
-o, --out_dir PATH Output directory for metrics tables.
--baseline <FLOAT FLOAT>... Baseline window START END, seconds relative
to the event, end exclusive. Defaults to all
pre-event samples.
-t, --trials FILE Trials CSV to join onto the per-trial table
by trial_index, for peri-event files without
trials columns.
--response <FLOAT FLOAT>... Response window START END, seconds relative
to the event, end inclusive. Defaults to all
post-event samples.
--onset [sd|peak|extrapolate] Onset by threshold at a multiple of the
baseline SD or a fraction of the amplitude,
or by extrapolating a line fitted to the
rise back to baseline. [default: sd]
--onset-sd FLOAT Baseline SD multiple for --onset sd.
[default: 2.0]
--onset-fraction FLOAT Amplitude fraction for --onset peak.
[default: 0.2]
--onset-min-samples INTEGER Consecutive samples above threshold required
for an onset. [default: 3]
--extrapolate-range <FLOAT FLOAT>...
Amplitude fractions LOW HIGH bounding the
rise fitted for --onset extrapolate.
[default: 0.2, 0.8]
--smooth INTEGER Moving-average window in samples, odd, for
peak, onset, decay and offset detection. 1
disables. [default: 1]
--decay-fraction FLOAT Amplitude fraction the trace must fall to
after the peak. [default: 0.5]
--min-trials INTEGER RANGE Trial groups with fewer trials get empty
session summaries, reliability and mean-
trace metrics. The all-trials session
summaries are always taken. [default: 10;
x>=1]
--mask-response / --no-mask-response
End cue-aligned reliability epochs at each
trial's response; trials without one end at
the median response time. [default: mask-
response]
--min-rt FLOAT RANGE Drop trials with a response time below this,
in seconds, from the reliability metrics.
[default: 0.2; x>=0]
--response-sd FLOAT Baseline SD multiple a trial's mean epoch
response must exceed for response_fraction.
[default: 2.0]
--time-warp Resample each reliability epoch onto a
common 0-1 grid.
--cue-baseline <FLOAT FLOAT>...
Baseline window START END relative to each
trial's cue, for lever-aligned reliability
metrics. [default: -1.0, 0.0]
--bootstrap INTEGER RANGE Resamples of each trial group for the mean-
trace metrics and their intervals. 0 skips
them. [default: 10000; x>=0]
--ci FLOAT RANGE Width of the mean-trace metric intervals, in
percent. [default: 95.0; 0<x<100]
--seed INTEGER Random seed for the bootstrap resamples.
[default: 42]
--help Show this message and exit.
peri-event
Extract per-trial windows around a behavioural event from a behaviour-aligned recording.
RECORDING_PATH is an HDF5 recording with /F and /timestamps_aligned, or a _regions.csv with a time_aligned
column. TRIALS_PATH is the *_trials.csv written by visiomode-analysis session. HDF5 input gives HDF5 output;
CSV input gives long-format CSV output with the TRIALS_PATH columns joined onto every row. --with-metrics also
writes the tables of process metrics from the CSV output, using --baseline as the metrics baseline window.
Usage:
Options:
-o, --out_dir PATH Output directory for peri-event windows.
--event [cue_onset|trial_start|response|reward]
Behavioural event to align windows to.
[default: cue_onset]
--pre FLOAT Seconds before the event. [default: 1.0]
--post FLOAT Seconds after the event. [default: 3.0]
--fs FLOAT Sampling rate of the output windows, in Hz.
[default: 25.0]
--method [interp|nearest] Linear interpolation, or the nearest
recorded sample. [default: interp]
--baseline <FLOAT FLOAT>... Baseline window START END, seconds relative
to the event; its mean is subtracted per
trial.
--with-metrics Also write the response metrics of `process
metrics`, joined with TRIALS_PATH. CSV input
only.
--response <FLOAT FLOAT>... Response window START END, seconds relative
to the event, end inclusive. Defaults to all
post-event samples.
--onset [sd|peak|extrapolate] Onset by threshold at a multiple of the
baseline SD or a fraction of the amplitude,
or by extrapolating a line fitted to the
rise back to baseline. [default: sd]
--onset-sd FLOAT Baseline SD multiple for --onset sd.
[default: 2.0]
--onset-fraction FLOAT Amplitude fraction for --onset peak.
[default: 0.2]
--onset-min-samples INTEGER Consecutive samples above threshold required
for an onset. [default: 3]
--extrapolate-range <FLOAT FLOAT>...
Amplitude fractions LOW HIGH bounding the
rise fitted for --onset extrapolate.
[default: 0.2, 0.8]
--smooth INTEGER Moving-average window in samples, odd, for
peak, onset, decay and offset detection. 1
disables. [default: 1]
--decay-fraction FLOAT Amplitude fraction the trace must fall to
after the peak. [default: 0.5]
--min-trials INTEGER RANGE Trial groups with fewer trials get empty
session summaries, reliability and mean-
trace metrics. The all-trials session
summaries are always taken. [default: 10;
x>=1]
--mask-response / --no-mask-response
End cue-aligned reliability epochs at each
trial's response; trials without one end at
the median response time. [default: mask-
response]
--min-rt FLOAT RANGE Drop trials with a response time below this,
in seconds, from the reliability metrics.
[default: 0.2; x>=0]
--response-sd FLOAT Baseline SD multiple a trial's mean epoch
response must exceed for response_fraction.
[default: 2.0]
--time-warp Resample each reliability epoch onto a
common 0-1 grid.
--cue-baseline <FLOAT FLOAT>...
Baseline window START END relative to each
trial's cue, for lever-aligned reliability
metrics. [default: -1.0, 0.0]
--bootstrap INTEGER RANGE Resamples of each trial group for the mean-
trace metrics and their intervals. 0 skips
them. [default: 10000; x>=0]
--ci FLOAT RANGE Width of the mean-trace metric intervals, in
percent. [default: 95.0; 0<x<100]
--seed INTEGER Random seed for the bootstrap resamples.
[default: 42]
--help Show this message and exit.
regions
Extract ∆F signal averages from ABA-defined regions, custom region masks, or both.
Usage:
Options:
-o, --out_dir PATH Output directory for region activity file.
-m, --mask PATH Path to a custom region mask file (NPY, NPZ or TIFF),
drawn in registered frame coordinates. A boolean mask is
extracted as a single region, named after the file (or,
for NPZ files, after each key); an integer-labelled mask
is extracted as one region per label, named
'<name>_<label>'. Masks are used as drawn and are not
mirrored across hemispheres. May be passed multiple
times to combine masks from several files. Supplying a
mask replaces the ABA region extraction unless
--include-aba is given.
--include-aba Extract ABA-defined regions alongside any custom masks.
Has no effect if no mask is supplied.
--help Show this message and exit.
regression
Perform pixel-wise ridge regression on a preprocessed ∆F/F recording.
Usage:
Options:
-o, --out_dir PATH Output directory for regression results.
-a, --alpha FLOAT Ridge regularisation strength. Defaults to
1.0.
-n, --nuisance-regressors PATH Path to an external nuisance regressor file
(NPZ or HDF5), e.g. behavioural motion
energy. Every array/dataset in the file
other than 'timestamps' is treated as one
nuisance regressor and interpolated onto the
recording's own timestamps before being
z-scored and appended to the regressor
matrix. May be passed multiple times to add
nuisance regressors from several files.
-f, --fast Use fast vectorised implementation of ridge
regression. This is an experimental feature
and may not work for all datasets. Use with
caution. Defaults to False.
--npz Save regression results as a compressed
NumPy .npz file. Defaults to True.
--h5 Save regression results as an HDF5 file.
Defaults to False.
--help Show this message and exit.
smooth
Generate a smoothed DeltaF/F recording using a Laplace of Gaussian filter.
Usage:
Options:
-o, --out_dir PATH Output directory for smoothed recording.
-s, --sigma INTEGER Standard deviation of the Gaussian kernel, in pixels.
--help Show this message and exit.
zscore
Pixel-wise z-score ∆F/F signal.
Usage:
Options:
register
Register recordings to a template.
Usage:
Options:
Subcommands
- label: Mark landmarks on a recording for registration to a template using the landmarks GUI.
- landmarks: Register a recording to a template based on defined landmarks.
label
Mark landmarks on a recording for registration to a template using the landmarks GUI.
Args: path (str): Path to preprocessed HDF5 file or NWB file. out_dir (str): Output directory for registration landmarks file. template_points (str): Path to template landmark points in CSV or Fiji XML points format. session_id (str): Session ID for the recording.
Returns: dict: Dictionary with the landmarks and their x-y coordinates. Dictionary keys are landmark names, while x-y coordinates are stored as an (x, y) tuple, i.e. (column, row).
Usage:
Options:
-o, --out_dir PATH Output directory for landmarks file.
-t, --template-points FILE Path to template landmark points in CSV or Fiji
XML points format
--session-id TEXT Session ID for the recording.
--help Show this message and exit.
landmarks
Register a recording to a template based on defined landmarks.
Args:
path (str): Path to preprocessed recording HDF5 or NWB file.
out_dir (str): Output directory for registered recording.
recording_points (str, optional): Path to recording landmark points in CSV or Fiji XML points format.
template_points (str, optional): Path to template landmark points in CSV or Fiji XML points format.
scale (float, optional): Scale of the Allen CCF template, relative to its native size. Defaults to the
scale matching the recording's pixel size.
output_width (int, optional): Deprecated, use scale. Width of the registered frames.
output_height (int, optional): Deprecated, use scale. Height of the registered frames.
Returns: str: Path to the registered recording file.
Raises: ValueError: If the path to recording landmarks cannot be inferred, or the options conflict.
Usage:
Options:
-o, --out_dir PATH Output directory for registered recording.
-r, --recording-points FILE Path to recording landmark points in Fiji XML
points format
-t, --template-points FILE Path to template landmark points in Fiji XML
points format
-s, --scale FLOAT Scale of the Allen CCF template the frames are
registered to, relative to its native 140x142
pixels. Defaults to the scale at which template
pixels match the recording's pixel size, so the
recording keeps its own resolution. Ignored
with -t.
--output-width INTEGER Deprecated, use --scale. Width of the
registered frames.
--output-height INTEGER Deprecated, use --scale. Height of the
registered frames.
--help Show this message and exit.
report
Generate an HTML report for a mesoscopy processing step.
PATH is a _preprocessed.h5, _registered.h5 or _perievent.csv file. Peri-event reports pick up the
_metrics.csv and _metrics-session.csv written by process metrics and the _connectivity.csv written by
process connectivity next to the input when present.
Args: path (str): Path to the input file. out_dir (str): Directory where the report will be saved. Defaults to the current directory trials (str, optional): Trials CSV for peri-event files without an sdt_type column.
Returns: str: Path to the generated report.
Usage:
Options:
-o, --out_dir PATH Output directory for the report.
-t, --trials FILE Trials CSV giving sdt_type per trial, for peri-event
files written without it.
--help Show this message and exit.
sample
Sample an image frame from an HDF5 file and export it as a PNG.
Usage:
Options:
--index INTEGER Index of frame to sample. [default: 0]
--crop INTEGER
--vmin FLOAT
--vmax FLOAT
--key TEXT Activity column
--help Show this message and exit.
start-time
Print a recording's start time.
This is the first /timestamps entry of an HDF5 file, or the session_start_time of an NWB file, as stored.
Usage:
Options: