Metadata-Version: 2.4
Name: malva-client
Version: 0.3.0
Summary: Python client for Malva Index
Author-email: Daniel León-Periñán <daniel.leonperinan@mdc-berlin.de>, Nikos Karaiskos <nikolaos.karaiskos@mdc-berlin.de>
Maintainer-email: Daniel León-Periñán <daniel.leonperinan@mdc-berlin.de>, Nikos Karaiskos <nikolaos.karaiskos@mdc-berlin.de>
License-Expression: BSD-3-Clause-Clear
Project-URL: Documentation, https://malva-client.readthedocs.io
Project-URL: Source, https://github.com/malva-bio/malva_client
Project-URL: Homepage, https://malva.bio
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: pandas>=1.0
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0
Requires-Dist: pydantic>=1.8.0
Requires-Dist: keyring>=23.0.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: gprofiler-official>=1.0.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: anndata>=0.8.0
Requires-Dist: seaborn>=0.12.0
Requires-Dist: dnaio>=1.2.3
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: furo>=2024.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == "docs"
Requires-Dist: sphinx-click>=5.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Requires-Dist: sphinx-design>=0.5; extra == "docs"
Requires-Dist: nbsphinx>=0.9; extra == "docs"
Requires-Dist: pandoc; extra == "docs"
Requires-Dist: ipykernel; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: responses>=0.23; extra == "test"
Dynamic: license-file

# Malva Client

[![PyPI](https://img.shields.io/pypi/v/malva-client)](https://pypi.org/project/malva-client/)
[![Documentation](https://readthedocs.org/projects/malva-client/badge/?version=latest)](https://malva-client.readthedocs.io)
[![GitHub](https://img.shields.io/badge/GitHub-malva--bio%2Fmalva__client-blue)](https://github.com/malva-bio/malva_client)

Python client for the [Malva](https://malva.bio) 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](https://malva-client.readthedocs.io).

## Installation

```bash
pip install malva-client
```

For single-cell analysis workflows:
```bash
pip install malva-client scanpy
```

## Authentication

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

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

## Quick Start (CLI)

```bash
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)

```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")
```

### Working with Results

```python
# 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](https://malva-client.readthedocs.io/en/latest/tutorials.html) for coverage analysis, dataset discovery, cell-level searches, and more.

## Indexing Your Own Data

For local indexing and quantification, see [Malva Tools](https://github.com/malva-bio/malva) (`malva` CLI).

## Citation

If you use Malva in your research, please cite:

> [TBA]

## License

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