Summary: Which Approach Should You Use?

Path 1: Fast (1 minute)

# Change this:
from bids.layout import BIDSLayout

# To this:
from bids2table_compat import BIDSLayout

# Done! 20x faster, no other changes needed

Supported methods in Path 1:

✅ layout.get(subject='01', suffix='T1w', return_type='filename')
✅ layout.get_subjects(), layout.get_sessions()
✅ layout.get_metadata(file_path)
✅ layout.get_entities() - returns dict of entity values
✅ layout.add_custom_entity(name, values) - add custom columns
✅ Query sentinels: Query.OPTIONAL, Query.NONE, Query.ANY
✅ Access underlying DataFrame: layout.df
⚠️ Not supported: Database queries, graph operations, complex validators
⚠️ Not supported: build_path(), parse_file_entities() - use DataFrame operations instead

For most neuroimaging pipelines, the supported methods cover 95%+ of use cases. Path 2: Gradual (over time)

Path 3: All-in (1-2 hours)

All three modern approaches are ~20x faster than PyBIDS for indexing. For queries:

Start with bids2table_compat for immediate gains, then migrate to native DataFrames when you have time.

Need Help?

Happy migrating! 🎉