Skip to content

fix(docs): link required sites for models without a coefficients file - #216

Open
marcbal77 wants to merge 2 commits into
bio-learn:masterfrom
marcbal77:fix/doc-sites-file-for-api-models
Open

marcbal77 wants to merge 2 commits into
bio-learn:masterfrom
marcbal77:fix/doc-sites-file-for-api-models

Conversation

@marcbal77

@marcbal77 marcbal77 commented Sep 23, 2026 •

Copy link
Copy Markdown
Member

What

Closes #200. HurdleInflammAge showed N/A in the Coefficients column of the model table because it has no model.file. Its required CpGs already ship in biolearn/data/Hurdle_CpGs.csv, so the docs now link to that file instead.

How

  • New optional sites_file key in a model definition's model block, for models that have no coefficients file but do have a fixed list of required sites.
  • HurdleAPIModel reads its CpG list from sites_file rather than a hardcoded filename, so the definition is the single source for both the model and the docs. The default is unchanged (Hurdle_CpGs.csv), so direct construction behaves as before.
  • doc/generate.py links required sites when there is a sites_file and no file. Everything else in the generator is untouched.

Instantiating the model in the doc build (the approach floated in the issue) was avoided: HurdleAPIModel requires HURDLE_API_KEY to construct, which the docs build shouldn't depend on. Any future API-backed model can set sites_file and get the same treatment.

Output

Only one row of generated/model_table.csv changes:

- HurdleInflammAge,...,N/A
+ HurdleInflammAge,...,`required sites <https://github.com/bio-learn/biolearn/blob/master/biolearn/data/Hurdle_CpGs.csv>`_

model_usage.csv is identical.

Tests

  • test_sites_loaded_from_definition_sites_file: sites come from the definition's file.
  • test_missing_sites_file_falls_back_to_all_sites: the parameter is actually used, and an unknown file keeps the existing warn-and-fallback behavior.
  • test_sites_file_exists: every sites_file in model_definitions exists in biolearn/data, so the docs link can't point at a missing file.

The two Hurdle tests fail against master and pass here. make check-format clean. make test: 205 passed, 5 skipped, 0 failed.

Depends on #218

Stacked on #218, which fixes the CI failure every PR currently hits (geo2r now returns a CAPTCHA page). Merge #218 first and this diff reduces to the commit above.

Note

doc/generate.py also crashes on master in generate_data_csv_from_yaml because the NHANES and FHS entries from #203 have no samples field. That is fixed separately in #219.

geo2r now returns a CAPTCHA page to scripted requests, which broke CI on
master. The test stubs the metadata call, and _create_metadata raises a
clear error when the response is not JSON.
Add an optional sites_file key to model definitions. HurdleAPIModel now
loads its CpG list from it, and the doc generator links it in place of
N/A. Closes bio-learn#200.
@marcbal77
marcbal77 force-pushed the fix/doc-sites-file-for-api-models branch from 7235f1b to 546e9e5 Compare September 23, 2026 20:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

enhancement: surface required CpG sites in docs for models without a coefficients file

1 participant