MERMAKE processes MERFISH, smFISH, and IF imaging data by detecting local intensity maxima (puncta) in 3D image stacks. In multiplexed experiments (MERFISH), these puncta are decoded using a user-supplied codebook, while in smFISH mode and IF, the puncta are simply called and reported as-is.

To install MERMAKE,

python3 -m pip install mermake

pip install --pre cupy-cuda12x==14.0.0a1 -f https://pip.cupy.dev/pre

MERMAKE relies on CuPy for GPU-accelerated image processing. To run MERMAKE successfully, you must have:

1. An NVIDIA GPU with CUDA support
2. The CUDA Toolkit installed (Refer to the official CuPy installation guide)

the general steps of the MERMAKE merfish pipeline is: Here is a simple flow chart:

graph TD;
    A["microscope"]--image capture-->B["zarr \(images\)"];
    B["zarr \(images\)"]--fitting-->C["xfits \(local maxima\)"];
    C["xfits \(local maxima\)"]--decoding-->D["decoded"];
    C["xfits \(local maxima\)"]--segmentation-->S["segm"];
    D["decoded"]---->E["final spots"];
    S["segm"]---->E["final spots"];
    E["final spots"]---->F["h5ad"];

To run MERMAKE, you'll need to provide a configuration TOML file with a few key settings describing your experiment.

mermake my_settings.toml

If mermake is run without providing a toml file, it will warn about the usage and print out the toml file format. Most users only need to edit the [paths] section.

All other sections ([hybs], [dapi], etc.) are preconfigured for most use cases and usually do not need to be changed. Though to use multi-psfs you will want to set the tilesize to the size of the samping grid (ie 300).

[paths]
codebook = "codebook.csv"
psf_file = "psfs/psf_scope3.npy"
flat_field_tag = "flat_field/Scope3_"
hyb_range = "H1_*_set1:H16_*_set3"
hyb_folders = ["experiment_folder"]
output_folder = "output"
background_range = 'H0_background_set1:H0_background_set3'
#---------------------------------------------------------------------------------------#
#---------------------------------------------------------------------------------------#
#           you probably dont have to change any of the settings below                  #
#---------------------------------------------------------------------------------------#
#---------------------------------------------------------------------------------------#

hyb_save =  '{fov}--{tag}--col{icol}__Xhfits.npz'
dapi_save = '{fov}--{tag}--dapiFeatures.npz'
drift_save = 'drift_Conv_zscan__{ifov:0>3}--_set{iset}.pkl'
regex = '''([A-z]+)(\d+)_([^_]+)_set(\d+)(.*)''' #use triple quotes to avoid double escape

[hybs]
tile_size = 500
overlap = 89
beta = 0.0001
threshold = 3600
blur_radius = 30
delta = 1
delta_fit = 3
sigmaZ = 1
sigmaXY = 1.5

[dapi]
tile_size = 500
overlap = 89
beta = 0.01
threshold = 3.0
blur_radius = 50
delta = 5
delta_fit = 5
sigmaZ = 1
sigmaXY = 1.5

To set the hyb_save toml string to not be dynamic and with different names for each fov and hyb.

hyb_save =  'Xhfits.npz'
dapi_save = '{fov}--{tag}--dapiFeatures.npz'

What this does is trick mermake into thinking the hybs for each fov and channel has already been processed due to the existing Xhfits.npz file