Imctools

Looking for ways to analyze your dataset? Need help with a software package?
Computational image analysis of multiplexed Imaging Mass Cytometry acquisitions
User avatar
votti
Posts: 21
Joined: Mon Nov 27, 2017 12:46 pm

Imctools

Post by votti » Fri Jan 12, 2018 4:50 pm

https://github.com/BodenmillerGroup/imctools

Imctools is a python based IMC file conversion library that aims to convert IMC rawfiles (.mcd, .txt) into an intermediary, vendor independent ome.tiff format, containing all the relevant metadata. Further it contains tools to generate simpler tiff files that can be directly be used as input files for e.g. CellProfiller, Ilastik, Fiji etc.

As an example it is used in our IMC segmentation pipeline to prepare the data for CellProfiller: https://github.com/BodenmillerGroup/Imc ... onPipeline

As a bonus:
As it contains also a pure python implementation of the converters, imctools can also be used to directly in Fiji (https://fiji.sc/) via Jython.
For a use as FIJI plugin, copy the 'imctools' subfolder into the FIJI plugins directory 'Fiji.app/plugins/'.
Then restart FIJI and imctools should be available in FIJI -> plugins -> imctools.
The two working functions are:
- 'open imc file' -> Can open IMC .txt and .mcd files. Also a .OME.TIFF file is saved in the same folder which can be opened much faster next time
- 'open multichannel ome': -> a helper function to open a multichannel ome file in a way that shows the channel name.

Note that these plugins open the images automatically as an image5d stack. If you want a normal imagej stack just use the plugins -> image5d -> image5d to stack

Please let me know if you have any problems!
Cheers, Vito

MariekeIJsselsteijn
Posts: 4
Joined: Mon Jan 15, 2018 10:52 am

Re: Imctools

Post by MariekeIJsselsteijn » Wed Jan 24, 2018 5:35 pm

Thanks for sharing this tool and histocat.
My knowledge in the use of python is very limited, something i realise is nescesarry and i am working hard on to improve.
I have been able to get the ome.tiff file by using the imctool plugin in Fiji but i was wondering if there is a way to also get the individual marker tiff files through fiji which can be used in the histoCAT software?
Last edited by MariekeIJsselsteijn on Wed Jan 24, 2018 5:35 pm, edited 1 time in total.

RaulCatena
Posts: 25
Joined: Mon Nov 27, 2017 12:49 pm

Re: Imctools

Post by RaulCatena » Wed Jan 24, 2018 6:38 pm

Hello

If you happen to have a Macintosh, you can use histoCAT++ to convert txt, mcd, or tiff into a folder of single channel tiffs that work with histoCAT.

You can download histoCAT++ at
http://www.bodenmillerlab.com/research-2/histocat-2/

Let us know whether you succeed

Regards

User avatar
votti
Posts: 21
Joined: Mon Nov 27, 2017 12:46 pm

Re: Imctools

Post by votti » Thu Jan 25, 2018 4:36 pm

:)
MariekeIJsselsteijn wrote:
Wed Jan 24, 2018 5:35 pm
Thanks for sharing this tool and histocat.
My knowledge in the use of python is very limited, something i realise is nescesarry and i am working hard on to improve.
I have been able to get the ome.tiff file by using the imctool plugin in Fiji but i was wondering if there is a way to also get the individual marker tiff files through fiji which can be used in the histoCAT software?


Hi there!

The export is actually quite easy from Fiji, as FIJI is one of the most flexible Image Processing programs around:
1) Load the ome.tiff using the 'Plugins/imctools/open_multichannel_ome' function (or the open_imc_file when starting from .txt/.mcd), this makes sure the planes in the stack have the correct naming.
2) Convert the image to a stack using 'Plugins/Imag5D/Image5D to stack'
3) Optional: apply some filters, smoothing:
a) Outlier removal: 'Process/Noise/Remove Outliers' works quite nice with radius 2 pixels, Threshold 50 (say yes to apply to all x images when it asks)
b) Gaussian smoothing: 'Process/Filters/Gaussian blur' makes images look more nice using a sigma of < 0.75
4) convert to 16bit: 'Image/Type/16 bit' (Edit: just heard from the HistoCAT main team that this should not be necessary in the latest version)
5) Export the single planes images in a folder: 'File/Save as/Image Sequence' tic 'Use slice labels as file names' then select an existing empty folder or create a folder at this point

This folder than can be loaded in HistoCAT.
If you use this a lot I would recommend recording a macro to do this steps.

Btw: using the inbuilt Segmentation Plugins it should also be fairly easy to make a 'quick and dirty' image segmentation from within FIJI.
I do not think anybody is doing this and it is not offically supported/recommended, but in theory it could be possible:
A mask can be roughly built using: https://imagej.net/Nuclei_Watershed_Separation until the 'Analyze the segmented objects' step
Then it can be exported to HistoCAT by 'Analyze/Analyze Particles' and selecting "Show: 'Count Masks"

The 'Count Masks' image could then be saved as Tiff into the 'HistoCat' folder and selecting it when histoCAT asks if the folder contains a mask or not.
Edit: just tried this quickly by duplicating the Histone channel out of the image stack and then following the ImageJ guide and it works actually more or less :)

Maybe one could even use 'Weka' in FIJI to do pixel classification for a better segmentation, but I unfortunately do not have spare time to play around with this... :cry:

User avatar
sbooth
Posts: 8
Joined: Wed Apr 25, 2018 9:40 pm

Re: Imctools

Post by sbooth » Wed Apr 25, 2018 9:52 pm

Hi Votti,

I am trying to use the imctools as a Fiji plugin as you described. The 'open multichannel ome' function works fine, but the 'open imc' function (which is the one that I need) is throwing the following error in my hands, could you take a look and let me know what you think? Using the latest ver of Fiji (1.52a).
Cheers!

test
Traceback (most recent call last):
File "C:\Users\sbooth\Desktop\Fiji.app\plugins\imctools\imctools\open_imc_file.py", line 14, in <module>
import imctools.io.mcdparserbase as mcdparserbase
File "C:\Users\sbooth\Desktop\Fiji.app\plugins\imctools\imctools\io\mcdparserbase.py", line 11, in <module>
from imctools.io.mcdxmlparser import McdXmlParser
File "C:\Users\sbooth\Desktop\Fiji.app\plugins\imctools\imctools\io\mcdxmlparser.py", line 2, in <module>
import imctools.librarybase as libb
File "C:\Users\sbooth\Desktop\Fiji.app\plugins\imctools\imctools\librarybase.py", line 19
d = {t.tag: {k:v[0] if (len(v) == 1 and ~isinstance(v[0], type(dict()))) else v for k, v in dd.items()}}
^
SyntaxError: no viable alternative at input 'for'

User avatar
votti
Posts: 21
Joined: Mon Nov 27, 2017 12:46 pm

Re: Imctools

Post by votti » Thu Apr 26, 2018 12:40 pm

sbooth wrote:
Wed Apr 25, 2018 9:52 pm
Hi Votti,

I am trying to use the imctools as a Fiji plugin as you described. The 'open multichannel ome' function works fine, but the 'open imc' function (which is the one that I need) is throwing the following error in my hands, could you take a look and let me know what you think? Using the latest ver of Fiji (1.52a).
Cheers!

test
Traceback (most recent call last):
File "C:\Users\sbooth\Desktop\Fiji.app\plugins\imctools\imctools\open_imc_file.py", line 14, in <module>
import imctools.io.mcdparserbase as mcdparserbase
File "C:\Users\sbooth\Desktop\Fiji.app\plugins\imctools\imctools\io\mcdparserbase.py", line 11, in <module>
from imctools.io.mcdxmlparser import McdXmlParser
File "C:\Users\sbooth\Desktop\Fiji.app\plugins\imctools\imctools\io\mcdxmlparser.py", line 2, in <module>
import imctools.librarybase as libb
File "C:\Users\sbooth\Desktop\Fiji.app\plugins\imctools\imctools\librarybase.py", line 19
d = {t.tag: {k:v[0] if (len(v) == 1 and ~isinstance(v[0], type(dict()))) else v for k, v in dd.items()}}
^
SyntaxError: no viable alternative at input 'for'
Hi there!
The error seems to occur during the metadata parsing from the .mcd file. This is usually a sign that the .mcd file is corrupted/was not written correctly, which unfortunately happens occasionally. A sign for this to happen is that there is usually a .schema file kept alongside the .mcd file after acquisition. Using the .txt file is the easiest solution for this problem.

Did/Could you try different files to make sure that this is not the error?
I am also happy to provide you with a test .mcd file.

phobson
Posts: 2
Joined: Tue Jan 30, 2018 12:08 pm

Re: Imctools

Post by phobson » Tue Jun 12, 2018 3:35 pm

Hi,

This is probably a very silly question and more of a quality of life issue, but is there any way to expand the tab with all the channel labels? If I expand the window, the box containing the channels stays exactly the same size.

I'm constantly scrolling back and forth to identify which channel is my channel of interested before I can click on it.

Phil

User avatar
votti
Posts: 21
Joined: Mon Nov 27, 2017 12:46 pm

Re: Imctools

Post by votti » Tue Jun 12, 2018 4:33 pm

I suffered from this con
phobson wrote:
Tue Jun 12, 2018 3:35 pm
Hi,

This is probably a very silly question and more of a quality of life issue, but is there any way to expand the tab with all the channel labels? If I expand the window, the box containing the channels stays exactly the same size.

I'm constantly scrolling back and forth to identify which channel is my channel of interested before I can click on it.

Phil
Hey Phil,

Do you mean the width of the channel selection list in the Image5D viewer of ImageJ, e.g. when using the overlay mode?

As much as I like ImageJ, I am also suffering from this one: unfortunately I am not fluent with Java (the programing language this is written in) and I simply do not have the time to properly investigate it :(
Maybe one could raise at 'issue' at the official Image_5D plugin github page: https://github.com/fiji/Image_5D
I think in the end it would be an easy to fix issue for somebody that knows java.

As an alternative way I usually would use Plugins -> Image5d -> 'Image5D to stack' and browse through it as a stack or duplicate channels out to make a composite image - however I am aware that this is fairly cumbersome. It would be really awesome if somebody could make a proper multiplexed image browser for ImageJ!

Otherwise you can also use HistoCAT (Imctools has also a ome.tiff to HistoCAT folder converter command line tool: https://github.com/BodenmillerGroup/imc ... e2micat.py) or HistoCAT++ (if you happen to own a Mac) for viewing/browsing images.

Another alternative could also be using OMERO for image management and viewing: https://www.openmicroscopy.org/omero/
It is compatible with the OME.tiff that imctools can produce and it seems to get rapidly better/more usable for multiplexed imagining data. There is also a test account available: http://qa.openmicroscopy.org.uk/registry/demo_account/

Cheers, Vito

phobson
Posts: 2
Joined: Tue Jan 30, 2018 12:08 pm

Re: Imctools

Post by phobson » Tue Jun 12, 2018 4:57 pm

Thanks for getting back so quickly Vito,

I'll check out the other software tools.

I do like IMCtools, so thank you for developing it. I will continue to persevere with the sliding bar and hope someone can add this in into the development!

Phil

ssivajothi
Posts: 30
Joined: Thu Jan 11, 2018 9:00 pm

Re: Imctools

Post by ssivajothi » Tue Jul 17, 2018 1:42 pm

Hi Vito,

I am a beginner with Python and IMCtools, just a couple of questions:

1) Is IMCtools package supposed to be 'installed' via terminal or Jupyter notebook? Or am I supposed to copy it somewhere and call it? Sorry if terminology I'm using is wrong
2) is there a way to use histocat++ in this pipeline? For example: take txt/mcd file into histocat++, perform compensation, generate single tiffs for each channel and then take this into your segmentation pipeline? Can you clarify if this is possible or the preferred order for doing it? If I do something like this, which middle part of the script do I start from in your pipeline?

Thank you,
Santhosh

Post Reply