lieberinstitute / vistoseg

Image processing pipeline for spatial projects

VistoSeg

Welcome to VistoSeg!

This repository describes steps to run Image processing on Visium histology images for Spatial transcriptomics. You can see the documentation at http://research.libd.org/VistoSeg.

Internal

JHPCE location: /dcs04/lieber/lcolladotor/spatialDLPFC_LIBD4035/VisiumLIBD

vistoseg's Issues

Citation information and software name

Is there a particular name for the Matlab image processing software? If so, I'd replace Cite us with Cite xx at https://github.com/LieberInstitute/VisiumImgProcessing/blob/705329a25b21f818e62a3606fec4a7af1f757192/index.Rmd#L15 and then include the Bibtex information for citing the software. This is something we'll likely do at the end once you have a small paper describing your work.

You can use available::available() in R to verify that the software name you chose is ok (aka, that it doesn't mean something you don't want it to mean).

Add software requirements

I would add a section like ## Software requirements {-} below the citation information from #3 https://github.com/LieberInstitute/VisiumImgProcessing/blob/705329a25b21f818e62a3606fec4a7af1f757192/index.Rmd#L17 so you can explain what specific version of Matlab this code works on and any particular Matlab dependencies it might have.

If you also need about XX GB of RAM and/or multiple cores, I would mention that too. That will help set the expectations on what you need to have before you can use this software.

Error while running the corrected countSpots_centroid.m code

{Error: File:
/dcs04/lieber/marmaypag/spatialDLPFC_SCZ_LIBD4100/code/vistoseg/lib_updated/countSpots_centroid.m
Line: 36 Column: 18
Functions cannot be indexed using {} or . indexing.

Error in countNuclei (line 30)
[count,prop,countC] = countSpots_centroid(BW, R, tbl, posPath);
}

Avoid full paths

I recommend avoiding full paths like https://github.com/LieberInstitute/VisiumImgProcessing/blob/705329a25b21f818e62a3606fec4a7af1f757192/Step1.Rmd#L8 since that means that a user has to modify the code before they can run it themselves. Instead, you can add a step saying something like "cd directory_where_you_downloaded_the_files".

This can be related to #2.

Update citation information

Hi,

At http://research.libd.org/VistoSeg/index.html#cite-vistoseg the citation information is outdated. Can you update it to point to the pre-print?

Thanks!
Leo

Reviews are back

Reviews are back and tagging @lcolladotor to discuss with @madhavitippani et al. after returning next week to discuss next steps.

Explain how to download the data used in this documentation

Similar to #1, at https://github.com/LieberInstitute/VisiumImgProcessing/blob/705329a25b21f818e62a3606fec4a7af1f757192/Step1.Rmd#L3 or maybe before, I would add a code chunk or description telling readers where they can download these images from. You might want to use the AWS links we have at https://github.com/LieberInstitute/spatialLIBD#raw-data. If you do, make sure the file names match the ones you use in your commands.

Basically, we want readers to be able to run the commands described here on their own computers. This is useful to detect if there are any issues related to software versions or operating systems. That is, users shouldn't get any errors from running these commands, but if they do, we'd want them to report the problem(s) and fix the issues. So in essence, we are giving them a small reproducible example and describing it in this documentation.

image requirements

Dear authors, thank you for developing VistoSeg.
I have a question about the input image requirements to run this tool.
Do we need the original image? or can we use the image from "SpaceRanger" in tissue_hires_image.png format?
if we could used the preprocessed (i.e. cropped images) can you guide me on steps to do so?
thank you in advance!

Getting cropped spot images

Dear VistoSeg team,

Thank you very much for this amazing tool!

I was wondering if it is possible to save the individual images of all spots (similar to the image here - just above section 4.2 http://research.libd.org/VistoSeg/step-4-gui-to-count-nuclei-in-a-visium-spot.html#spotspotcheck) given full resolution tiff image, scalefactors_json and tissue_positions_list.

bookdown info

If you have any questions about bookdown, use https://bookdown.org/yihui/bookdown/. In particular, in the video I'm recording I mentioned that you can link across chapters. The syntax is described at https://bookdown.org/yihui/bookdown/cross-references.html but as you can see, if you change the title of the section/sub-section you are linking to, it breaks the link. So if are using cross references, you need to remember to check any possible broken links whenever you change the title of a section/subsection.

CC @bpardo99 @abspangler13

fine tuning segmentation step

Dear author,

I've tried VistoSeg following your tutorial with my data and found that I need to fine-tune the segmentation step.
I would like to know if we can modify threshold and also split overlapping nuclei.
Here is an example image from spotcheck showing poor counts (counting a single nuclei as multiple fragments; may be we need max&min nuclei size threshold?) and also counting overlapping nuclei as one instead of two.
thank you in advance!

update countSpots() function to count nuclei/spot based on centroid of nuclei

Be more verbose and describe code chunks

On chapters like https://github.com/LieberInstitute/VisiumImgProcessing/blob/705329a25b21f818e62a3606fec4a7af1f757192/Step2.Rmd it's useful to describe what each of the functions you are using do. For example, why do you ned imread() or graythresh() etc. That is, the code ends ups being a small portion of the documentation and you end up with more text. That's the point of the documentation, to describe the code =)

update refineVNS() to provide csv with shape and size metrics

Clarify the docs due to differences between Visium and Visium SPG processing pipeline steps

Hi,

From today's spatial meeting, it sounds like there's a need to clarify the two types of .mat files in Visium and Visium Spatial Proteogenomics (Visium-SPG) processing pipelines, to avoid this confusion in the future. Otherwise you get a silent error: you get numbers but they are not the right ones.

This could be an excellent opportunity for Uma @Ukaipa9 / Boyi @boyiguo1 to learn / practice sending pull requests. Request a DSgs with Nick @Nick-Eagles if you need to learn more about pull requests.

Thanks!
Leo

OSTA vs the documentation in this repo

Think of the documentation that you are writing here as the minimal documentation users need to user your software. We'll likely add more discussion lines once we incorporate your information into OSTA https://github.com/lmweber/OSTA-book with @lmweber.

In the end, both will feed off each other. Like, the documentation you have here such as #4 will likely not exist in OSTA so OSTA will refer to these docs. Yet how your software fits into a more general pipeline for Visium data will likely be a part of OSTA, so you don't have to worry about showing a full analysis pipeline example in your docs..

Write a short paper about your software

Related to #3, I recommend writing a small application note about the software you are documenting here. The paper will be quite small and can have a structure like this:

• introduction: why people would need it and some problems that existed prior to this software
• results: what the software does without any code shown (you might want a schematic figure here)
• methods: anything you need to cite that allowed you to build your software
• discussion: some limitations, context for the software
• funding
• acknowledgments: early users, people who help proofread the docs, etc
• references: a small list

Two typical journals for this type of paper are Oxford Bioinformatics and F1000Research. See https://academic.oup.com/bioinformatics/advance-article/doi/10.1093/bioinformatics/btab152/6162880 and https://academic.oup.com/bioinformatics/article/36/16/4532/5861528 for two similar papers I was involved in recently as well as the spatialLIBD paper we are writing right now https://www.overleaf.com/read/tqvgjssdckqv. Check https://f1000research.com/gateways/bioconductor?selectedDomain=articles for some F1000Research papers others have written. Brenda @bpardo99 checked a few of these before starting the spatialLIBD one.

If you go with Oxford Bioinformatics, check the Application Note format (max 2 pages, 1 figure OR table) https://academic.oup.com/bioinformatics/pages/General_Instructions. The first time you submit the paper it does have to be <= 2 pages. Then in the review process you can expand to 3 (and pay the extra page charge). It'd be up to your team whether to pay the open access fees (I'm in favor of that but it's pricey, like in regutools we didn't have the budget for that).

Another potential journal, though it might not apply here given that your software is based on Matlab code, is the Journal of Open Source Software https://joss.theoj.org/.

Overall with this type of paper, the paper is really small. Most of the work goes into the documentation (if you really want others to use your software).

If you go with Oxford Bioinformatics, create an Overleaf account and use their template which will make it much easier for you https://www.overleaf.com/latex/templates/template-for-oxford-bioinformatics-journal-new-version/zjrmbrmtrytg. That's how we started the spatialLIBD paper. It's like Google Docs but for LaTeX. It's helpful to look at the main.tex from others to see any syntax issues. For citations, you'll need to use Bibtex, so check for example the document.bib for spatialLIBD (I recommend using lastnameYEAR and ordering your citations alphabetically in the .bib file; cc @abspangler13 @bpardo99). Once you are ready to pre-print the paper, I can help you a bit with adding a .cls file that strips out some of the Oxford Bioinformatics info such that you'll be ok uploading the resulting PDF to bioRxiv.

create thresholding function based on refineVNS() metric.csv output

Explain Visium and/or the data used in this documentation

I think that it would be useful to explain to the reader where the data comes from instead of assuming that they know what we are talking about. So before https://github.com/LieberInstitute/VisiumImgProcessing/blob/705329a25b21f818e62a3606fec4a7af1f757192/Step1.Rmd#L3 I suggest describing what data was used for this documentation at https://github.com/LieberInstitute/VisiumImgProcessing/blob/705329a25b21f818e62a3606fec4a7af1f757192/index.Rmd#L11. You could link to say the image we have at https://github.com/LieberInstitute/spatialLIBD/blob/master/man/figures/paper_figure1.jpg and maybe re-use some of the documentation from https://github.com/LieberInstitute/spatialLIBD#study-design.

You could also make it more general and talk also more about Visium from 10X.