ancpbids

ancpBIDS is a modular Python library for reading, querying, validating, and writing BIDS datasets. Its architecture is designed for extensibility and maintainability.

Key Features

BIDS Dataset Loading
Load BIDS datasets of any size or complexity, with support for multiple BIDS schema versions.
Flexible Query Engine
Query files, folders, and metadata using a powerful, Pythonic API. Supports entity-based, scope-based, and custom queries.
Validation
Validate datasets against the BIDS specification and custom rules using a plugin-based validation system.
Writing and Derivatives
Write and update BIDS datasets, including support for creating and saving BIDS derivatives.
Lazy Loading
Efficiently handle large datasets with optional lazy loading, reducing memory usage and speeding up initial access.
Plugin Architecture
Extend or customize core functionality (validation, file handling, schema, etc.) via a robust plugin system.
PyBIDS Compatibility Layer
Drop-in compatibility for many pybids API calls, easing migration from or integration with existing codebases.
Synthetic and Real Data Support
Works with both synthetic test datasets and real-world BIDS datasets.
CI/CD Ready
Includes a comprehensive suite of automated and manual tests, with synthetic datasets for reproducibility.
Extensible and Versioned Schema
Supports multiple BIDS schema versions and allows for easy extension as the BIDS standard evolves.

Architecture

Core Models:
The in-memory graph is hand-maintained in ancpbids/model_base.py. Versioned enums are loaded at runtime from official BIDS schema.json files vendored in ancpbids/schema/versions/.
Plugin System:
The extension mechanism (see ancpbids/plugin.py) allows for dynamic extension of core functionality. Plugins can hook into schema modification, dataset processing, file handling, writing, and validation. Graph methods (query, get_schema, …) live on the model classes; SchemaPlugin remains an extension point.
Query Engine:
The query logic is implemented in ancpbids/query.py, providing flexible access to dataset contents and metadata.
Compatibility Layer:
ancpbids/pybids_compat.py provides compatibility with the pybids API for easier migration and integration.
Utilities:
Helper functions and utilities are in ancpbids/utils.py.
Testing:
The tests/ directory is organized into auto (CI-safe) and manual (non-deterministic or performance) tests, with synthetic datasets under tests/data/.

Plugin and mixin system

Extensibility comes in two shapes:

Plugins — hook into load / write / validate / schema / file I/O (execute methods).
Mixins — add methods to a host class such as BIDSLayout via @mixin(target=...).

Built-in plugins/mixins are registered the same way: decorated with @hook(ranking=0, system=True) / @mixin(...) and listed under ancpbids.plugins / ancpbids.mixins in this project's pyproject.toml. Third-party packages add their own entries to those groups. Hooks are lifecycle contributors (execute); mixins add methods to host classes.

Registering an external plugin

Decorate a plugin subclass:

from ancpbids.plugin import ValidationPlugin, hook

@hook(ranking=1000)
class SiteRulesPlugin(ValidationPlugin):
    def execute(self, dataset, report: ValidationPlugin.ValidationReport):
        pass

In your package’s pyproject.toml:

[project.entry-points."ancpbids.plugins"]
site_rules = "lab_bids_extensions.validation:SiteRulesPlugin"

Install alongside ancpBIDS; importing ancpbids loads the plugin.

Registering an external mixin

Decorate a mixin with a target (live class or "module:Class" string):

from ancpbids import BIDSLayout
from ancpbids.plugin import mixin

@mixin(target=BIDSLayout, ranking=1000)
class MyExportMixin:
    def to_custom(self):
        ...

Advertise under ancpbids.mixins:

[project.entry-points."ancpbids.mixins"]
my_export = "lab_bids_extensions.exports:MyExportMixin"

Built-in DataFrameMixin lives in ancpbids.mixins.mixin_dataframe, uses @mixin(target=BIDSLayout, ranking=0), and is listed as to_df under the ancpbids.mixins entry-point group in this project's pyproject.toml.

Full guide: docs/source/plugins.rst.

Versioning and Schema Evolution

The codebase supports multiple BIDS schema versions via vendored schema.json files.
The schema is loaded dynamically based on the dataset version, allowing for forward compatibility.

Testing and CI

Unit Tests:
Located in tests/auto/, these are run automatically in CI.
Manual/Performance Tests:
Located in tests/manual/, these are for benchmarking or non-deterministic checks.
Synthetic Data:
All tests use synthetic datasets in tests/data/ to ensure reproducibility.

Developer Guidelines

Extending the Model:
Add a new ancpbids/schema/versions/schema_v<version>.json (see Model Generation Utility). Type stubs and model_latest update from the vendored JSON files.
Adding Plugins:
Follow the plugin system described above (including external entry points).
Testing:
Add new tests to tests/auto/ for CI-safe code, and to tests/manual/ for performance or integration tests.
Documentation:
Update README.md and docstrings for any new features or changes.

Code Quality

The codebase uses type hints and docstrings for clarity.
Contributions should follow PEP8 and include tests and documentation.

Model Generation Utility

The in-memory graph (ancpbids/model_base.py) is hand-maintained. tools/generatemodel.py fetches an official BIDS schema.json into ancpbids/schema/versions/ and writes version-specific type stubs under ancpbids/schema/stubs/ (v1_X_Y.pyi) so IDEs can see enum literals such as SuffixEnum.bold. Enums are still built from JSON at runtime.

Usage:

uv run --with requests python tools/generatemodel.py [--schema-version <version>]
uv run python tools/generatemodel.py --stubs-only

If --schema-version is omitted, the latest available schema version is used.
--stubs-only regenerates stubs from JSON files already in ancpbids/schema/versions/.
Output: ancpbids/schema/versions/schema_v<version>.json, ancpbids/schema/stubs/v1_X_Y.pyi, and ancpbids/schema/stubs/aliases.pyi.

Metadata

Release files for ancpbids 0.4.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ancpbids 0.4.10
File	Size	Uploaded	Provenance
ancpbids-0.4.10.tar.gz	2.4 MB	Aug 29, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for ancpbids 0.4.10
File	Interpreter	ABI	Platform	Reset
ancpbids-0.4.10-py3-none-any.whl 681.7 kB Aug 29, 2026 Without provenance	Python 3	none	any	Details

Total release size: 3.1 MB

Release files / ancpbids-0.4.10.tar.gz

Download URL	ancpbids-0.4.10.tar.gz
Size	2.4 MB
Tags	Source
SHA-256 checksum How to use checksums	`adeca96cead29bdcf84ecdcd8cac5fe9fb83dc8a219e378e88d085b47a1d4318`
BLAKE2b-256 checksum How to use checksums	`1b1cf94fed998a8a4a9e153e1a4ce58850c4d2084b569c2cf21a9b5809bbb6f2`
Upload date	Aug 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / ancpbids-0.4.10-py3-none-any.whl

Download URL	ancpbids-0.4.10-py3-none-any.whl
Size	681.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d003266f959a5c8adc6fcee0a1ab94681048394ab2ba2bed7ef06b4c23613230`
BLAKE2b-256 checksum How to use checksums	`e9bcc33c6aa159950992317bb1dc9660450b4c5f23f5cf20cdadd8ced875d897`
Upload date	Aug 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Security for ancpbids 0.4.10

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.