redefine FeatureData[NOG] type that is generated as output from eggnog-annotate, and add support for downstream analysis of this data

[gregcaporaso]

This isn't FeatureData in the way that we typically define it, in that the feature ids from the corresponding table are not the ids in this artifact. This seems more like SampleData to me. I'm currently investigating this, but I wanted to get an issue up now to make folks aware that this semantic type is likely going to change. We'll ultimately want to process this artifact to generate FeatureData.

[gregcaporaso]

After doing a little research on this, I think we should make the following changes to the eggnog-annotate and eggnog-diamond-search actions.

eggnog-diamond-search

• The output table seems to make more sense as a FeatureTable[PresenceAbsence], rather than a FeatureTable[Frequency]. While it's possible (and not uncommon) for a feature id (seed ortholog id) to be reported multiple times in a single sample, we're not normalizing by input contig length, or referring back to the original reads to see how many times a contig was observed when creating this table. It may be possible to generate a FeatureTable[Frequency] ultimately, but the safer approach seems to be to be to generate a FeatureTable[PresenceAbsence].

eggnog-annotate

• As noted above, the current output should be described as SampleData rather than FeatureData. I propose that we drop that output in favor of FeatureData[Eggnog]* (that subtype aligns with the input to this action, ReferenceDB[Eggnog]), which will be traditional feature data. In this new artifact class, we'll have seed ortholog ids map to their associated annotations, and there will be no references to samples. The sample specific information is all contained in the FeatureTable and SampleData[BLAST6] that are returned by eggnog-diamond-search, so doesn't need to be reproduced here.

* Notes on FeatureData[Eggnog]:

• There are 16 annotations in eggNOG 5, and they will vary across versions of eggNOG (eggNOG 6 adds a few). So, I propose that the column names won't be fixed but rather can be discovered by viewing as metadata (e.g., qiime tools inspect-metadata).
• We'll need some actions to turn this into something that can be used with existing tools in QIIME 2.
  • I would see an action taking FeatureData[Eggnog] as input, and allowing the user to turn this into FeatureData[Taxonomy]. Here, the user would provide a column name and a delimiter, and the values in that column would be split on the delimiter and joined using ;. All other columns would be dropped, and the output would then be usable anywhere FeatureData[Taxonomy] is used.
  • Another action might take the FeatureData[Eggnog] and eggnog-diamond-search's FeatureTable as input and map to a new feature space based on annotations in FeatureData[Eggnog]. For example, this could allow the user to map from Eggnog hits to KEGG pathways, one or more of which can be associated with each input feature id. The user would again provide a delimiter for use in splitting the annotation field. The output from this action would be FeatureTable[PresenceAbsence] for now (and maybe type mapped from the input table in the future).

An example of the current FeatureData[NOG], for a single sample viewed as QIIME 2 metadata, see the attached .qzv (renamed with .zip so GitHub allows me to upload it).

contig-hits.zip

@misialq, @nbokulich, @colinvwood, @ebolyen - thoughts on this?

[nbokulich]

The first point shows some close parallels with what we already discussed wrt unnormalized taxonomic frequencies, e.g., output by kraken2.

I disagree that a FeatureTable[PresenceAbsence] should be the output. I recognize that the output is unnormalized, but FeatureTable[PresenceAbsence] eliminates the possibility of then normalizing to generate normalized frequencies. So I would propose outputting FeatureTable[Frequency] (maybe with some type of unnormalized property) and then allowing this output to be passed to the RPKM method that we discussed to normalize by length.

[misialq]

Thanks for looking into that @gregcaporaso! Here's what I think:

• on eggnong-diamond-search: I agree with @nbokulich; these are frequencies which should "just" be normalized - we could flag that using a property, similarly to how we discussed in the case of Kraken2, and then just have a separate action addressing/correcting that
• on eggnog-annotate: I agree that this looks more like SampleData. However, what I'm a bit confused about is how you are going to replace FeatureData[NOG] with FeatureData[Eggnog] - it would still remain a FeatureData type. What would the final outputs of this action be? And what kinds of files would they represent? As long as they are multiple annotation files (one per sample) it should remain a SampleData type in my opinion.

When looking at those two actions I only now noticed we are using contigs as input - why is this actually? Shouldn't we rather process either reads directly or dereplicated MAGs? (I know that neither of those would solve the issue described above, but just trying to think about the most probable routes the the users would want to take here...

[misialq]

Hey @gregcaporaso, some more thoughts after discussing this today with @nbokulich:

• we believe that the output type from the eggnog-annotate should change to the SampleData kind, however we should keep it as SampleData[NOG] which would be a collection of the original annotation files generated by the eggnog-mapper - just in case users want to use those directly (and following the same logic we applied to Kraken2 outputs)
• we propose sticking to the NOG subtype, though, as it represents a specific object (Non-supervised Orthologous Groups, alongside the OG and KEGG, as per our original plan)
• we'd need a separate action which would accept SampleData[NOG] and filter and compress it based on criteria like e.g. specific Evalue/bit score to produce: 1) a new SampleData[NOG] (filtered) and 2) "dereplicated" FeatureData[NOG] - the reason for this being that there may be multiple hits mapping to the same OG in different MAGs so we leave it up to the user to decide how to filter those (not everyone may necessarily be interested in the top hits - the lower quality hits may actually carry interesting information)
• the same action could then produce one to a couple of FeatureData[Taxonomy] artifacts, based on the few columns in the annotations for which it makes sense (we thought it would make sense to produce them here rather then have a separate action for generating those based on columns specified by the user as it really only makes sense for just a few columns)
• on the topic of fixing the column names in the annotations: I do think they should be fixed - we are not going to support any previous versions of the EggNOG databases and you mentioned that version 6 only adds a few; we propose instead to just decide which columns should be mandatory and enforce those. I cannot find an example for the version 6 so I cannot really propose any specific ones here, but I'm imagining that probably most of the v5 make sense as they would be included in v6 as well - is that the case?

How does that sound?

[gregcaporaso]

we believe that the output type from the eggnog-annotate ...

I like it. Good call about keeping the original output accessible for users who may want that.

we propose sticking to the NOG subtype...

Works for me.

we'd need a separate action which would accept SampleData[NOG] and filter...

That makes sense, but I think the filtering can happen upstream on the SampleData[BLAST6] using a new action (I'm going to call that action filter-sample-data-blast6 here). I believe that will have the information that users need for the filtering. We also need the ability to generate the dereplicated FeatureData[NOG] for unfiltered data to align with the eggnog-diamond-search FeatureTable. How about the following?

graph TD;
    actEDS([eggnog-diamond-search])
    actEA([eggnog-annotate])
    artFSDB([filter-sample-data-blast6])
    artFT(((FeatureTable)))
    artSDB((("SampleData#91;BLAST6#93;")))
    artSDN((("SampleData#91;NOG#93;")))
    artFDN((("FeatureData#91;NOG#93;")))
    actEDS-->artFT;
    actEDS-->artSDB;
    artSDB-->actEA;
    artSDB-->artFSDB;
    artFSDB-->artSDB;
    actEA-->artSDN;
    actEA-->artFDN;

Loading

the same action could then produce one to a couple of FeatureData[Taxonomy] artifacts

In my flowchart above, eggnog-annotate could do that, or we could keep it as a separate action. I think the right approach here depends on how many fields we're going to want, either in FeatureData[Taxonomy] artifacts or other FeatureData subtypes. If there are many (say more than 3) possible outputs, we might want to let users choose which ones they want (in which case they should be able to generate additional ones without having to re-run eggnog-annotate). If it's 1-3, just creating those is probably easier.

Here's the eggNOG 6 paper, and the list of annotation sources including * for the ones that are new in eggNOG 6. Any of these that are strictly hierarchical would be stored in FeatureData[Taxonomy] - e.g., KEGG Enzyme and Pathway annotations, CARD (I think), and others.

on the topic of fixing the column names in the annotations: I do think they should be fixed - we are not going to support any previous versions of the EggNOG databases...

If we go this route, I think we should only support v6 (v5 is a previous version now, and I think it's only a database update, not an emapper update). I still need to test v6 though. Let's circle back to this bit of the discussion after I've done a little more research.

[misialq]

the filtering can happen upstream on the SampleData[BLAST6] using a new action

I guess all the required information should be there already so that sounds good to me!

I think the right approach here depends on how many fields we're going to want

Agreed.

I think we should only support v6

I fully support that, provided that v6 is already released officially (or would be at the time of our release). I was under the impression that it's not yet official but please correct me if I'm mistaken.

I would like to highlight again that we should revisit which inputs we're actually going to support as this influences semantic types of the linked outputs - please see the other related topic: #50.

[gregcaporaso]

I fully support that, provided that v6 is already released officially (or would be at the time of our release). I was under the impression that it's not yet official but please correct me if I'm mistaken.

My understanding is that it is - they have a paper on it, formally published (not just pre-print). But that doesn't seem very apparent from their website.

I would like to highlight again...

Thanks - will follow up there.