Skip to content

feat: filter + schema CLI args, index columns - #109

Open
kaitj wants to merge 3 commits into
feat/generalize-ents/phase1from
feat/generalize-ents/phase2
Open

feat: filter + schema CLI args, index columns#109
kaitj wants to merge 3 commits into
feat/generalize-ents/phase1from
feat/generalize-ents/phase2

Conversation

@kaitj

@kaitj kaitj commented Aug 12, 2026

Copy link
Copy Markdown
Contributor

This PR

Phase 2 of the generalized entities refactor, building on top of Phase 1 (#107). Adds additional CLI arguments, index columns, and filtering.

__main__.py - new CLI flags and deprecations:

  • --filter / -f ENTITY=PATTERN - filter indexed files by entity key and glob pattern; malformed args logged and skipped
  • --schema PATH - path to custom BIDS schema
  • --subjects emits a DeprecationWarning diirecting users to --filter sub=...

_indexing.py - filtering + new index columns:

  • index_dataset() + batch_index_dataset() accepts new filters kwarg; include_subjects emits a DeprecationWarning
  • _match_single() + _match_filters() - entity value matching against glob patterns
  • _find_bids_subject_dirs refactored to use _match_single, removing unused _filter_include / _filter_exclude helpers
  • dataset_name, dataset_type, bids_versiion added to Arrow schema, populated from dataset_description.json
  • _read_dataset_description() cached helper; clear_schema_caches() exposed as public API

Type of Change

  • Bug fix
  • Enchancement / feature
  • Documentation
  • Other

Related Issue(s)


Stack created with GitHub Stacks CLIGive Feedback 💬

@github-actions

github-actions Bot commented Aug 12, 2026

Copy link
Copy Markdown

Coverage

Coverage Report
FileStmtsMissCoverMissing
__init__.py100100% 
__main__.py86891%127, 185, 187–188, 193, 223, 227, 231
_entities.py128199%301
_indexing.py250797%194, 203–204, 396–397, 487, 533
_logging.py31487%31, 38, 40–41
_metadata.py49492%40–41, 67, 72
_pathlib.py21386%19, 21, 23
_schema.py120199%298
_version.py110100% 
pybids
   __init__.py40100% 
   _bidsfile.py381366%67–69, 73–75, 79–81, 85–87, 91
   _layout.py1664573%68, 77, 86, 109, 119–120, 123, 143–144, 158–159, 173–174, 177–181, 185, 187–188, 191–192, 219, 224, 238, 315–317, 379–384, 386, 389–394, 396, 450, 470
   _utils.py14564%47–51
TOTAL9289190% 

Tests Skipped Failures Errors Time
212 0 💤 0 ❌ 0 🔥 11.433s ⏱️

@github-actions

github-actions Bot commented Aug 12, 2026

Copy link
Copy Markdown

Benchmark Results

Local index (1 workers) Remote index (4 workers) Bold query Metadata query Subject query
feat/generalize-ents/phase2 99.799 (99.791 ± 0.267) ms 125.013 (125.588 ± 2.124) s 335.490 (341.123 ± 22.304) µs 366.225 (367.516 ± 20.985) µs 36.379 (40.773 ± 10.623) µs
main 99.391 (99.495 ± 0.412) ms 129.320 (129.227 ± 1.119) s 385.239 (388.940 ± 35.064) µs 388.103 (392.475 ± 27.785) µs 33.174 (42.141 ± 19.628) µs
v2.3.1 100.829 (101.104 ± 0.967) ms 128.446 (128.303 ± 1.558) s 388.393 (392.643 ± 34.347) µs 382.724 (379.169 ± 21.419) µs 33.449 (36.831 ± 8.351) µs
feat/generalize-ents/phase2 vs main ratio ⚪ 1.004 ⚪ 0.967 🟢 0.871 🟢 0.944 🔴 1.097
feat/generalize-ents/phase2 vs v2.3.1 ratio ⚪ 0.990 ⚪ 0.973 🟢 0.864 ⚪ 0.957 🔴 1.088

median (mean ± std)

🔴 Slower   ⚪ No change (<5 %)   🟢 Faster

@kaitj
kaitj marked this pull request as ready for review August 20, 2026 18:14
@kaitj
kaitj force-pushed the feat/generalize-ents/phase2 branch from 13ef379 to 7f595cf Compare August 27, 2026 20:28
@kaitj
kaitj force-pushed the feat/generalize-ents/phase2 branch from 7f595cf to 923c5d8 Compare August 27, 2026 20:30
- Add _read_dataset_description() cached helper to read
  dataset_description.json
- Extend index schema with dataset_name, dataset_type, and
  bids_version columns populated from dataset description
- Add _match_filters() and _match_single() for glob-based entity
  filtering
- Add filters parameter to index_dataset() and batch_index_dataset()
- Emit DeprecationWarning when include_subjects is used (use
  filters={'sub': ...} instead)
- Add clear_schema_caches() function and export in __init__.py
- Add --filter/-f flag with ENTITY=PATTERN syntax, repeatable
- Add _parse_filters() to parse filter args, warn on malformed args
- Add _normalize_filters() to convert single-item lists to bare strings
  for compatibility with the API's dict[str, str | list[str]] type
- Add --schema flag forwarded to index_dataset, batch_index_dataset,
  and get_arrow_schema
- Emit DeprecationWarning when --subjects is used
- Merge --subjects values into filters['sub'] for backward compat
- Remove redundant _check_path loop (moved into expansion loop)
- Add `--filter / -f ENTITY=PATTERN` CLI flag for filtering indexed files
- Add `--schema` flag support for custom BIDS schema paths
- Emit DeprecationWarning for `--subjects` CLI flag and `include_subjects` kwarg
- Fix `_find_bids_subject_dirs` to use inline `_match_single` matching
- Replace `_filter_include`/`_filter_exclude` with direct pattern matching
- Add `cli_prog` module-scoped fixture for CLI tests
- Add tests for filter parsing, normalization, matching, and CLI integration
- Add tests for new index columns, clear_schema_caches, and schema loading
- Update `--schema` help text to accurately describe YAML directory/file input
- Add FBT001 to ignored test ruff rules
@kaitj
kaitj force-pushed the feat/generalize-ents/phase2 branch from 923c5d8 to 3309489 Compare September 2, 2026 17:38
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.

Generalize entities [Phase 2]

1 participant