Naming schemes for the various alpha diversity indices

[antagomir]

Related to discussion in MiaBook PR#14.

We have several "alpha diversity" indices and methods. Alpha diversity is a vast general category that is often seen to cover richness, evenness, diversity, and related indices. It is also fundamentally different from another common concept, beta diversity, and confusion between alpha and beta diversity must be avoided.

A suggestion: let us have specific methods for each specific type of alpha diversity indices, and then one generic wrapper that calculates all of these.

About the generic wrapper:

1) The general wrapper could be named as: estimateAlphaDiversity. This has been implemented already. I propose that we keep the name like this because it makes a clear difference to beta diversity, and for most users, this could be the default method to use. The user can choose to focus on specific indices if they need to (specified through function arguments).

2) In addition, we could make sure that all indices implemented through this wrapper are interpreted in a conceptually similar way: increasing values indicate increasing community diversity. This means that we can include richness, evenness, diversity, and rarity but we would need to exclude dominance (it has an opposite interpretation: increasing dominance means decreasing diversity). This would help to avoid unintended mistakes/misinterpretations if the users switch between difference indices available through this generic wrapper.

Comments on the naming of more specific methods for alpha diversity and closely related indices:

• estimateRichness: should work; implemented already
• estimateEvenness: should work; implemented already
• estimateDiversity: acceptable; implemented already; potentially confused with beta diversity but the risk is not high and it is also helpful to follow the same naming scheme than with the other alpha diversity indices
• estimateRarity: to be implemented in issue #59 and could be also incorporated to the wrapper estimateAlphaDiversity
• estimateDominance: has opposite sign than the other indices; the naming can follow the other indices but should be dropped out from the wrapper estimateAlphaDiversity in order to avoid confusion.

[microsud]

In addition, we could make sure that all indices implemented through this wrapper are interpreted in a conceptually similar way: increasing values indicate increasing community diversity. This means that we can include richness, evenness, diversity, and rarity but we would need to exclude dominance (it has an opposite interpretation: increasing dominance means decreasing diversity). This would help to avoid unintended mistakes/misinterpretations if the users switch between difference indices available through this generic wrapper.

Makes sense to me.

estimateDominance: has opposite sign than the other indices; the naming can follow the other indices but should be dropped out from the wrapper estimateAlphaDiversity in order to avoid confusion.

This is good. We expect researchers with all levels and kinds of expertise digging into microbiome research, avoiding potential confusions is important.

[FelixErnst]

PRs welcome. Lets get this done.

However, I would like to stress that a catchy and easy to understand function name goes a long way. Secondly spell the reasons for grouping the indices the way you outlined it here in the description of the man pages. Thirdly, add a comprehensive details section on each index so that all the information required is at one place.

[antagomir]

I started to look into this, and now converging to the conclusion that it would be better to keep all these distinct concepts separate, and remove the estimateAlphaDiversity wrapper entirely. It is better to keep the concepts clear. Users can easily combine them if needed, it is just five different (albeit related) types of indices. This is also helping to avoid confusion with relatively similar names with certain indices in different context (e.g. Simpson's index has three variations, used in diversity, evenness and dominance).

Let us then keep the name estimateDiversity as is (for alpha diversity). It could be potentially confused with beta diversity but this is not a big risk or problem in the end i.m.o.

I can make the PR unless there are objections.

[antagomir]

Will do "soon".

[FelixErnst]

No problem. I assigned the issues based on similarity. Since you and Tuomas are already working on this and also in MiaBook, there is no point in diverting it to someone else

[FelixErnst]

Can this be closed?

I think this is solved with 4866ece