Python client¶

The malva_client package is the recommended way to work with Malva from Python. It wraps the Malva API and returns pandas-friendly objects, so you can go from a search to a dataframe in a few lines.

The package talks to the same server and the same search backend as the web interface, so it uses the same authentication and counts against your daily search quota.

Install¶

pip install malva-client

Requires Python 3.9 or later.

Configure¶

Create an API token on your profile page, then store it with the command-line tool:

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

Alternatively, set the token in your environment:

export MALVA_API_TOKEN=YOUR_API_TOKEN

Connect¶

from malva_client import MalvaClient

client = MalvaClient()
print(client.is_authenticated())

Run a search¶

Gene search by symbol:

result = client.search("BRCA1")
df = result.df
print(df.head())

The default result is aggregated by sample and cell type. Common columns are sample_id, cell_type, gene_sequence, rel, exp, pct, raw_kmers and cell_count. The rel, exp, pct and raw_kmers columns match the display modes of the Expression Explorer.

Sequence search:

sequence = "ATCGATCGATCGATCGATCGATCG"
sequence_result = client.search_sequences(sequence)
print(sequence_result.df.head())

What else the client does¶

The client exposes a search job workflow, coverage searches, sample and study browsing, downloads, and cell-group queries. Methods include submit_search, get_job_status, wait_for_job, get_coverage, get_sequence_coverage, get_studies, get_samples, download_sample and get_cells_by_metadata.