Polish mediation model metadata

[RiboRings]

Hi! This PR targets the messy metadata of the getMediation output and reorganises it into a data.frame. This issue was raised in microbiome/miaViz#165.

Example:

library(mia)
library(scater)

# Load dataset
data(hitchip1006, package = "miaTime")
tse <- hitchip1006

# Agglomerate features by family (merely to speed up execution)
tse <- agglomerateByRank(tse, rank = "Phylum")
# Convert BMI variable to numeric
tse$bmi_group <- as.numeric(tse$bmi_group)

# Apply clr transformation to counts assay
tse <- transformAssay(tse,
                      method = "clr",
                      pseudocount = 1)

# Analyse mediated effect of nationality on BMI via clr-transformed features
# 100 permutations were done to speed up execution, but ~1000 are recommended
tse <- addMediation(tse, name = "assay_mediation",
                    outcome = "bmi_group",
                    treatment = "nationality",
                    assay.type = "clr",
                    covariates = c("sex", "age"),
                    treat.value = "Scandinavia",
                    control.value = "CentralEurope",
                    boot = TRUE, sims = 10,
                    p.adj.method = "fdr")

med_df <- metadata(tse)[["assay_mediation"]]
metadata_df <- attr(med_df, "model metadata")

dim(metadata_df)
> [1]  8 56

names(metadata_df)
 [1] "d0"            "d1"            "d0.ci"         "d1.ci"         "d0.p"         
 [6] "d1.p"          "d0.sims"       "d1.sims"       "z0"            "z1"           
[11] "z0.ci"         "z1.ci"         "z0.p"          "z1.p"          "z0.sims"      
[16] "z1.sims"       "n0"            "n1"            "n0.ci"         "n1.ci"        
[21] "n0.p"          "n1.p"          "n0.sims"       "n1.sims"       "tau.coef"     
[26] "tau.ci"        "tau.p"         "tau.sims"      "d.avg"         "d.avg.p"      
[31] "d.avg.ci"      "d.avg.sims"    "z.avg"         "z.avg.p"       "z.avg.ci"     
[36] "z.avg.sims"    "n.avg"         "n.avg.p"       "n.avg.ci"      "n.avg.sims"   
[41] "boot"          "boot.ci.type"  "treat"         "mediator"      "covariates"   
[46] "INT"           "conf.level"    "model.y"       "model.m"       "control.value"
[51] "treat.value"   "nobs"          "sims"          "call"          "robustSE"     
[56] "cluster"

View(metadata_df)

[TuomasBorman]

It seems that the previous messy data was actually "mediate" class. I think we have to also output the mediate object as user might expect that the actual output from mediate() is also returned.

However, most of the data in this new metadata table is relevant for the user. So my suggestion is that

1. We keep the attributes() untouched. It should include the raw mediate() output.
2. We add confidence intervals (and other relevant info) to the main table

Does this sound feasible?

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 32 lines in your changes missing coverage. Please review.

Project coverage is 69.34%. Comparing base (e4b7e97) to head (9cdf6c7).
Report is 10 commits behind head on devel.

Files with missing lines	Patch %	Lines
R/mediate.R	0.00%	32 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##            devel     #678      +/-   ##
==========================================
- Coverage   70.11%   69.34%   -0.77%     
==========================================
  Files          47       47              
  Lines        5778     5918     +140     
==========================================
+ Hits         4051     4104      +53     
- Misses       1727     1814      +87     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[TuomasBorman]

To handle the dependencies, I changed mediation package as "soft-dependency". It is only required when the function is called.