malva-client 0.3.3

Python client for Malva Index

Malva Client

Python client for the Malva genomic search platform. Search genes, sequences, and natural language queries across >7,000 single-cell and spatial transcriptomics samples.

For full documentation, visit malva-client.readthedocs.io.

Installation

pip install malva-client

For single-cell analysis workflows:

pip install malva-client scanpy

Authentication

Generate an API token at malva.bio (login with ORCID, then go to Profile > Generate API Token), then configure the client:

malva_client config --server https://malva.mdc-berlin.de --token YOUR_API_TOKEN

Quick Start (CLI)

malva_client search "CD3D" --output results.csv
malva_client search "ATCGATCGATCGATCGATCGATCG" --format json
malva_client search "CD4 T cells in brain tissue"

Quick Start (Python)

from malva_client import MalvaClient

client = MalvaClient("https://malva.mdc-berlin.de", "YOUR_API_TOKEN")

# Search for genes, sequences, or natural language queries
results = client.search("CD3D")
print(results)

# Search for sequences
results = client.search("ATCGATCGATCGCCACATGGACTTGAC")

# Natural language queries
results = client.search("cells expressing markers of neurodegeneration")

Per-cell matrices

# First run a normal expression search
result = client.search("SPP1")

# Retrieve positive cells from that search job
cells = client.retrieve_cells(result, sample_ids=[123456])

# Inspect positive cells or project them onto a coexpression index
cell_ids = cells.get_cell_ids(sample_ids=[123456])
coexpr = cells.project("human_cortex", sample_ids=[123456], top_n_genes=50)

# If you only need projection, keep the cell transfer server-side
coexpr = client.get_coexpression(result.job_id, "human_cortex", filter_sample_ids=[123456])

# If downstream code needs per-feature cell values, store them in the search job
value_result = client.search("SPP1", aggregate_expression=False)
value_cells = client.retrieve_cells(value_result, sample_ids=[123456])

Working with Results

# Enrich results with metadata
results.enrich_with_metadata()
fig = results.plot_expression_summary("cell_type")

# Filter and aggregate
filtered = results.filter_by(disease='normal', organ='brain')

See the tutorials for coverage analysis, dataset discovery, cell-level searches, and more.

Indexing Your Own Data

For local indexing and quantification, see Malva Tools (malva CLI).

Citation

If you use Malva in your research, please cite:

[TBA]

License

The Clear BSD License - Copyright (c) 2025-2026 Malva