aablocks

aablocks

A-Alpha Bio SDK for accessing Atlas data blocks.

Installation

pip install aablocks

For DataFrame support:

pip install aablocks pandas   # For pandas
pip install aablocks polars   # For polars

Quick Start

Python

import aablocks as aa

# Login (opens browser)
aa.login()

# List data blocks
blocks = aa.list_blocks()

# Get data as pandas DataFrame
df = aa.get_data("ab1001")

CLI

# Login (opens browser)
> aablocks login

# List data blocks
> aablocks list

# Download a data block
> aablocks get ab1614 -o data.csv

# Download structure files
> aablocks structures ab1614

Python API

aa.login()

Authenticate with the Atlas. Opens browser for OAuth. No-op if already logged in.

import aablocks as aa
aa.login()

aa.logout()

Clear cached authentication token.

aa.logout()

aa.list_blocks(all_versions=False, format=None)

List all accessible data blocks.

Parameters:

Returns: list[DataBlock] | str | DataFrame

# As pandas DataFrame
df = aa.list_blocks()

# As DataBlock objects
blocks = aa.list_blocks(format="list")
for d in blocks:
    print(f"{d.id}: {d.name}")

# All versions as polars
df = aa.list_blocks(all_versions=True, format="polars")

aa.get_details(block_id, version=None)

Get metadata for a specific block.

Parameters:

Returns: DataBlock

block = aa.get_details("ab1001")
print(block.name)
print(block.modes)  # ['source', 'ml']

aa.get_datacard(block_id, version=None)

Get the datacard content for a block.

Parameters:

Returns: dict (see OpenAPI DatacardResponse schema)

datacard = aa.get_datacard("ab1001")
print(datacard["exec"]["scientific_value"])
for uc in datacard["exec"]["use_cases"]:
    print(uc["title"], uc["description"])

aa.get_data(block_id, version=None, mode=None, format=None, output_path=None, output_compressed=False, progress=None, schema=True, load_negatives=False)

Download data for a data block. When schema=True (default), column types are automatically applied when reading as pandas or polars — no manual schema handling needed.

Parameters:

Returns: str | DataFrame | None

# Pandas DataFrame with proper types (Int64, Float64, boolean, string)
df = aa.get_data("ab1001")
print(df.dtypes)

# Polars DataFrame with proper types
df = aa.get_data("ab1001", format="polars")
print(df.schema)

# ML-ready data
df = aa.get_data("ab1001", mode="ml")

# Include negative control rows (ANeg/AlphaNeg)
df = aa.get_data("ab1001", load_negatives=True)

# Skip schema (raw pandas inference)
df = aa.get_data("ab1001", schema=False)

# Download to file
aa.get_data("ab1001", output_path="data.csv")

# Download compressed
aa.get_data("ab1001", output_path="data.csv.gz", output_compressed=True)

aa.download_structures(block_id, version=None, output_path=None, progress=None)

Download all structure files for a data block as a zip archive.

Parameters:

Returns: str (output file path)

# Download structures (filename from server)
path = aa.download_structures("ab1614")

# Download to specific path
path = aa.download_structures("ab1614", output_path="structures.zip")

aa.download_structure(block_id, filename, version=None, output_path=None)

Download a single structure file for a block.

Parameters:

Returns: str (file content or output file path)

# Get structure content as string
content = aa.download_structure("ab1614", "structure.cif")

# Download to file
path = aa.download_structure("ab1614", "structure.cif", output_path="my_file.cif")

aa.set_config(key, value)

Set a configuration value.

aa.set_config("api_format", "polars")
aa.set_config("progress", False)

DataBlock

Data block metadata container returned by list_blocks(format="list") and get_details().

CLI

After installation, the aablocks command is available in your terminal.

Global Options

aablocks login

Log in to the Atlas. Opens your browser for authentication. Tokens are cached locally and automatically refreshed.

> aablocks login
Opening browser for authentication...
Logged in successfully.

aablocks logout

Log out and clear cached credentials.

> aablocks logout
Logged out successfully.

aablocks list [OPTIONS]

List all data blocks accessible to the current user.

# List as table (default) — columns: ID, Name, Version, Released, Structures, A Size, Alpha Size, Total PPI, Unique PPI, Modes
> aablocks list
ID           Name                           Version  Released     Structures   A Size     Alpha Size Total PPI    Unique PPI   Modes
--------------------------------------------------------------------------------------------------------------------------------------
ab1001       AlphaBlock 1001                1        2026-01-21                500        200        100000       50000        source, ml
ab1479       AlphaBlock 1479                1        2026-01-21                800        300        240000       95000        source
ab1614       AlphaBlock 1614                1        2026-01-21   34570

# List as JSON
> aablocks list -f json

# List as CSV
> aablocks list -f csv

# Include all versions
> aablocks list --all-versions

aablocks details <block_id> [OPTIONS]

Show detailed metadata for a specific block.

> aablocks details ab1001
ID:           ab1001
Name:         AlphaBlock 1001
Version:      1
Released:     2026-01-21
Groups:       tier1
Modes:        source, ml
Experiment:   Local affinity landscape on VHH72-SARS-CoV-2 RBD

aablocks datacard <block_id> [OPTIONS]

Show the datacard for a block.

# Display formatted datacard text
> aablocks datacard ab1001

# Get raw JSON
> aablocks datacard ab1001 --raw

# Save to file
> aablocks datacard ab1001 --raw > datacard.json

aablocks get <block_id> [OPTIONS]

Download CSV data for a block.

# Print CSV to stdout
> aablocks get ab1001

# Download to file
> aablocks get ab1001 -o data.csv

# Download compressed
> aablocks get ab1001 -o data.csv.gz -f gz

# Get ML-ready variant
> aablocks get ab1001 --mode ml

# Include negative control rows
> aablocks get ab1001 --load-negatives

# Display as table
> aablocks get ab1001 -f table

# Pipe to other tools
> aablocks get ab1001 | head -100 > sample.csv

aablocks structures <block_id> [OPTIONS]

Download structure files for a block. By default, downloads all structures as a zip archive. Use --file to download a single structure file.

# Download all structures as zip (filename from server)
> aablocks structures ab1614
Structures written to ab1614_structures.zip

# Download to specific path
> aablocks structures ab1614 -o my_structures.zip
Structures written to my_structures.zip

# Download a single structure file (prints content to stdout)
> aablocks structures ab1614 --file structure.cif

# Download a single structure file to disk
> aablocks structures ab1614 --file structure.cif -o
Structure written to structure.cif

# Download a single structure file to a specific path
> aablocks structures ab1614 --file structure.cif -o my_file.cif
Structure written to my_file.cif

aablocks config [key] [value]

Get or set configuration options.

# Show all settings
> aablocks config

# Get a specific value
> aablocks config cli_format

# Set a value
> aablocks config cli_format table

Examples

Complete Python Workflow

import aablocks as aa

# Authenticate
aa.login()

# Browse data blocks
blocks = aa.list_blocks(format="list")
print(f"Found {len(blocks)} data blocks")

for d in blocks[:3]:
    print(f"{d.id}: {d.name} (v{d.version})")

# Get details
details = aa.get_details("ab1001")
print(f"Modes: {details.modes}")

# Download data (schema applied automatically)
df = aa.get_data("ab1001")
print(df.head())

# ML version
df_ml = aa.get_data("ab1001", mode="ml")

# Read datacard
datacard = aa.get_datacard("ab1001")
print(datacard["exec"]["scientific_value"])

# Download structures
aa.download_structures("ab1614")

Scripting

# List data block IDs only
> aablocks list -f csv | tail -n +2 | cut -d, -f1

# Download all accessible data blocks
> for id in $(aablocks list -f csv | tail -n +2 | cut -d, -f1); do
    aablocks get $id -o "${id}.csv"
done

Schema

Each data block has a column schema that defines proper dtypes for pandas and polars. When using get_data(), schemas are applied automatically (schema=True by default).

Automatic Typing

import aablocks as aa

aa.login()

# Pandas — columns are typed as Int64, Float64, boolean, string
df = aa.get_data("ab1001")
print(df.dtypes)
# mata_description                       string
# alphaseq_affinity                      Float64
# above_background                       boolean
# pos_a                                  Int64

# Nullable integers stay Int64 (not float64) even with missing values
print(df["pos_a"].dtype)  # Int64

# Polars — columns are typed via schema_overrides
df = aa.get_data("ab1001", format="polars")
print(df.schema)
# {'mata_description': Utf8, 'alphaseq_affinity': Float64, 'pos_a': Int64, ...}

# Skip schema (raw inference)
df = aa.get_data("ab1001", schema=False)

Manual Schema Usage

# Fetch the schema separately
schema = aa.get_schema("ab1001")
# {'dtype': {'mata_description': 'string', 'pos_a': 'Int64', ...}, 'parse_dates': []}

# Use directly with pandas
import pandas as pd
df = pd.read_csv("local_data.csv", **schema)

# Convert to polars kwargs
polars_kwargs = aa.pandas_schema_to_polars(schema)
import polars as pl
df = pl.read_csv("local_data.csv", **polars_kwargs)

CLI

# Show schema for default mode
> aablocks schema ab1001
{
  "dtype": {
    "mata_description": "string",
    "alphaseq_affinity": "Float64",
    "above_background": "boolean",
    "pos_a": "Int64"
  }
}

# Show schema for ML mode
> aablocks schema ab1001 -m ml

License

Apache 2.0 — see LICENSE for details.