TileDB-VCF verification notes

Reviewed 2026-10-01 against TileDB-VCF 0.40.3 and tiledb-cloud 0.14.4.

Distribution and local environment

The official TileDB channel metadata listed 0.40.3 builds for Python 3.9-3.12 on osx-arm64, osx-64, and linux-64. PyPI tiledbvcf metadata and the conda-forge tiledbvcf-py package endpoint returned 404. This is a distribution constraint, not absence of a macOS build. The native library is also available through the project's documented source-build and container routes.

An unpinned native osx-arm64 Conda solve succeeded but importing the resulting package failed: its bundled libtiledb needed exact versioned Azure dylibs absent from the newer dependencies selected by Conda. Pinning azure-core-cpp 1.16.2, azure-storage-blobs-cpp 12.16.0, azure-storage-files-datalake-cpp 12.14.0, capnproto 1.4.0, and c-blosc2 2.23.1 resolved the import failure without binary patches. The resolved environment used Python 3.12.14, pandas 2.3.3, NumPy 2.5.3, and PyArrow 24.0.0. The CLI reported TileDB-VCF 0.40.3, embedded TileDB 2.30.0, and htslib 1.23; the Conda TileDB package version alone was not an accurate indicator of the bundled library's runtime version.

Tests in tests/tiledbvcf/ (repository-level, outside this shipped skill) use tiny synthetic, indexed VCFs, not real human data. Native checks cover incremental ingestion, multiallelic and missing GT values, deletion overlap boundaries, BED coordinates, sample partitions, total record limits, cohort statistics, QC, semantic per-sample export, and CLI create/store/list/stat/TSV. Native checks require the separate Conda build and bcftools; an ordinary uv environment cannot install TileDB-VCF from PyPI.

Source and runtime findings

• Released Python Dataset source defines memory_budget_mb, explicit create_dataset, the batch-continuation protocol, 1-based explicit region strings, and (index, count) partitions. read_iter does not accept set_af_filter; use read with continuation when applying that filter.
• Native in-memory exporter converts pos_start and pos_end to 1-based output while keeping BED endpoints in BED conventions. Statistics pos remained 0-based in the native fixture.
• A BED read followed by a string-region read on the same Dataset retained the old BED interval, adding a record outside the new requested window. The skill requires reopening the reader when switching selectors. This is an observed 0.40.3 behavior, not a universal claim about future releases.
• The CLI's variadic --tiledb-config consumed following positional paths until -- was added. The invalid command printed a missing-input error with exit code zero. Validate sample counts and artifacts after ingestion.
• Cohort AF was 3/4 for a site where S1 was 0/1 and S2 was 1/1. Selecting S1 with AF >0.6 still returned S1, establishing that this query does not recompute AF on the selected sample subset. Both variant-statistics and allele-count tables reported the VCF POS=1 site as pos=0.

Cloud SDK and endpoint contracts

The published 0.14.4 wheel, including tiledb/cloud/vcf/query.py, vcf/ingestion.py, utilities/_common.py, client.py, config.py, and generated REST client modules, is the contract source. Some older website examples still name obsolete partition arguments; follow the released num_region_partitions signature.

The default service base is https://api.tiledb.com; a configured deployment host may override it. The SDK reads TILEDB_REST_TOKEN and sends it using the X-TILEDB-REST-API-KEY header. tiledb.cloud.Config() propagates the authenticated client configuration to the native library as rest.server_address and rest.token. Importing only the Cloud client does not supply that configuration to an independently opened native Dataset. login() can persist configuration; environment-based credentials avoid putting a literal token in the example.

These submission calls use API-key or basic authentication and have no pagination query parameters. The SDK handles serialization, graph state, and result retrieval; the skill does not invent a /vcf REST endpoint. Route/method/body/auth and result-type dispatch were tested against the installed client with transport mocked. This is not proof that a hosted deployment accepts the calls today.

The distributed read wrapper waits for its DAG and returns pyarrow.Table. The public vcf.ingest wrapper starts a batch graph and returns a status/graph-ID mapping before completion. Underlying ingest_vcf validates exactly one source selector. The PyPI life-sciences extra installs TileDB-SOMA, not TileDB-VCF. Cloud account authorization, storage roles, quotas, distributed native image versions, paid execution, and remote object storage were not exercised.

Further official sources

• Data model
• Released CLI option definitions
• Released QC wrapper
• Released allele-frequency wrapper
• bcftools manual