q2-FMT install on 2025.4

saatkinson · June 11, 2025, 8:07pm

Hello,

I'm wondering if it's possible to install the q2-FMT plugin on the latest 2025.4 install. I found these instructions for how to add it to the 2024 release. I'm able to run the pip install commands successfully, but when I run qiime info this is what's shown for FMT:

fmt: 0+unknown

Then when I tried to run a FMT command to test:

qiime fmt cc \
--i-diversity-measure ../core-metrics-results/jaccard_distance_matrix.qza \
--m-metadata-file ../../mapping_file.txt \
--p-distance-to donor --p-compare baseline \
--p-time-column Week --p-reference-column DonorSampleID \
--p-subject-column tag --p-filter-missing-references \
--p-against-group 0 \
--p-p-val-approx asymptotic \
--o-stats raincloud_jaccard_stats.qza \
--o-raincloud-plot raincloud_jaccard_plot.qzv

I got this error:

Plugin error from fmt:

  0.0 was not found as a group within the distribution.

Debug info has been saved to /tmp/qiime2-q2cli-err-cpu_7mkf.log

I'm assuming the issue is the difference in versions since q2-fmt-2024.11 can install into a qiime2-2024.10 environment without issue. Is there a way to get the current release of the FMT plugin installed in 2025 version of Q2 or is a version for 2025 coming soon?

The q2-fmt github page directs me to the q2-fmt documentation page for installation, but I can't find any install instructions.

Thank you!
Samantha

cherman2 · June 11, 2025, 9:26pm

Hi @saatkinson,
Thanks for using q2-fmt!

I think I am alittle confused. Do you only get this error when you pip install into a qiime2-2025.4 release? Is there a version of q2-fmt where you can run this command without getting this error?This error is saying that 0 is not a valid timepoint in your metadata, do you have a 0 timepoint?

If you are trying to install into a qiime2-2025.4 release I would use this command:

pip install https://github.com/qiime2/q2-fmt/archive/refs/tags/2024.11.1.zip

or if you are okay with qiime2-2024.10, you can install q2-fmt by following the library docs: QIIME 2 Library. This installs q2-fmt-2024.11 into qiime2-2024.10.

A new release of q2-fmt is coming soon but I can't make any promises as to when though as I am trying to finish up my phd.

Thank you!

saatkinson · June 18, 2025, 3:20pm

Hi @cherman2,

Thank you for responding, I know finishing up your PhD is super stressful (congratulations!!).

I do have a timepoint 0 in my metadata. Here's a snippet of the first group of samples:

Sample ID	Sample	Sample_Name	tag	sample_type	Group	SourceNum	Timept	Week	DonorSampleID
1AHW6FT	1AHW6FT	AHW006	Original	source_feces	AHW-6.1	6	0w	0
2AHW61B	2AHW61B	11	Cage	cage_baseline	AHW-6.1	6	0w	0	1AHW6FT
3AHW61	3AHW61	6	F_651	feces	AHW-6.1	6	1w	1	1AHW6FT
4AHW61	4AHW61	7	F_652	feces	AHW-6.1	6	1w	1	1AHW6FT
5AHW61	5AHW61	8	F_653	feces	AHW-6.1	6	1w	1	1AHW6FT
6AHW61	6AHW61	9	F_654	feces	AHW-6.1	6	1w	1	1AHW6FT
7AHW61	7AHW61	10	F_655	feces	AHW-6.1	6	1w	1	1AHW6FT
8AHW61	8AHW61	20	F_651	feces	AHW-6.1	6	2w	2	1AHW6FT
9AHW61	9AHW61	21	F_652	feces	AHW-6.1	6	2w	2	1AHW6FT
10AHW61	10AHW61	22	F_653	feces	AHW-6.1	6	2w	2	1AHW6FT
11AHW61	11AHW61	23	F_654	feces	AHW-6.1	6	2w	2	1AHW6FT
12AHW61	12AHW61	24	F_655	feces	AHW-6.1	6	2w	2	1AHW6FT
13AHW61	13AHW61	50	F_651	feces	AHW-6.1	6	3w	3	1AHW6FT
14AHW61	14AHW61	51	F_652	feces	AHW-6.1	6	3w	3	1AHW6FT
15AHW61	15AHW61	52	F_653	feces	AHW-6.1	6	3w	3	1AHW6FT
16AHW61	16AHW61	53	F_654	feces	AHW-6.1	6	3w	3	1AHW6FT
17AHW61	17AHW61	54	F_655	feces	AHW-6.1	6	3w	3	1AHW6FT

I was using "Week" as my --p-time-column, which has "0" as a timepoint.

I would prefer to use Q2 v. 2025.4 since I started with that version and all of my tables/analyses aren't backward compatible; I'd like to avoid rerunning everything if possible.

I did try running your pip install command in my 2025.4 environment and got this error:
ModuleNotFoundError: No module named 'q2_stats.types'
And now qiime info doesn't work, it just keeps repeating the module error.

I guess my new questions are:

Do you think my original install method worked and the issue was something to do with my command setup, about which I should make a new forum post for help?
If you think I should get the pip install you mentioned to work, do you have a pip command for (re)installing the q2_stats module?

Thanks!
Samantha

cherman2 · June 19, 2025, 6:18pm

Hi @saatkinson

I think that this issue may be becausee you only have one '0' timepoint that has a donor. Would you mind private messaging me your diversity metric and your command so I can test this out and give you more info.

This is a code change I completely forgot about and makes installing q2-fmt the way I described not compatiable with 2025.4 . I am so sorry, I forgot about this. Your install instructions avoid this issues but to make it easier to use with 2025.4, I will issue a new release of q2-fmt next week and follow up with you once its done.
Thank you so much.

saatkinson · June 19, 2025, 6:39pm

Hi @cherman2 ,

Thanks so much for being willing to look at this! I send the private message with the files/command.

Thank you sooo much! I really appreciate it and will keep an eye out for the new release

Best,
Samantha

cherman2 · July 1, 2025, 11:10pm

Hi @saatkinson,
Sorry for the slow reply!

q2-fmt was just released so feel free to install the new version, this will fix the q2-stats error you were running into (your work around was fine, but this is more official if you want).

As for your data, I believe that its because there is not a consistent 0 timepoint for all your subjects. Is that correct?

Can you tell me more about your study so that I can best suggest how to use q2-fmt to answer your question?
Thank you so much and thank you for your patience!

saatkinson · July 2, 2025, 2:27pm

Hi @cherman2 ,

Thank you for the q2-fmt release! I'll try the official release for sure.

Unfortunately, yes. The timepoint 0 we have is a cage baseline (collected stool from the cage of mice) while the remaining timepoints are per mouse. So each mouse's baseline is that same cage collection.

We are using gavage to introduce our source feces into germ free mice. We have sequencing from the source feces and as I mentioned above an aggregate baseline. Then feces were collected from the mice (individually) on a weekly basis and I was hoping to use q2-fmt to analyze bacterial engraftment from the source feces.

Thank you for all your help!!
~Samantha

saatkinson · July 3, 2025, 7:41pm

Hi @cherman2 ,

I'm trying to install the new release with this command:

conda env update --file https://raw.githubusercontent.com/qiime2/q2-fmt/refs/heads/dev/environment-files/q2-fmt-qiime2-amplicon-2025.4.yml

And I'm getting a HTTP 404 error.
Error:

CondaHTTPError: HTTP 404 NOT FOUND for url <https://raw.githubusercontent.com/qiime2/q2-fmt/refs/heads/dev/environment-files/q2-fmt-qiime2-amplicon-2025.4.yml>
Elapsed: 00:00.301552

An HTTP error occurred when trying to retrieve this URL.
HTTP errors are often intermittent, and a simple retry will get you on your way.

Is it possible the yml file didn't make it into the github folder? I know it says a simple retry will likely fix the problem, but I've been retrying intermittently since yesterday and it's still a problem.

Thanks,
Samantha

lizgehret · July 3, 2025, 7:54pm

Hey @saatkinson,

Just jumping in quickly for @cherman2 with regards to your install command - it looks like there's a small piece missing in the listed environment file name. Here's the full command you'll want to use to update your existing environment (after activating your existing fmt environment):

conda env update --file https://raw.githubusercontent.com/qiime2/q2-fmt/refs/heads/dev/environment-files/q2-fmt-qiime2-amplicon-2025.4-release-2025.7.yml

This should do the trick, but please let us know if you run into any other issues!

saatkinson · July 3, 2025, 8:00pm

Hi @lizgehret ,

Thanks for missing piece, that did the trick!

Also, just a heads-up that the q2-fmt library page needs to be updated as that's where I got the command from.

Best,
Samantha

lizgehret · July 3, 2025, 8:48pm

Hey @saatkinson,

Ahh, I suspect that may be a cached page; here's what I see on my end:

We did update this a couple of days ago, so you're probably just seeing the outdated page. If you clear your browser cache/cookies, that should do the trick!

Cheers

saatkinson · July 28, 2025, 5:24pm

Hi @cherman2,

I'm just checking in before the topic closes. Any ideas about our cage baseline issue?

Thanks,
Samantha

cherman2 · July 28, 2025, 6:09pm

Hi @saatkinson,
Thank you for circling back to this.

I have not run into a cage baseline before and would have to thing alittle more about how to implement this in q2-fmt.

Here are two not ideal work around:

you could change that baseline sample to have the same subject id as one of the mice from that cage. This will unfortunately drop all other samples (that don't have a baseline) so this will give you less information but you could use the baseline
you could use tp 1 as your baseline, I don't know who far into treatment the mouse is in your study, so I don't know if this will work very well as a baseline but that way you could keep all your mice.

Let me think more about how to implement cage baselines, for now I have made a issue on our github: cage baseline sample · Issue #131 · qiime2/q2-fmt · GitHub you can check here for updates!

system · August 29, 2025, 12:09am

This topic was automatically closed 31 days after the last reply. New replies are no longer allowed.