search

JuliaStats / MixedModels.jl

A Julia package for fitting (statistical) mixed-effects models
http://juliastats.org/MixedModels.jl/stable
MIT License
405 stars 48 forks source link

document across public-facing dependencies #644

Closed kolia closed 2 years ago

kolia commented 2 years ago

MixedModels.jl would be much more user-friendly and accessible to noobs such as myself if the docs included or cross-linked to dependencies that export relevant functions, ideally with a search functionality that spans all such packages.

I keep searching through the docs looking for things that one would expect, but not finding them because they are defined in dependencies of MixedModels.jl that I didn't even know exist.

palday commented 2 years ago

What about the API documentation? At the top, we note that MixedModels implements the StatisticalModel and RegressionModel APIs. We don't define methods for every function in those APIs -- some don't make sense for mixed models and some have generic fallbacks that use functions whose methods that we do implement, so there's no need to implement a specialized method.

Do you have a specific example of something that you expected but couldn't find?

Or do you mean functionality implemented in reverse dependencies, i.e. packages that take MixedModels as a dependency?

kolia commented 2 years ago

This has happened several times, but I can only remember the most recent example:

I was looking to get the std of residuals for a LinearMixedModel, so I search for the word "residual" in the MixedModels.jl docs search bar, and get some maybe relevant functions

Screen Shot 2022-10-04 at 12 25 06 PM

and since I am a noob, I get lost reading through each of these listed docs because each might be relevant (maybe the model has this std info stored away somewhere already, maybe I have to run predict on the data and subtract the actual values to get the residual, etc, I just don't know), instead of doing what would have been more useful in retrospect, which is first looking through the docs for StatisticalModel and RegressionModel.

I think having docs for the subset ofStatisticalModels and RegressionModels that is relevant to MixedModel users (whether or not MixedModels specializes on them) into the MixedModels docs would help a lot. For now, I "just" need to remember to always search for things in each of these 3 package docs.