search

microbiome / mia

Microbiome analysis
https://microbiome.github.io/mia/
Artistic License 2.0
45 stars 25 forks source link

z transformation naming to change #583

Closed antagomir closed 2 weeks ago

antagomir commented 2 weeks ago

The transformAssay function has the option "z" among transformation methods and this scales the signal to zero mean, unit variance. The name "z" derived from some older code but "z transformation" has a different meaning in signal processing. That meaning is more common. The naming can be therefore confusing and should be changed.

Suggestions:

1) rename the "z" method into "standardize", which performs the zero mean, unit variance via vegan::decostand. This would be useful because the mia::transformAssay is already supporting other vegan::decostand transformations.

2) We should not duplicate vegan::decostand documentation; on the same go one should check the roxygen documentation of mia::transformAssay under ""The available transformation methods include: ...". Remove explanations for those methods that have the same name in vegan and are already explained there. Add text mentioning that the methods in vegan::decostand are supported and user should see that documentation for details.

3) Another option is to use base::scale and modify the implementation so that users could pass arguments to the scale function through the transformAssay call. This would allow a wider range of options, such as ignoring centering and only doing the unit variance scaling; then we could do things like transformAssay(tse, method="scale", center=FALSE). Could be useful in principle but on the other hand there is no immediate need. It would be also possible to support this one alongside with vegan::decostand because the mia package has support for all vegan::decostand transformations anyway.

TuomasBorman commented 2 weeks ago

1.-2 I think "standardize" is already supported, so only the documentation should be modified (should be checked whether that is the case). The code still could support "z", but we should just avoid using it in documentation.

  1. One option is to ask update to vegan package if there is need for these options. It would be beneficial if we could rely on vegan in most of these transformations. Although, adding support for "scale" method is not big deal since it requires only couple lines of code and adjustment to this internal function.
antagomir commented 2 weeks ago

True, "standardize" should be supported already as a vegan option.

I would anyway deprecate the "z" option because we are not providing it in the more commonly used meaning and this is a potential source of confusion.

I wouldn't bother the vegan developers with this until there is a clear need. This is not critical so perhaps we leave support for "scale" for now, and just updated the documentation + deprecate z.

TuomasBorman commented 2 weeks ago

I agree. Deprecation requires only warning message above this

https://github.com/microbiome/mia/blob/315beb05e1fdc8d51c76f01ecdd99220a86d525e/R/transformCounts.R#L313

antagomir commented 2 weeks ago

Great. I suggest that @Daenarys8 will open a PR with the suggested changes.