mesoscopy
Widefield calcium imaging analysis pipeline.
Usage:
Options:
Subcommands
- 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 a report for a mesoscopy processing step.
- sample: Sample an image frame from an HDF5 file and export it as a PNG.
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
- regions: Extract ∆F signal averages from ABA-defined regions.
- 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.
regions
Extract ∆F signal averages from ABA-defined regions.
Usage:
Options:
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 Output directory for smoothed recording.
--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 registered recording.
-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. output_width (int, optional): Width of the registered frames. Defaults to the Allen CCF template width. output_height (int, optional): Height of the registered frames. Defaults to the Allen CCF template height.
Returns: str: Path to the registered recording file.
Raises: ValueError: If the path to recording landmarks cannot be inferred.
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
--output-width INTEGER Width of the registered frames. Defaults to the
width of the Allen CCF template.
--output-height INTEGER Height of the registered frames. Defaults to
the height of the Allen CCF template.
--help Show this message and exit.
report
Generate a report for a mesoscopy processing step.
Args: path (str): Path to the input file, which should be either a preprocessed or registered recording. out_dir (str): Directory where the report will be saved. Defaults to the current directory
Returns: str: Path to the generated report.
Raises: ValueError: If the input file does not match expected patterns for preprocessing or registration.
Usage:
Options:
sample
Sample an image frame from an HDF5 file and export it as a PNG.
Usage:
Options: