Skip to content

FSSgam

1.2.0Package record

Full Subsets Multiple Regression Using GAMs

0packages depend
334downloads / year
94.4%test coverage
10/13flavors OK

Overview

About

Full-subsets information-theoretic approaches are increasingly used to explore predictive power and variable importance when a wide range of candidate predictors are being considered. This package provides functions that can be used to construct, fit, and compare a complete model set of possible ecological or environmental predictors for a given response variable of interest. Models are based on Generalized Additive Models (GAMs) and build on the 'MuMIn' package. Advantages include the capacity to fit more predictors than there are replicates, automatic removal of models with correlated predictors, and support for model sets that include interactions between factors and smooth predictors, as well as smooth-by-smooth interactions via te(). Methods are described in Fisher et al. (2018) doi:10.1002/ece3.4134.

Changes in 1.2.0
  • generate_model_set() gains null.cov.cutoff, defaulting to 0.8, and returns null.term.correlations. **Behaviour change:** a predictor correlated with a variable named in null.terms above that cutoff is now dropped from the model set, and a warning names it, what it correlates with, and how strongly (FSSgam_package#23). null.terms forces a term into every candidate, and those terms were outside the cov.cutoff screen, which covers pred.vars.cont, pred.vars.fact and linear.vars only. So a candidate could be arbitrarily strongly correlated with a forced term and appear in every model in the set. That inflates the variance of the forced term's estimate, which is frequently the term the analysis exists to estimate, and nothing in the output indicated it. A separate cutoff, with a much looser default than cov.cutoff's 0.28, because the two screens answer different questions. cov.cutoff decides which predictors may appear together; this decides which predictor is so nearly a restatement of a forced term that fitting both is not informative. Set it to 1 to admit every predictor whatever its correlation with a forced term. **A variable inside a bs='re' smooth is excluded from the screen.** A random-effect grouping factor is correlated with the predictors measured within it by construction: in the companion repository's case study 2, null.terms is s(Location,Site,bs='re') and Status is nested in Location, so their correlation is 1. That is the design of the study rather than collinearity to screen out, and dropping Status there would be wrong. The screen is for a forced term that competes with a candidate for the same variation. Correlations among the null.terms variables themselves are neither computed nor screened. Those terms are forced in by the user's decision, and dropping one is what must not happen. null.term.correlations is returned whether or not anything is dropped, so the correlations can be inspected where no warning is raised; it is NULL where there is nothing to report. A supplied cor.matrix is used for any forced term it names in either dimension, overriding the computed estimate for that term; the rest of the block is computed from use.dat, which is the ordinary case, a supplied matrix being indexed by predictor and a forced term not being one. Requiring the matrix to name the term would disable this screen for every caller who supplies one. Where the computation fails -- which is what a predictor of a class check_correlations() cannot classify causes -- the screen is skipped with a warning rather than the call stopping, so a caller relying on FSSgam_package#13 still gets their model set and is told their forced terms were not screened. **A pair a supplied cor.matrix gives no value for is treated as not supplied, and computed from use.dat.** That is NA in both directions, or NA in the one direction a matrix naming the forced term in a single dimension has. Read as a correlation of zero, such a pair admitted the predictor to every candidate alongside the forced term -- the outcome this screen exists to prevent -- decided by a cell the user left empty rather than by a correlation, while the same NA between two predictors stops the call (FSSgam_package#27). Where one direction gives a value, that value is used, unchanged. A forced term can be part supplied and part computed, the two being merged cell by cell rather than row by row (FSSgam_package#41). Where the correlation estimate is asymmetric, as check_non_linear_correlations() returns it, both directions are read and the larger is used -- what the cov.cutoff screen already does. Reading one direction admitted a candidate that is a deterministic function of a forced term: measured on a squared forced term in the committed test, [forced, candidate] is 0.280 -- below the default cutoff -- while [candidate, forced] is 0.991. The smaller figure depends on the random draw and the test asserts only that it is below the cutoff, which is the property that matters. Each cell of null.term.correlations is the value screened on rather than one direction of it; on the symmetric default path the two are equal. null.cov.cutoff is validated: it must be a single non-negative number. Unvalidated, an NA gave an internal "missing value where TRUE/FALSE needed" and a length-2 value was accepted silently. Where dropping predictors leaves fewer than max.predictors, the error says so and names them, rather than reporting only that max.predictors exceeds the number of predictors.
Show all changes in 1.2.0Hide the rest of the changes in 1.2.0
  • **Behaviour change:** a test.fit produced by mgcv::gamm() directly is rejected, with a message naming the remedy. Such a fit records no call, so stats::update() has nothing to re-evaluate and every candidate refit fails. The error it produced instead -- "need an object with call component" -- named neither the argument nor the remedy, and the message that followed advised the user to stop using uGamm, which is what they would have had to use to succeed (FSSgam_package#34). The documentation is corrected with it. generate_model_set()'s null.terms text directed the user to gamm for a correlation structure, its @details contrasts gam and gamm at length, and fit_model_set()'s r2.type names gamm among the classes it reports for. All three now say that a gamm fit reaches this package only through MuMIn::uGamm, which supplies the call that a bare mgcv::gamm() fit lacks.
  • **Behaviour change:** generate_model_set() rejects a predictor named twice within pred.vars.cont, pred.vars.fact or linear.vars, naming it. Such a name produced a candidate holding it twice, ZONE+ZONE, together with two "no non-missing arguments to max; returning -Inf" warnings naming nothing: enumerate_candidate_models() deduplicates a candidate's terms before indexing the correlation matrix, so a candidate holding one term twice gives a 1x1 sub-matrix whose triangles are empty, and max() of an empty vector returns -Inf, which is below any cov.cutoff (FSSgam_package#28). The warnings had a second cause, which rejecting the repeated name does not address: naming a predictor in both pred.vars.cont and linear.vars, the documented idiom below, puts the name in the candidate pool twice and reaches the same empty triangle at any max.predictors of 2 or more. Both screens now test the sub-matrix through a helper that returns FALSE for an empty triangle rather than calling max() on it, so no candidate set emits the warning. Which combinations survive is unchanged, -Inf having been below every cutoff. A name appearing in both pred.vars.fact and pred.vars.cont or linear.vars is rejected too, as is a name repeated within the character form of factor.factor.interactions or smooth.smooth.interactions. That last is a third route to the same defect and the one the others miss: factor.factor.interactions = c("fa", "fa", "fb") built the interaction column fa.I.fb twice, so use.dat gained two columns of that name and the candidate set gained fa.I.fb+fa.I.fb. A name appearing in both pred.vars.cont and linear.vars is **not** rejected: that is the documented way to fit a continuous predictor linearly, setdiff(pred.vars.cont, linear.vars) deciding which predictors get a smooth.
  • **Behaviour change:** a variable named in the character form of factor.factor.interactions or smooth.smooth.interactions must be a predictor of the model set. Each argument was checked against the wrong set -- the first against colnames(use.dat), so any column was accepted, and the second against rownames(cor.matrix), so what was accepted depended on whether a cor.matrix was supplied and what names it carried. A non-predictor named in either was screened against cov.cutoff and contributed interaction terms, while appearing in no other candidate, in included.vars, or in the variable-inclusion columns fit_model_set() returns (FSSgam_package#37).
  • **Behaviour change:** a factor predictor with fewer than two observed levels is rejected, naming it and its level count. Such a factor explains nothing, cannot be screened for collinearity, and produces an interaction column that is a copy of the other factor, so the model set holds the same model under two names. Levels declared but taken by no row are counted as absent (FSSgam_package#33).
  • Bug fix: check_correlations() and check_non_linear_correlations() now wrap their lm() call in try(), as every other fit in both already was. It was the one unguarded fit in each, so a single-level factor stopped the whole call with "contrasts can be applied only to factors with 2 or more levels" instead of leaving that cell NA. Both are exported and callable directly, so the guard matters beyond the generate_model_set() path the check above covers (FSSgam_package#33).
  • **Behaviour change:** a hard coded factor interaction column whose generated name is already a column of use.dat is not created, and a warning names it. cbind() accepted the duplicate, and every later stage selects predictors by name: use.dat[, "a.I.b"] returned the first of the two, which is the user's own column, while the model formulas and the correlation matrix were built for the generated one. Nothing reported the collision. Declining rather than overwriting, because overwriting silently changes a predictor the user named (FSSgam_package#22). This is reached without contrivance: passing the used.data of one call as the use.dat of the next presents every generated name as an existing column. Two generated names can also collide with each other, which is the same defect reached from inside rather than outside: (a, b.I.c) and (a.I.b, c) both paste to a.I.b.I.c, and the two columns are different variables. That is declined and warned about as well, though it is no longer reachable through the public API, the predictor name it requires being rejected by the check below.
  • **Behaviour change:** a predictor whose name contains .by., .te., .t., .I., + or * is rejected, as is one named null. Those strings separate the parts of a generated term name and are found with grep(fixed = TRUE) over every term, so a predictor named catch.by.effort -- an ordinary variable name -- was parsed as an interaction. The candidate became ~s(catch.by.effort) + s(catch, by = effort), which cannot be fitted, so the predictor vanished from the model set. The only indication was the -Inf warnings, which this release removes for unrelated reasons (FSSgam_package#39). + joins the terms of a candidate name and * writes a linear interaction, so either is parsed as more than one term in the same way. null is the name given to the null model's own candidate, so a predictor of that name produced two candidates called null: mod.formula[["null"]] returned the first, and the variable importance table matched the wrong row. factor.smooth.interactions in its character form is validated alongside the other two interaction arguments, which it was not. This rejects the failure rather than fixing the parse. Making a term's structure explicit instead of recovering it from its name is a larger change, and the issue records what it would involve. One consequence is worth knowing: passing the used.data of one call as the use.dat of the next presents generated names, which contain .I. by construction, so those columns must be dropped or renamed before they can be named as predictors.
  • Bug fix: a user-supplied cor.matrix with exactly one cell was silently discarded and recomputed from use.dat. A model set with a single predictor is the only case in which a supplied matrix is 1x1, and length(cor.matrix) == 1 was the test for "nothing supplied", which a 1x1 matrix also satisfies. The supplied value governed no screen and did not appear in predictor.correlations, which is the opposite of the documented contract that a supplied matrix replaces the automatic estimate (FSSgam_package#26). The test is now on the default value rather than on length, in both places it was made -- build_predictor_correlation_matrix() and the factor_correlations() helper inside resolve_factor_interactions(), which had its own copy. It tests dimensionality rather than a list of accepted classes, so the S4 matrix Matrix::Matrix() returns is accepted, as it was before this argument was validated at all. Note that Matrix::nearPD() is not such a case: it returns a list whose mat component is the matrix, and only that component was ever accepted. **Behaviour change:** cor.matrix is now validated, and a value that is neither a matrix, a data.frame, nor NA is rejected naming its class. What happened to such a value before depended on its length, and neither outcome was right. A length-one value of any class -- a string, or a list holding a matrix -- satisfied the sentinel and was silently treated as nothing supplied, so the model set was built from a computed matrix as though the argument had not been given. A value of any other length fell through to the supplied branch and failed against the missing-predictor check, reporting predictors rather than the argument. Calls of the first kind used to run and now error.
  • **Behaviour change:** an NA between two terms of a supplied cor.matrix is now reported by generate_model_set(), naming the pairs, where it previously stopped the call with missing value where TRUE/FALSE needed — naming neither the matrix, the argument, nor the pair (FSSgam_package#27). The report is made where each sub-matrix is formed, immediately before the screen takes max(abs(.)) of it, rather than at a single earlier point. Two earlier placements were tried and both were wrong, in opposite directions. Checking only in build_predictor_correlation_matrix() missed every pair screened before it, resolve_factor_interactions() running first. Checking a union of every name that might be screened then reported pairs that are not: a name given in the character form of factor.factor.interactions is screened against the others in that argument and never against pred.vars.cont. Reporting at the screening site covers exactly the pairs that are screened. **A consequence, and a departure from what the issue asked for.** The report covers exactly the pairs some screen compares, so it depends on max.predictors and on the interaction arguments. The issue asked for the report not to depend on max.predictors; that would mean rejecting a matrix over a cell nothing reads, which is a false failure. An NA is reported whenever it is read and not otherwise. Note that "read" is not the same as "in a candidate together". A .by. term is one term of a candidate but splits into two for the screen, so at max.predictors = 1 a continuous predictor and a factor are still compared; two continuous predictors are not.
  • Bug fix: the correlation matrix resolve_factor_interactions() computes when no cor.matrix is supplied is now zero-filled, as the one build_predictor_correlation_matrix() computes already was. Without it a computed matrix reached the factor-factor screen with NA in it -- check_correlations() returns NA for a pair involving a single-level factor (FSSgam_package#33) -- and the call stopped with missing value where TRUE/FALSE needed (FSSgam_package#27). **Behaviour change, and a poor outcome that is better than the error it replaces.** An NA becoming zero means "uncorrelated", so a factor-factor pair that previously stopped the call is now admitted. Where the NA came from a single-level factor the interaction column is a copy of the other factor: fa.I.const is paste(fa, "a"), so fa and fa.I.const are the same model under two names, and both enter the AICc table and the variable importance scores. That is not a good model set, and the real defect is that a single

The NEWS section is longer than shown here.

From NEWS.md in the release

Install

Health

CRAN checks
3ERROR10OK
Check messages
ERRORtestsr-oldrel-macos-arm64, r-oldrel-macos-x86_64, r-release-macos-x86_64

r-oldrel-macos-arm64

Running ‘testthat.R’ [17s/18s]
Running the tests in ‘tests/testthat.R’ failed.
Complete output:
  > # This file is part of the standard setup for testthat.
  > # It is recommended that you do not modify it.
  > #
  > # Where should you do additional test configuration?
  > # Learn more about the roles of various files in:
  > # * https://r-pkgs.org/testing-design.html#sec-tests-files-overview
  > # * https://testthat.r-lib.org/articles/special-files.html
  > 
  > library(testthat)
  > library(FSSgam)
  > 
  > test_check("FSSgam")
  Loading required package: nlme
  This is mgcv 1.9-4. For overview type '?mgcv'.
  Loading required package: gamm4
  Loading required package: Matrix
  Loading required package: lme4
  
  Attaching package: 'lme4'
  
  The following object is masked from 'package:nlme':
  
      lmList
  
  This is gamm4 0.3-0
  
  Saving _problems/test-generate_model_set-658.R
  [ FAIL 1 | WARN 0 | SKIP 13 | PASS 909 ]
  
  ══ Skipped tests (13) ═════════════════════════════
...[truncated]...
═══════════════════════════
  • On CRAN (12): 'test-check_correlations.R:83:3',
    'test-fit_model_set_parallel.R:16:3', 'test-fit_model_set_parallel.R:34:3',
    'test-fit_model_set_parallel.R:54:3', 'test-fit_model_set_parallel.R:77:3',
    'test-fit_model_set_parallel.R:110:3', 'test-fit_model_set_parallel.R:130:3',
    'test-numerical-regression.R:81:1', 'test-numerical-regression.R:89:1',
    'test-numerical-regression.R:102:1', 'test-numerical-regression.R:114:1',
    'test-numerical-regression.R:136:1'
  • set FSSGAM_TEST_PARALLEL=true to run the parallel tests (1):
    'test-criterion.R:574:3'
  
  ══ Failed tests ════════════════════════════════════════════════════════════════
  ── Failure ('test-generate_model_set.R:657:3'): candidate model names do not depend on the collation locale ──
  Expected `identical(...)` to be FALSE.
  Differences:
  `actual`:   TRUE 
  `expected`: FALSE
  
  
  [ FAIL 1 | WARN 0 | SKIP 13 | PASS 909 ]
  Error:
  ! Test failures.
  Execution halted

r-oldrel-macos-x86_64

Running ‘testthat.R’ [49s/67s]
Running the tests in ‘tests/testthat.R’ failed.
Complete output:
  > # This file is part of the standard setup for testthat.
  > # It is recommended that you do not modify it.
  > #
  > # Where should you do additional test configuration?
  > # Learn more about the roles of various files in:
  > # * https://r-pkgs.org/testing-design.html#sec-tests-files-overview
  > # * https://testthat.r-lib.org/articles/special-files.html
  > 
  > library(testthat)
  > library(FSSgam)
  > 
  > test_check("FSSgam")
  Loading required package: nlme
  This is mgcv 1.9-4. For overview type '?mgcv'.
  Loading required package: gamm4
  Loading required package: Matrix
  Loading required package: lme4
  
  Attaching package: 'lme4'
  
  The following object is masked from 'package:nlme':
  
      lmList
  
  This is gamm4 0.3-0
  
  Saving _problems/test-generate_model_set-658.R
  [ FAIL 1 | WARN 0 | SKIP 13 | PASS 909 ]
  
  ══ Skipped tests (13) ═════════════════════════════
...[truncated]...
═══════════════════════════
  • On CRAN (12): 'test-check_correlations.R:83:3',
    'test-fit_model_set_parallel.R:16:3', 'test-fit_model_set_parallel.R:34:3',
    'test-fit_model_set_parallel.R:54:3', 'test-fit_model_set_parallel.R:77:3',
    'test-fit_model_set_parallel.R:110:3', 'test-fit_model_set_parallel.R:130:3',
    'test-numerical-regression.R:81:1', 'test-numerical-regression.R:89:1',
    'test-numerical-regression.R:102:1', 'test-numerical-regression.R:114:1',
    'test-numerical-regression.R:136:1'
  • set FSSGAM_TEST_PARALLEL=true to run the parallel tests (1):
    'test-criterion.R:574:3'
  
  ══ Failed tests ════════════════════════════════════════════════════════════════
  ── Failure ('test-generate_model_set.R:657:3'): candidate model names do not depend on the collation locale ──
  Expected `identical(...)` to be FALSE.
  Differences:
  `actual`:   TRUE 
  `expected`: FALSE
  
  
  [ FAIL 1 | WARN 0 | SKIP 13 | PASS 909 ]
  Error:
  ! Test failures.
  Execution halted

r-release-macos-x86_64

Running ‘testthat.R’ [49s/69s]
Running the tests in ‘tests/testthat.R’ failed.
Complete output:
  > # This file is part of the standard setup for testthat.
  > # It is recommended that you do not modify it.
  > #
  > # Where should you do additional test configuration?
  > # Learn more about the roles of various files in:
  > # * https://r-pkgs.org/testing-design.html#sec-tests-files-overview
  > # * https://testthat.r-lib.org/articles/special-files.html
  > 
  > library(testthat)
  > library(FSSgam)
  > 
  > test_check("FSSgam")
  Loading required package: nlme
  This is mgcv 1.9-4. For overview type '?mgcv'.
  Loading required package: gamm4
  Loading required package: Matrix
  Loading required package: lme4
  
  Attaching package: 'lme4'
  
  The following object is masked from 'package:nlme':
  
      lmList
  
  This is gamm4 0.3-0
  
  Saving _problems/test-generate_model_set-658.R
  [ FAIL 1 | WARN 0 | SKIP 13 | PASS 909 ]
  
  ══ Skipped tests (13) ═════════════════════════════
...[truncated]...
═══════════════════════════
  • On CRAN (12): 'test-check_correlations.R:83:3',
    'test-fit_model_set_parallel.R:16:3', 'test-fit_model_set_parallel.R:34:3',
    'test-fit_model_set_parallel.R:54:3', 'test-fit_model_set_parallel.R:77:3',
    'test-fit_model_set_parallel.R:110:3', 'test-fit_model_set_parallel.R:130:3',
    'test-numerical-regression.R:81:1', 'test-numerical-regression.R:89:1',
    'test-numerical-regression.R:102:1', 'test-numerical-regression.R:114:1',
    'test-numerical-regression.R:136:1'
  • set FSSGAM_TEST_PARALLEL=true to run the parallel tests (1):
    'test-criterion.R:574:3'
  
  ══ Failed tests ════════════════════════════════════════════════════════════════
  ── Failure ('test-generate_model_set.R:657:3'): candidate model names do not depend on the collation locale ──
  Expected `identical(...)` to be FALSE.
  Differences:
  `actual`:   TRUE 
  `expected`: FALSE
  
  
  [ FAIL 1 | WARN 0 | SKIP 13 | PASS 909 ]
  Error:
  ! Test failures.
  Execution halted

CRAN check page ↗

Slowest check: 3.5 min · r-oldrel-windows-x86_64
Status changes
  • ERROR10 OK, 3 ERRORNow
  • ERROR2 OK, 1 ERROR2026-09-28
Advisories

none known

Documentation

In release 1.2.0
READMEYes · 356 wordsVignettesNoNEWSYes · 100% structured · mentions 1.2.0Citation fileNoWebsiteYes · pkgdown
Help pages
17 (1 internal)includes a package overview page
Examples that run
100%12 run in a plain check
Exported functions with examples
100%
Documented parameters
100%
Return-value docs
100%
Help pages citing references
6%

Downloads

334
CRAN downloads in the past year
Rank #25,313 · ~1/day · ~28/mo
Daily download trend is not available in this view yet.
33430 days
33490 days
3341 year
Compare downloads with other packages →
Also on5 r2u1 autocran

Repository

2Stars
1Forks
0Open issues
0Open PRs
1Releases
301Commits
1Commit identities
301 commits · Last activity 2026-09-29 · Default branch at 1.2.0.9000, ahead of CRAN 1.2.0 (checked 2026-10-21)
Responsiveness
How these are sampled
PRs merged (all time)
100%
Median days to close, 50 most recently updated closed issues
4
Median days to close, 50 most recently updated closed PRs
0

Releases over time

2026-09-28 · 02026-09-29 · 1
PracticesBeta

8 development-tooling and community-health practices detected across 5 families in the upstream repository

Checks run against github.com/beckyfisher/fssgam_package on 2026-10-21.

Continuous integration (2)
GitHub ActionsR CMD check workflow

The R CMD check workflow runs on Linux, macOS and Windows, and on R-devel

Docs source (3)
pkgdown

GitHub Pages site last deployed 2026-09-29 · The repository has a site deploy workflow

pkgdown site last built 2026-09-29

Coverage (1)
Coverage reporting
Reproducibility and dev environment (1)
data-raw/
Show all practicesHide 1 practice
CRAN release process (1)
cran-comments.md
How this is detected·Detection ruleset v4 (2026-10-20)
AI coding toolsBeta

This repository shows signs of AI coding tools.

  • Claude Codefirst seen 2026-06-20
    Seen in the repository: CLAUDE.md
    Named in .Rbuildignore: CLAUDE.md
    Pull request it wrote: opened by a project member
    Commits: at least 164 crediting it in the message
Models named in its commits
  • Claude Opus 5117 commits · Aug to Sep 2026
  • Claude Sonnet 4.627 commits · Jun 2026
  • Claude Opus 4.82 commits · Jul 2026

Some of these counts are a minimum, because the search stopped before the oldest commits.

Counts are commits, not lines of code. Commits by a tool's accounts count once across all of its accounts. Commits crediting it are the largest count among its credit lines, a minimum.How this is detected·Detection ruleset v4 (updated 2026-09-27)

Dependencies

Declared dependencies
6 external dependencies (excludes base and recommended)

Installing FSSgam adds 6 packages (0 with compiled code, 1.8 MB of source tarballs). Heaviest: insight 1.2 MB, iterators 293 KB, MuMIn 186 KB.

Depends (1)
R >= 4.4.0
Imports (8)
doSNOWforeachmgcvMuMInnnetparallelstatsutils
LinkingTo (0)
none
Suggests (4)
Enhances (0)
none
Reverse dependencies
0direct
0indirect

Nothing depends on this yet.

Datasets

People & History

People (2)
Author, Maintainer since 1.2.0 (2026)
Releases (1)
  • 1.2.0Latest
    2026-09-28 · current release
  • R
    R 4.6.0 released · 2026-04-24

Package metadata

First published
2026-09-28
Total releases
1 / 1 yrs
License
Apache License (== 2.0)
Minimum R
≥ 4.4.0
Bundled data
46 KB / 4 files
Download size
208 KB

Cite

Cite this package

Run in R for the authors' preferred citation:

citation("FSSgam")
Fisher, R., & Australian Institute of Marine Science. (2026). FSSgam: Full Subsets Multiple Regression Using GAMs (Version 1.2.0) [Computer software]. https://doi.org/10.32614/CRAN.package.FSSgam

This package has no citation file, so citation() returns this entry built from DESCRIPTION.

Cite the R Observatory

For a number measured here: a download total, a coverage figure, an archival date.

APA

Balamuta, J. J. (2026). R Observatory: Metrics for FSSgam version 1.2.0 [Data set]. HJJB, LLC. Data release v2026-10-23. https://doi.org/10.5281/zenodo.21843040

From data release v2026-10-23, which the citation names so these numbers can be found later. More on citing and the projects behind them.

Report a problem with this page →

Privacy choices

These apply to this browser and are stored on this device only. Nothing about your choice is sent to us.

Read the privacy policy