Built site for ModelArray@0.1.5: 4b64d71

Author: araikes

llms.txt

@@ -128,7 +128,7 @@ If you use ModelArray, please cite:
 - [`ModelArray.gam()`](https://pennlinc.github.io/ModelArray/reference/ModelArray.gam.md)
   : Run GAM for element-wise data
 - [`ModelArray.lm()`](https://pennlinc.github.io/ModelArray/reference/ModelArray.lm.md)
-  : Fit linear model for element-wise data
+  : Fit element-wise linear models
 - [`ModelArray.wrap()`](https://pennlinc.github.io/ModelArray/reference/ModelArray.wrap.md)
   : Run a user-supplied function for element-wise data
 - [`analyseOneElement.gam()`](https://pennlinc.github.io/ModelArray/reference/analyseOneElement.gam.md)

pkgdown.yml

@@ -12,7 +12,7 @@ articles:
   installations: installations.html
   modelling: modelling.html
   walkthrough: walkthrough.html
-last_built: 2026-03-31T00:13Z
+last_built: 2026-03-31T00:34Z
 urls:
   reference: https://pennlinc.github.io/ModelArray/reference
   article: https://pennlinc.github.io/ModelArray/articles

reference/ModelArray.lm.html

@@ -1,8 +1,8 @@
-# Fit linear model for element-wise data
+# Fit element-wise linear models
 
-\`ModelArray.lm\` fits linear model (\`stats::lm()\`) for each of
-elements requested, and returns a tibble dataframe of requested model
-statistics.
+`ModelArray.lm` fits a linear model at each requested element in a
+[ModelArray](https://pennlinc.github.io/ModelArray/reference/ModelArray-class.md)
+and returns a tibble of requested model statistics.
 
 ## Usage
 
@@ -38,151 +38,206 @@ ModelArray.lm(
 
 - formula:
 
-  Formula (passed to \`stats::lm()\`)
+  Formula (passed to [`lm`](https://rdrr.io/r/stats/lm.html)).
 
 - data:
 
-  ModelArray class
+  A
+  [ModelArray](https://pennlinc.github.io/ModelArray/reference/ModelArray-class.md)
+  object.
 
 - phenotypes:
 
   A data.frame of the cohort with columns of independent variables and
-  covariates to be added to the model. It should contains a column
-  called "source_file", and this column should match to that in `data`.
+  covariates to be added to the model. It must contain a column called
+  `"source_file"` whose entries match those in
+  `sources(data)[[scalar]]`.
 
 - scalar:
 
-  A character. The name of the element-wise scalar to be analysed
+  Character. The name of the element-wise scalar to analyse. Must be one
+  of `names(scalars(data))`.
 
 - element.subset:
 
-  A list of positive integers (min = 1, max = number of elements). The
-  subset of elements you want to run. Default is \`NULL\`, i.e.
-  requesting all elements in \`data\`.
+  Integer vector of element indices (1-based) to run. Default is `NULL`,
+  i.e. all elements in `data`.
 
 - full.outputs:
 
-  TRUE or FALSE, Whether to return full set of outputs. If FALSE, it
-  will only return those requested in arguments `var.*` and
-  `correct.p.value.*`; if TRUE, arguments `var.*` will be ignored, and
-  will return all possible statistics for `var.*` and any options
-  requested in arguments `correct.p.value.*`.
+  Logical. If `TRUE`, return the full set of statistics (ignoring
+  `var.*` arguments). If `FALSE` (default), only return those requested
+  in `var.*` and `correct.p.value.*`.
 
 - var.terms:
 
-  A list of characters. The list of variables to save for terms (got
-  from \`broom::tidy()\`). See "Details" section for more.
+  Character vector. Statistics to save per term, from
+  [`broom::tidy()`](https://generics.r-lib.org/reference/tidy.html). See
+  Details.
 
 - var.model:
 
-  A list of characters. The list of variables to save for the model (got
-  from \`broom::glance()\`). See "Details" section for more.
+  Character vector. Statistics to save for the overall model, from
+  [`broom::glance()`](https://generics.r-lib.org/reference/glance.html).
+  See Details.
 
 - correct.p.value.terms:
 
-  A list of characters. To perform and add a column for p.value
-  correction for each term. Default: "fdr". See "Details" section for
-  more.
+  Character vector. P-value correction method(s) for each term. Default:
+  `"fdr"`. See Details.
 
 - correct.p.value.model:
 
-  A list of characters. To perform and add a column for p.value
-  correction for the model. Default: "fdr". See "Details" section for
-  more.
+  Character vector. P-value correction method(s) for the model-level
+  p-value. Default: `"fdr"`. See Details.
 
 - num.subj.lthr.abs:
 
-  An integer, lower threshold of absolute number of subjects. For an
-  element, if number of subjects who have finite values (defined by
-  \`is.finite()\`, i.e. not NaN or NA or Inf) in h5 file \>
-  `num.subj.lthr.abs`, then this element will be run normally;
-  otherwise, this element will be skipped and statistical outputs will
-  be set as NaN. Default is 10.
+  Integer. Lower threshold for the absolute number of subjects with
+  finite scalar values (not `NaN`, `NA`, or `Inf`) required per element.
+  Elements below this threshold are skipped (outputs set to `NaN`).
+  Default is 10.
 
 - num.subj.lthr.rel:
 
-  A value between 0-1, lower threshold of relative number of subjects.
-  Similar to `num.subj.lthr.abs`, if proportion of subjects who have
-  valid value \> `num.subj.lthr.rel`, then this element will be run
-  normally; otherwise, this element will be skipped and statistical
-  outputs will be set as NaN. Default is 0.2.
+  Numeric between 0 and 1. Lower threshold for the proportion of
+  subjects with finite values. Used together with `num.subj.lthr.abs`
+  (the effective threshold is the maximum of the two). Default is 0.2.
 
 - verbose:
 
-  TRUE or FALSE, to print verbose message or not
+  Logical. Print progress messages. Default `TRUE`.
 
 - pbar:
 
-  TRUE or FALSE, to print progress bar or not
+  Logical. Show progress bar. Default `TRUE`.
 
 - n_cores:
 
-  Positive integer, The number of CPU cores to run with
+  Positive integer. Number of CPU cores for parallel processing via
+  [`mclapply`](https://rdrr.io/r/parallel/mclapply.html). Default is 1
+  (serial).
 
 - on_error:
 
-  Character: one of "stop", "skip", or "debug". When an error occurs
-  while fitting an element, choose whether to stop, skip returning
-  all-NaN values for that element, or drop into \`browser()\` (if
-  interactive) then skip. Default: "stop".
+  Character: one of `"stop"`, `"skip"`, or `"debug"`. When an error
+  occurs fitting one element: `"stop"` halts execution; `"skip"` returns
+  all-`NaN` for that element; `"debug"` drops into
+  [`browser`](https://rdrr.io/r/base/browser.html) (if interactive) then
+  skips. Default: `"stop"`.
 
 - write_results_name:
 
-  Optional analysis name for incremental writes to
-  \`results/\<write_results_name\>/results_matrix\`.
+  Optional character. If provided, results are incrementally written to
+  `results/<write_results_name>/results_matrix` in the HDF5 file
+  specified by `write_results_file`.
 
 - write_results_file:
 
-  Optional HDF5 file path used when \`write_results_name\` is provided.
+  Optional character. HDF5 file path for incremental result writes.
+  Required when `write_results_name` is provided.
 
 - write_results_flush_every:
 
-  Positive integer number of elements per write block.
+  Positive integer. Number of elements per write block. Default 1000.
 
 - write_results_storage_mode:
 
-  Storage mode for results writes (e.g., \`"double"\`).
+  Character. Storage mode for HDF5 writes (e.g. `"double"`). Default
+  `"double"`.
 
 - write_results_compression_level:
 
-  Gzip compression level (0-9) for results writes.
+  Integer 0–9. Gzip compression level for HDF5 writes. Default 4.
 
 - return_output:
 
-  If TRUE (default), return the combined data.frame. If FALSE, returns
-  \`invisible(NULL)\`; useful for streaming large runs to HDF5.
+  Logical. If `TRUE` (default), return the combined data.frame. If
+  `FALSE`, return `invisible(NULL)`; useful when writing large outputs
+  directly to HDF5.
 
 - ...:
 
-  Additional arguments for \`stats::lm()\`
+  Additional arguments passed to
+  [`lm`](https://rdrr.io/r/stats/lm.html).
 
 ## Value
 
-Tibble with the summarized model statistics for all elements requested
-when \`return_output = TRUE\`; otherwise \`invisible(NULL)\`.
+A tibble with one row per element. The first column is `element_id`
+(0-based). Remaining columns contain the requested statistics, named as
+`<term>.<statistic>` for per-term statistics and `model.<statistic>` for
+model-level statistics. If p-value corrections were requested,
+additional columns are appended with the correction method as suffix
+(e.g. `<term>.p.value.fdr`).
 
 ## Details
 
 You may request returning specific statistical variables by setting
-`var.*`, or you can get all by setting `full.outputs=TRUE`. Note that
+`var.*`, or you can get all by setting `full.outputs = TRUE`. Note that
 statistics covered by `full.outputs` or `var.*` are the ones from
-broom::tidy() and broom::glance() only, and do not include corrected
-p-values. However FDR-corrected p-values ("fdr") are generated by
-default. List of acceptable statistic names for each of `var.*`:
+[`broom::tidy()`](https://generics.r-lib.org/reference/tidy.html),
+[`broom::glance()`](https://generics.r-lib.org/reference/glance.html)
+only, and do not include corrected p-values. However FDR-corrected
+p-values (`"fdr"`) are generated by default.
 
-- `var.terms`: c("estimate","std.error","statistic","p.value"); For
+List of acceptable statistic names for each of `var.*`:
+
+- `var.terms`: `c("estimate", "std.error", "statistic", "p.value")`; For
   interpretation please see
   [tidy.lm](https://broom.tidymodels.org/reference/tidy.lm.html).
 
-- `var.model`: c("r.squared", "adj.r.squared", "sigma", "statistic",
-  "p.value", "df", "logLik", "AIC", "BIC", "deviance", "df.residual",
-  "nobs"); For interpretation please see
+- `var.model`:
+  `c("r.squared", "adj.r.squared", "sigma", "statistic", "p.value", "df", "logLik", "AIC", "BIC", "deviance", "df.residual", "nobs")`;
+  For interpretation please see
   [glance.lm](https://broom.tidymodels.org/reference/glance.lm.html).
 
 For p-value corrections (arguments `correct.p.value.*`), supported
-methods include all methods in \`p.adjust.methods\` except "none". Can
-be more than one method. FDR-corrected p-values ("fdr") are calculated
-by default. Turn it off by setting to "none".  
+methods include all methods in `p.adjust.methods` except `"none"`. You
+can request more than one method. FDR-corrected p-values (`"fdr"`) are
+calculated by default. Turn it off by setting to `"none"`.
+
 Arguments `num.subj.lthr.abs` and `num.subj.lthr.rel` are mainly for
 input data with subject-specific masks, i.e. currently only for volume
 data. For fixel-wise data, you may ignore these arguments.
+
+## See also
+
+[`ModelArray.gam`](https://pennlinc.github.io/ModelArray/reference/ModelArray.gam.md)
+for generalized additive models,
+[`ModelArray.wrap`](https://pennlinc.github.io/ModelArray/reference/ModelArray.wrap.md)
+for user-supplied functions,
+[ModelArray](https://pennlinc.github.io/ModelArray/reference/ModelArray-class.md)
+for the input class,
+[`ModelArray`](https://pennlinc.github.io/ModelArray/reference/ModelArray-class.html)
+for the constructor,
+[`exampleElementData`](https://pennlinc.github.io/ModelArray/reference/exampleElementData.md)
+for testing formulas on a single element.
+
+## Examples
+
+``` r
+if (FALSE) { # interactive()
+ma <- ModelArray("path/to/data.h5", scalar_types = c("FD"))
+phenotypes <- read.csv("cohort.csv")
+
+# Fit linear model with default outputs
+results <- ModelArray.lm(
+  FD ~ age + sex,
+  data = ma,
+  phenotypes = phenotypes,
+  scalar = "FD"
+)
+head(results)
+
+# Full outputs, no p-value correction
+results_full <- ModelArray.lm(
+  FD ~ age + sex,
+  data = ma,
+  phenotypes = phenotypes,
+  scalar = "FD",
+  full.outputs = TRUE,
+  correct.p.value.terms = "none",
+  correct.p.value.model = "none"
+)
+}
+```