Save Model Output to File with Timestamping and Format Handling

This function saves the output from `run_linear_models()` or a compatible list of model results to a `.RData` file. It supports saving either the full output (including summaries, residuals, and formulas) or just the fitted model objects. The function automatically appends a date-based timestamp to the filename (if not already present), ensures the correct file extension, and provides overwrite protection.

If a single model object (e.g., `lm`, `lmerMod`) is provided, it will be wrapped in a named list (`model1`) to ensure compatibility. Generic lists are also accepted, though a warning will be issued if the input is not from `run_linear_models()`.

Arguments

model_output: A model object or list of model results, ideally from `run_linear_models()`. Must be a list or a model object that can be wrapped in a list.
file_path: A character string specifying the file path to save the output. If `.RData` is not included, it will be appended automatically.
models_only: Logical. If `TRUE`, only the fitted model objects (e.g., `lm`, `lmerMod`) are saved. This is useful if you only need to re-run predictions or diagnostics later. If `FALSE` (default), the full output is saved — including model summaries, residuals, and formulas — which is recommended for most users.
verbose: Logical. If `TRUE` (default), prints styled messages summarizing the save operation and suggesting next steps.
overwrite: Logical. If `FALSE` (default), the function will stop if the file already exists. Set to `TRUE` to allow overwriting.

Value

(Invisibly) A list containing:

object: The object that was saved (either full output or model-only list).
path: The full file path where the object was saved.

Examples

if (FALSE) { # \dontrun{
# Run and save model output
results <- run_linear_models(data = mtcars,
                             outcome = "mpg",
                             exposure = "cyl")

save_model_output(results, "model_results")

# Save only the fitted model objects
save_model_output(results, "models_only", models_only = TRUE)

# Overwrite an existing file
save_model_output(results, "model_results", overwrite = TRUE)

# Save a single model directly
single_model <- lm(mpg ~ cyl + wt, data = mtcars)
save_model_output(single_model, "single_model_output")
} # }