After running ANCOM-BC2 and attempting to visualize the results, the resulting html file opens empty in my browser. However, when I upload the QZV file to https://view.qiime2.org/ I do get an interactive figure as expected.
Details
I am using the following commands within the Quay container using apptainer version 1.4.3.
This results in the attached file lvl3-treatment1.visualizer.qzv which is fine in https://view.qiime2.org, but when I open the visualizer/Category-treatment1-level-3/index.html in Firefox 149.0.2 (64-bit) Snap buildt or Chromium Version 147.0.7727.116 (Official Build) snap (64-bit) in Ubuntu 24.04 LTS, the opened page is blank.
The folder visualizer/Category-treatment1-level-3 looks like that:
Firefox 149.0.2 (64-bit) Snap buildt or Chromium Version 147.0.7727.116 (Official Build) snap (64-bit) in Ubuntu 24.04 LTS.
What do you mean with "q2-view"? Is that via https://view.qiime2.org? Because that does work for me too, as mentioned above.
However, when I export the .qzv (via qiime tools export as described above) then the html opens a blank page for me. I attached the folder with the exported html now as well.
Just jumping in to clarify here- these visualizations aren't intended to be exported and viewed via the index.html page. There are two ways to view visualizations, either via q2view (which is just view.qiime2.org) or by running qiime tools view from your terminal and providing the relevant (un-exported) visualization.
thanks for the clarification, thats completely new to me! Until now all index.html that I ever created with QIIME2's qiime tools export did work as I had hoped. Is only that particular visualisation of qiime composition ancombc2-visualizer not intended to be viewed via index.html? Is that an exception or will that be the default in the future? Is there any alternative to obtain a directly viewable html file?
As context: q2view (view.qiime2.org) or running qiime tools view is not an option in an automated pipeline that I maintain and heavily use (ampliseq: Introduction).
I just went back and checked and indeed I can view via the exported index.html page from QIIME2 2026.4.0 the PCoAs, diversities, barplot, ANCOM-BC's da-barplot etc. So I am surprised by this exception.
It has more to do with the complexity of handling larger visualizations.
We used to bend over backwards via strange cross-origin tricks like jsonp to separate and load data. This is why it used to work and still does for many visualizations. However, the tricks needed to perform this really don't cooperate well with sensible web development and modern frameworks. (Every qiime2 visualization is really closer to a portable web-application/dashboard, and fighting CORS the entire time was becoming a real problem and prevents us from doing more interesting things in the future.)
So at this point, the real rule is that the visualization needs to be on the same origin (any origin is fine, but because each file:// URI is actually a unique origin this isn't going to work).
You could use python -m http.server or any equivalent static file server if that was a reasonable option. For ampliseq, is there any special utility to the bare HTML file? The user would still need a browser and to copy all of the side-car files that the HTML depends on, so leaving it as a qzv seems easier, more portable, and preserves provenance.
I am not familiar how to build such HTML visualizations or how much effort that needs, but MultiQC seems to handle it by integrating all the data into one self-sufficient HTML, admittedly it has not the same interactivity and might avoid steps that are needed for QIIME2 visualizations. I actually find the quality and usefulness of visualizations within QIIME2 amazing and extremely helpful, for me personally the crucial point to use QIIME2.
Yes, I think there is. Here some points that speak for HTML files that "just work" in the browser, in my opinion:
The ampliseq pipeline produces a HTML report, very simple format (from a R Markdown file), summarizing or linking most relevant files and results. So its very convenient to directly link in the pipeline HTML report to a HTML from QIIME2. I understand that there is now qiime tools make-report, but that includes "only" QIIME2 output, not from other tools, therefore I consider that not feasible for now for pipelines with tools that are not used within QIIME2.
Before I had implemented the HTML report in ampliseq, the case for HTML files was weaker I think. But using qiime tools view or the q2-view website would have been even at that time inconvenient to check all the different QZV files, I guess I was not the only one that felt that way and maybe thats why make-report was implemented.
Very personal: I always found the HTML files more convenient, I never ever used the QZV files other than for exporting HTML files within (and outside of) ampliseq. The ancom-bc2 HTML file was the first one that didnt work for me and that was a heavy surprise.
The clear advantage of provenance preserved in the QZV files is not needed within a pipeline such as ampliseq in my opinion, because the provenance is defined within the pipeline code.
It would be great if bare HTML files would still also work in future. For ampliseq, I will for now stay with the ANCOM-BC2 test within QIIME2, but I will probably add another visualization that can be viewed as QC before needing to open that QZV for details (such as a quick static volcano plot with R or such). But essentially, if QIIME2's HTMLs are not working any more out-of-the-box, using tools outside of QIIME2 might become more attractive to me.
Thanks a lot for all the info here and in general your hard work on QIIME2 over the years.
I think this is maybe a philosophical difference of opinion in retrospective vs prospective provenance. We've got decentralized, retrospective provenance, which is very interesting for the intermediate results. But I see your point-of-view.
In any case, I may have good news.
Our jupyterlab extension (which I was just working with a moment ago) does a particularly unusual trick. It embeds the entire zip file as a base64 string in notebooks and the jupyterlab server by default also returns data in this format from the file-viewer.
We then convert that to a Blob object in the browser and use postMessage to q2view. This generally works because localhost is considered a secure-context, so we don't have to fight CORS (as long as q2view accepts * origins, which it is configured to do).
What I wasn't entirely sure of was whether file:// is a similar secure-context. (It turns out to be implementation dependent, but it mostly is for postMessage).
This means we could embed QZVs in an HTML file and you can compose those arbitrarily. It's only a little bit silly, but we can treat the html file as a very simple shell to open the zip archive and go from there.
I pointed Codex-5.5 at some existing code and it was able to create an example of this:
If you look at the source, you can see it's not too bad. None of this is "production ready" yet, but it's an avenue we could explore a bit further if this solves your problem. We could also coordinate a little bit on getting the resize events which coordinate iframe height between the q2view and the parent context.
It looks like this works with Chrome and Firefox, but not Safari. This is something that we could catch when the postMessage fails and request a more compatible browser. I don't think that's too much of a burden for users, but your-mileage-may-vary.
This is a neat hacky solution indeed! While that would work for most users and many applications, the general concept seems incompatible with European GDPR. I am not a lawyer, but I am pretty sure that any human-derived microbiome or most metadata that is uploaded to a website breaches rules set by GDPR. There might be cases where this should be fine, like the ANCOM-BC2 results, but I am unsure where to draw the line. So while I would like to add such a solution very much (I work mostly with non-human derived microbiome data) I think it would set up a trap for European users with human-derived microbiome data. So the optimal solution is working entirely offline, and I do need to keep that in mind unfortunately.
It's going to depend on the definition of "uploaded to a website". The way q2view works is entirely client-side (there is no meaningful backend server outside of returning static HTML and JS). It uses a client-only service worker to intercept requests to a client-generated random ID which acts as a router for the service worker to ask the zip file for data.
It's not conceptually different from running localhost. Now I think a fair concern is that the behavior of the website could change at any time, but that could be mediated by controlling the origin yourself. For instance you could host the embed page on an ampliseq controlled github pages.
We have no intention of changing the client-only behavior because we have no way to pay for the bandwidth that any other mechanism would require, and also it puts us in the unenviable position of handling sensitive data. Even our provenance search and bug-detection is entirely client-side.
