Clarify `multilevel` argument documentation for `correlation()` and `cor_test()`

[indenkun]

Description:

I've identified a potential issue with the documentation for the multilevel argument in both correlation() and cor_test(). The current description seems to be inherited from another function (likely from the datawizard package via @inheritParams) and does not accurately reflect the behavior within the correlation package.

The current documentation states:

If TRUE, the factors are included as random factors. Else, if FALSE (default), they are included as fixed effects in the simple regression model.

However, based on my testing, when multilevel = FALSE, the function does not include factor variables as fixed effects. Instead, it calculates a simple, overall Pearson correlation between numeric variables, effectively ignoring the factor variable entirely.

This discrepancy likely stems from a shared documentation block intended for a different context. In the correlation package, multilevel = FALSE serves as a baseline for a simple, overall correlation, whereas multilevel = TRUE introduces a multilevel model with random effects. The current wording, suggesting a fixed-effects model for multilevel = FALSE, is misleading and could cause user confusion regarding the function's actual behavior.

Proposed change:

I propose that the documentation for the multilevel argument in both correlation() and cor_test() be updated to explicitly describe their specific behavior. A more accurate description would be:

If TRUE, the factors are included as random effects in a mixed-effects model to calculate within-group correlations. If FALSE (default), factors are ignored, and a simple correlation is calculated between the numeric variables.

This revised text clearly distinguishes between the two behaviors within the context of the correlation package, providing users with an accurate understanding of the function's output. Thank you for considering this clarification.

[mattansb]

I think an even better description would be:

If TRUE, the factors are included as random effects in a mixed-effects model to calculate within-group correlations. If FALSE they are treated according to include_factors.

[indenkun]

Thank you for your feedback. Certainly the description of the multilevel argument would be better that way.

It prompted me to look deeper into the interactions between the multilevel and include_factors arguments. I've found a potential discrepancy between the documentation and the function's actual behavior.

The current include_factors documentation states:

If TRUE, the factors are kept and eventually converted to numeric or used as random effects (depending of multilevel). If FALSE, factors are removed upfront.

While this is a great step towards clarity, I've observed that when multilevel = TRUE, the include_factors argument is effectively ignored by the internal .clean_data function.

For example, both correlation(iris, multilevel = TRUE, include_factors = FALSE) and correlation(iris, multilevel = TRUE, include_factors = TRUE) yield the same result, as the if (!multilevel) condition in .clean_data prevents the include_factors logic from ever being evaluated. This behavior contradicts the documentation for include_factors, which states its action depends on multilevel.

To avoid further confusion, I believe the documentation for both arguments should be made more precise to reflect this interaction.

To resolve this discrepancy, I think it would be better to change not only the description of multilevel but also the description of include_factors.

Proposed Documentation Changes:

Based on the feedback and code analysis, I suggest the following revised descriptions:

1. For multilevel argument:

   If TRUE, factors are included as random effects in a mixed-effects model to calculate within-group correlations. If FALSE (default), they are treated according to the include_factors argument.

This is as you commented earlier.

2. For include_factors argument:

   If TRUE, factors are kept and converted to numeric. If FALSE, factors are removed. This argument is only used when multilevel = FALSE.

These changes will provide a clear and accurate understanding of how these two arguments interact, preventing user confusion and aligning the documentation with the function's actual implementation.

Thank you for your consideration.