Motivation for staging raw tiles + ASHLAR registration instead of using MACS iQ View’s appending function

[yujxiao]

Thank you for developing this amazing tool macsima2mc ! I’m working with MACSIMA-generated data and aim to integrate MCMICRO for enhanced segmentation and downstream analysis. So I am wondering if you have experience in both the naive appending by MACS iQ View and the appending by the MCMICRO algorithm ASHLAR.

Current Workflow

• Using MACS iQ View’s built-in appending/stitching function to generate registered TIFFs.

Questions

1. Quality Comparison:

   • Does ASHLAR algorithm offer advantages over MACS iQ View’s appending(e.g., improved alignment accuracy, artifact correction, or multi-cycle consistency)?

2. Compatibility:

   • Are MACS iQ View’s stitched TIFFs compatible with MCMICRO’s segmentation steps without reprocessing through ASHLAR?

Thank you for your insight!

[josenimo]

In my experience, MACS iQ stitching can be good, but I have seen it fail catastrophically (see below).

nothing to say about campatibility, it should be compatible, unsure if it is

[Lubna-Younas]

We are having stitching issues with one of our MACSima TMAs. MACS iQ View didn't work well, so we tried MCMICRO as an alternative. We used the macsima2mc pipeline to convert the raw data (13 cycles) to MCMICRO format and then ran ASHLAR for stitching. Unfortunately, the result was very unusual (see attached screenshot). Could you please review the commands below and suggest any improvements?

macsima2mc command:
OUT=./raw-data/ROI3_macsima2mc
ROI=./raw-data/ROI3

for cyc in "$ROI"/Cycle; do
echo "Processing $cyc"
macsima2mc
-i "$cyc"
-o "$OUT"
-rm DAPI
-wt
-qc
done

ASHLAR command:
mkdir -p ./ROI3_ASHLAR.out

ashlar
-c 0
-o ./ROI3_ASHLAR.out/ROI3_ASHLAR.out.ome.tif
./raw-data/ROI3_macsima2mc/rack-01-well-A01-roi-003-exp-2/raw/src-S.ome.tiff

[josenimo]

@Lubna-Younas the top grid of images suggest you need to flip the y-axis

[josenimo]

try in a subset of cycles, --flip-y ashlar parameter

[VictorDidier]

@Lubna-Younas JoseNimo is right, you have to use the --flip-y flag in ASHLAR when working with macsima images. Thank you for pointing this out, I will add this information to the repo.

Also you might want to use the -ic flag in macsima2mc to apply the flat-field correction to your tiles, thats the usual procedure to avoir vignetting artifacts.

[Lubna-Younas]

Thanks for the clarification, it helped with the axis setup. I have another question regarding the pre-scan fluorescence images folder (labeled "3_Scan2" by default). The macsima2mc pipeline doesn't seem to convert that very first cycle into an OME‑TIFF. We're still seeing registration issues after ASHLAR. I was wondering if we could use the pre‑scan DAPI (cycle0) as a reference instead of the cycle1 DAPI, since cycle1 staining is weaker. Any suggestions?

[VictorDidier]

I remember having a use case similar to what you have, i.e having to use the DAPI signal from the Scan folder. I dont remember the details but I think the solution you mentioned was the quickest fix, rename the "3_Scan2" folder to 3_Cycle0. But just be aware that the .tif files inside the "3_Scan2" folder should follow the same naming pattern as in the Cycle folders, e.g. CYC-001_SCN-001_ST-B_R-01_W-C01_ROI-001_F-001_A-Laminin_C-D-FITCEXP-150.tif .

macsima2mc sorts the tiles based on the values of CYC,ST,R,W,ROI...etc. It might be that you might have to rename also the .tif files in the Scan folder. If you do, just make a copy of the original .tif files to avoid loosing the original acquisition information.

Try this solution. If you get an error let me know and share the naming pattern of the .tif files in the Scan folder.

[Lubna-Younas]

I tried renaming the scan folder from "3_Scane2" to "1_Cycle0" and also changed the file names. For example, renamed "CYC-000_SCN-002_ST-S_R-01_W-A01_ROI-003_F-002_D-APC_EXP-768.tif"
Cycle 1 files look like this "CYC-001_SCN-002_ST-S_R-01_W-A01_ROI-003_F-002_A-CD15_C-VIMC6_D-FITC_EXP-1207.5.tif".
I tried with both "ST-S" and "ST-B", but ended up with the same error every time.
error:
Processing /gpfs/data/fs73045/younas_l/raw-data/1_Cycle0/Cycle
Traceback (most recent call last):
File "/gpfs/data/fs73045/younas_l/miniforge3/bin/macsima2mc", line 7, in
sys.exit(main())
^^^^^^
File "/gpfs/data/fs73045/younas_l/miniforge3/lib/python3.12/site-packages/macsima2mc/macsima2mc.py", line 24, in main
cycle_number=int(cycle_info['cycle'].unique()[0])
~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^
IndexError: index 0 is out of bounds for axis 0 with size 0

Any thoughts? I'd really appreciate some help.
Thank you

[VictorDidier]

@Lubna-Younas it seems that you are missing the marker name (A) in your renamed images. It is important to have a marker name as macsima2mc uses the marker as one of the features to group the tiles. By the way the field A is not missing in the cycle-01 images. Try to add the name of the marker to your "cycle-0" images and see if it solves the problem, if not, let me know if you get a new error.

Anywas, just try the fix below:

[VictorDidier]

@Lubna-Younas, did adding the marker name solved your problem?

[Lubna-Younas]

Dear Victor Didier, Thanks for the follow up. Unfortunately, after renaming, I got the same error. We also realized that using the pre‑scan DAPI as a reference might not work, it just doesn't align well with the later cycles. So I switched to using Cycle 1 DAPI instead and encountered two problems:
1- Histogram values sometimes change, even though I didn't use any correction parameters.
2- We're seeing stitching/registration problems at FOV borders, something we didn't have with MACS iQ View.
I'm not sure if these problems come from the data transformation (macsima2mc) or from ASHLAR?
I have attached the screenshots for your reference. Thank you for your help

[VictorDidier]

@Lubna-Younas macsima2mc does not change the pixel intensity of the raw data, unless you applied flat-field illumination but even then the intensity is just slightly rescaled. Therefore I think that the source of these artifacts is ASHLAR. ASHLAR might have failed to stitch the images correctly, probable due to the high density of cells in the image, the artifacts you are seeing seem to be of the sort mentioned in this issue (ghost artifacts): labsyspharm/ashlar#218. If correcting stitching is critical and you still want to try alternatives for correcting this I have some ideas and probably some scripts to share, let me know and we can set up a call so we dont fill this section with comments unrelated to the issue.

[josenimo]

Dear @Lubna-Younas and @VictorDidier
This seems like an ASHLAR failure, this grid-like blurryness comes from lack of rotation correction.
I would suggest using the rotation-correction development branch:
https://github.com/jmuhlich/ashlar/tree/rotation-correction

[Lubna-Younas]

@VictorDidier I would be happy to discuss on call, please write me on lubna(dot)younas@i-med.ac.at

[VictorDidier]

@josenimo thank you very much for that hint, I did not know there is a rotation correction branch for ASHLAR. That might actually help a lot. I will anyway mail you soon @Lubna-Younas.