Source code for unravel.abca.merfish.merfish_cells_to_nii

#!/usr/bin/env python3

"""
Use ``abca_merfish_cells_to_nii`` or ``mc`` from UNRAVEL to convert ABCA MERFISH cells to a .nii.gz 3D image.

Prereqs:
    - ``merfish_cluster`` or ``merfish_filter`` to generate filtered cell data.

Usage:
------
    abca_merfish_cells_to_nii -i path/filtered_cells.csv -r path/to/reference.nii.gz [-b] [-o path/to/output.nii.gz] [-v]
"""

import nibabel as nib
import numpy as np
import pandas as pd
from pathlib import Path
from rich import print
from rich.traceback import install

from unravel.core.help_formatter import RichArgumentParser, SuppressMetavar, SM
from unravel.core.config import Configuration 
from unravel.core.utils import log_command, verbose_start_msg, verbose_end_msg, print_func_name_args_times


[docs] def parse_args(): parser = RichArgumentParser(formatter_class=SuppressMetavar, add_help=False, docstring=__doc__) reqs = parser.add_argument_group('Required arguments') reqs.add_argument('-i', '--input', help='path/filtered_cells.csv', required=True, action=SM) reqs.add_argument('-r', '--ref_nii', help='Path to reference .nii.gz for header info (e.g., image_volumes/MERFISH-C57BL6J-638850-CCF/20230630/resampled_annotation.nii.gz)', required=True, action=SM) opts = parser.add_argument_group('Optional arguments') opts.add_argument('-b', '--bin', help='Binarize the image. Default: False', action='store_true', default=False) opts.add_argument('-o', '--output', help='Output path for the saved .nii.gz image. Default: None', default=None, action=SM) general = parser.add_argument_group('General arguments') general.add_argument('-v', '--verbose', help='Increase verbosity. Default: False', action='store_true', default=False) return parser.parse_args()
[docs] @print_func_name_args_times() def merfish_cells_to_img(cell_df, img, xy_res, z_res): """ Convert MERFISH cell metadata into a 3D image by marking voxel positions of cells. Parameters ---------- cell_df : pd.DataFrame DataFrame containing filtered cell metadata with reconstructed coordinates. img : np.ndarray An empty 3D NumPy array shaped like the reference .nii.gz image. xy_res : float Resolution of the x-y plane in microns (µm). z_res : float Resolution of the z-plane in microns (µm). Returns ------- np.ndarray A 3D image where cell positions are marked with 1. """ if cell_df.empty: print("[bold yellow]Warning:[/bold yellow] No cells found in the input CSV. Returning empty image.") return img # Convert resolution to mm xy_res_mm = xy_res / 1000 z_res_mm = z_res / 1000 # Get image shape x_size, y_size, z_size = img.shape # Convert reconstructed coordinates to voxel indices cell_df['x_voxel'] = (cell_df['x_reconstructed'] / xy_res_mm).astype(int) cell_df['y_voxel'] = (cell_df['y_reconstructed'] / xy_res_mm).astype(int) cell_df['z_voxel'] = (cell_df['z_reconstructed'] / z_res_mm).astype(int) # Clip voxel indices to prevent out-of-bounds errors cell_df['x_voxel'] = cell_df['x_voxel'].clip(0, x_size - 1) cell_df['y_voxel'] = cell_df['y_voxel'].clip(0, y_size - 1) cell_df['z_voxel'] = cell_df['z_voxel'].clip(0, z_size - 1) # Remove NaNs to avoid indexing issues cell_df.dropna(subset=['x_voxel', 'y_voxel', 'z_voxel'], inplace=True) # Mark voxel positions in the image for _, row in cell_df.iterrows(): img[row['x_voxel'], row['y_voxel'], row['z_voxel']] = 1 return img
[docs] @log_command def main(): install() args = parse_args() Configuration.verbose = args.verbose verbose_start_msg() # Load the filtered cell metadata cell_df = pd.read_csv(args.input, dtype={'cell_label': str}, usecols=['cell_label', 'brain_section_label', 'x_reconstructed', 'y_reconstructed', 'z_reconstructed']) # Load reference image ref_nii = nib.load(args.ref_nii) img = np.zeros(ref_nii.shape, dtype=np.uint8) # Convert cell data to a 3D image img = merfish_cells_to_img(cell_df, img, xy_res=10, z_res=200) # Binarize the image if specified if args.bin: img[img > 0] = 1 # Set output path if args.output: output_path = Path(args.output) else: suffix = '_bin.nii.gz' if args.bin else '.nii.gz' output_path = str(Path(args.input)).replace('.csv', suffix) # Save the image as a .nii.gz file nii_img = nib.Nifti1Image(img, affine=ref_nii.affine, header=ref_nii.header) nib.save(nii_img, output_path) print(f"\n [bold green]Saved image to {output_path}[/bold green]\n") verbose_end_msg()
if __name__ == '__main__': main()