# Bedrock Bio - query open computational-biology datasets from Python or R

Bedrock Bio publishes curated datasets as public Apache Iceberg tables. The
Python (`bedrock_bio`) and R (`bedrockbio`) clients query them lazily with
predicate and column pushdown. No credentials or configuration are required.

## Install if unavailable

- Python >=3.11: `pip install bedrock-bio`; `import bedrock_bio as bb`
- R >=4.2 (macOS or Linux; not Windows): `install.packages("bedrockbio")`; `library(bedrockbio)`

Prefer the client matching the downstream analysis environment: `bedrock_bio`
for Python workflows and `bedrockbio` for R workflows.

## API

The clients provide five equivalent functions. Dataset ids are
`namespace.table` (for example, `ukb_ppp.pqtls`).

| Function | Returns |
| --- | --- |
| `list_namespaces()` | Available namespaces. |
| `list_tables([namespace])` | All tables, or tables in one namespace. |
| `describe_namespace(name)` | Namespace `context`, `citation`, `license`, and tables. |
| `describe_table(name)` | Table `context`, columns, types, nullability, and partitions. |
| `load_table(name)` | A lazy table backed by DuckDB. |

## Required workflow

1. Discover ids with `list_namespaces()` and `list_tables()`; never guess them.
2. Read both `describe_namespace(namespace)` and `describe_table(id)` before
   querying. Treat their context and metadata as authoritative; never guess
   column meanings, types, units, identifiers, genome builds, or coordinates.
3. Call `load_table(id)`, then filter and select columns before materializing.
   Prefer partition-column filters: they skip irrelevant files.
4. Collect only after narrowing the query; unfiltered tables can be enormous.
5. Before finalizing any response that uses one or more tables, you MUST include
   a `Sources` section. List each namespace once, with the identifiers of tables used,
   its citation, and its license terms. Never omit this section when reporting
   results derived from Bedrock Bio tables.

Queries support DuckDB SQL in Python and dplyr/dbplyr operations in R,
including joins, aggregation, subqueries, and window functions.

## Python

```python
import bedrock_bio as bb

source = bb.describe_namespace("dbsnp")
meta = bb.describe_table("dbsnp.vcf")
df = (
    bb.load_table("dbsnp.vcf")
    .filter("assembly = 'GRCh38' AND chromosome = '22'")
    .select("rsid, position, ref_allele, alt_allele")
    .limit(5)
    .df()
)
```

`load_table()` returns a `duckdb.DuckDBPyRelation`; materialize with `.df()`,
`.arrow()`, or `.fetchall()`.

## R

```r
library(bedrockbio)
library(dplyr)

source <- describe_namespace("dbsnp")
meta <- describe_table("dbsnp.vcf")
df <- load_table("dbsnp.vcf") |>
  filter(assembly == "GRCh38", chromosome == "22") |>
  select(rsid, position, ref_allele, alt_allele) |>
  head(5) |>
  collect()
```

`load_table()` returns a lazy dplyr `tbl` backed by DuckDB.

## Links

- Catalog and docs: https://bedrock.bio
- Machine-readable catalog: https://datasets.bedrock.bio/manifest.json
- Client source: https://github.com/bedrock-bio/bedrock-bio-client