Repository navigation
[JOSS review] improve documentation #48
Description
This is part of joss-reviews #10530. These suggestions focus on improving the documentation.
-
It would be great for the documentation to include a "real" example starting from csv files, to mimick what users really do. The current documentation shows how to simulate data, then works from the simulated data. This is great to show that the method works! But not so great to show users (especially those new to Julia) how to handle their own data. The current documentation sections are great. I'm only suggesting adding a paragraph about how to go from one or more data files to the analysis. Obviously, this toy example data set could be small to avoid storing big files (for Y, X and Z). That would not be representative of typical use cases in terms of size, but that's no problem. Showing how to store the results in output files would also valuable to empirical users.
-
Ideally, this "real" example would have feature names and predictors that come from a truly real example, such as particular names of a few triglyceride molecules, total number of carbons in the molecule, and case/control group of each subject (following Farage et al. 2025). A concrete example would help users understand the data and model.
-
Most example code in the documentation does not show the results (via ending with
;). I understand this choice, because most results are large matrices. But still, potential users who wonder ifMatrixLMis or isn't good for them would appreciate 'seeing' some more output, before deciding to install julia & the package. -
In particular, if one looks at the estimated object (named
estin the tutorial), it's ugly. I suggest implementingshowmethods for types that users will see:RawDataandMlm. -
Random.seed!(1)is not sufficient to reproduce the results, because the default RNG can change across julia versions. Using julia v1.12.6, I got different results when I ran the code from the section "Example: MLM for ordinal predictors". I got 1 extra p-value of 0 (when Z=C and X=4,pVals[3,3]). At the end of this section, the interpretation that follows the visualization of the p-values fails to list the last p-value of 0, for attribute D and category 3 (white cell in the plot). Was this interpretation omitted because the original RNG lead to a larger p-value, at the time when the text was written? Users might be confused as to why it is not listed.
To make sure that the interpretation text is correct, I suggest usingStableRNGsto fix the RNG and its seed.
Activity
GregFa commentedon Jul 28, 2026
Thank you, @cecileane, for these helpful suggestions.
We made several updates to the documentation in response to this issue:
MatrixLM.jl.RawDataandMlmobjects are displayed in a more user-friendly way. The improved output is now shown in the documentation.StableRNGsfor reproducibility across Julia versions.We did not add a small CSV-based tutorial directly to the package documentation, but the new applications page points users to complete workflows based on real datasets.
We believe these changes address the main documentation and reproducibility concerns raised here, so we are closing this issue. Thank you again for the detailed feedback.