Skip to content

[JOSS review] improve documentation #48

Closed

Description

@cecileane

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 if MatrixLM is 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 est in the tutorial), it's ugly. I suggest implementing show methods for types that users will see: RawData and Mlm.

  • 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 using StableRNGs to fix the RNG and its seed.

Activity

  1. GregFa commented on Jul 28, 2026

    @GregFa
    Member

    Thank you, @cecileane, for these helpful suggestions.

    We made several updates to the documentation in response to this issue:

    • Added a new Real-World Applications page with links to complete metabolomics and chemical genetic screening analyses using MatrixLM.jl.
    • Added custom show methods so that RawData and Mlm objects are displayed in a more user-friendly way. The improved output is now shown in the documentation.
    • Updated the documentation examples to use StableRNGs for reproducibility across Julia versions.
    • Revised the examples to display selected or partial results, so users can better understand the model output without printing very large matrices.

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions