malva-client 0.3.2__tar.gz → 0.3.4__tar.gz

{malva_client-0.3.2 → malva_client-0.3.4}/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.4] - 2026-06-05
+### Added
+- Coverage APIs accept `stage_callback` and log separate search, server-result generation, download, and parse stages for large coverage responses.
+- `get_cells_by_metadata()` for search-independent all-cell denominator retrieval by sample and/or cell type. Database-wide retrieval is available with explicit `include_all_database_cells=True`.
+- Aggregate result columns now use a single Expression Explorer-style schema: `rel`, `exp`, `pct`, `raw_kmers`, and `cell_count`. Legacy expression names are still accepted by helper methods such as `aggregate_by(..., expr_column=...)` when they can be mapped unambiguously.
+
+### Changed
+- Quickstart and tutorials now avoid placeholder sample IDs and document the meaning of aggregate and per-cell expression values.
+- `retrieve_cells()` documentation clarifies that denominator cells should be fetched independently with `get_cells_by_metadata()`, while fallback positive-cell-only endpoints may report `value=1`.
+- All-cell metadata decoding uses categorical cell types and rounded/clipped `uint16` total counts for lower memory use and faster DataFrame construction.
+
+### Fixed
+- `retrieve_cells()` now prefers the direct msgpack per-cell expression values endpoint, which uses the same raw k-mer value resolver as the Explorer matrix export without generating a ZIP. Aggregate searches therefore return raw per-cell values instead of all `1.0` positive indicators when values are available.
+- Removed stale docs examples that produced errors with placeholder IDs or non-existent tutorial links.
+
 ## [0.3.2] - 2026-05-07
 ### Added
 - `retrieve_cells()` for direct per-cell retrieval from an existing search job,

{malva_client-0.3.2/malva_client.egg-info → malva_client-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: malva-client
-Version: 0.3.2
+Version: 0.3.4
 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>
@@ -89,8 +89,8 @@ malva_client config --server https://malva.mdc-berlin.de --token YOUR_API_TOKEN
 
 ```bash
 malva_client search "CD3D" --output results.csv
-malva_client search "ATCGATCGATCGATCGATCGATCG" --format json
-malva_client search "CD4 T cells in brain tissue"
+malva_client search "ATCGATCGATCGATCGATCGATCG" --output sequence_results.json --format json
+malva_client search "CD4 T cells in brain tissue" --output nl_results.csv --format csv
 ```
 
 ## Quick Start (Python)
@@ -98,17 +98,15 @@ malva_client search "CD4 T cells in brain tissue"
 ```python
 from malva_client import MalvaClient
 
-client = MalvaClient("https://malva.mdc-berlin.de", "YOUR_API_TOKEN")
+client = MalvaClient()
 
-# Search for genes, sequences, or natural language queries
+# Search for a gene and inspect aggregate expression rows
 results = client.search("CD3D")
-print(results)
+print(results.df.head())
 
-# Search for sequences
-results = client.search("ATCGATCGATCGCCACATGGACTTGAC")
-
-# Natural language queries
-results = client.search("cells expressing markers of neurodegeneration")
+# Search a DNA sequence of at least 24 nt
+sequence_results = client.search_sequences("ATCGATCGATCGATCGATCGATCG")
+print(sequence_results.df.head())
 ```
 
 ### Per-cell matrices
@@ -118,18 +116,22 @@ results = client.search("cells expressing markers of neurodegeneration")
 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])
+cells = client.retrieve_cells(result, include_sample_metadata=False)
+sample_id = int(cells.cells.iloc[0]["sample_id"])
+
+# Inspect cells from one real encoded sample ID
+sample_cells = client.retrieve_cells(result, sample_ids=[sample_id], include_sample_metadata=True)
+cell_ids = sample_cells.get_cell_ids()
+cell_df = sample_cells.to_dataframe(include_sample_metadata=True)
+print(cell_ids.head())
+print(cell_df.head())
+
+# Fetch all cells for that sample once from metadata for denominator analyses
+all_cells = client.get_cells_by_metadata(sample_ids=[sample_id])
+print(all_cells.head())
+
+# Full-database retrieval is also available; it queues a server-side export.
+# all_cells = client.get_cells_by_metadata(include_all_database_cells=True)
 ```
 
 ### Working with Results
@@ -137,10 +139,12 @@ value_cells = client.retrieve_cells(value_result, sample_ids=[123456])
 ```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')
+by_cell_type = results.aggregate_by('cell_type', agg_func='mean')
+print(filtered.df.head())
+print(by_cell_type.head())
 ```
 
 See the [tutorials](https://malva-client.readthedocs.io/en/latest/tutorials.html) for coverage analysis, dataset discovery, cell-level searches, and more.

{malva_client-0.3.2 → malva_client-0.3.4}/README.md

@@ -31,8 +31,8 @@ malva_client config --server https://malva.mdc-berlin.de --token YOUR_API_TOKEN
 
 ```bash
 malva_client search "CD3D" --output results.csv
-malva_client search "ATCGATCGATCGATCGATCGATCG" --format json
-malva_client search "CD4 T cells in brain tissue"
+malva_client search "ATCGATCGATCGATCGATCGATCG" --output sequence_results.json --format json
+malva_client search "CD4 T cells in brain tissue" --output nl_results.csv --format csv
 ```
 
 ## Quick Start (Python)
@@ -40,17 +40,15 @@ malva_client search "CD4 T cells in brain tissue"
 ```python
 from malva_client import MalvaClient
 
-client = MalvaClient("https://malva.mdc-berlin.de", "YOUR_API_TOKEN")
+client = MalvaClient()
 
-# Search for genes, sequences, or natural language queries
+# Search for a gene and inspect aggregate expression rows
 results = client.search("CD3D")
-print(results)
+print(results.df.head())
 
-# Search for sequences
-results = client.search("ATCGATCGATCGCCACATGGACTTGAC")
-
-# Natural language queries
-results = client.search("cells expressing markers of neurodegeneration")
+# Search a DNA sequence of at least 24 nt
+sequence_results = client.search_sequences("ATCGATCGATCGATCGATCGATCG")
+print(sequence_results.df.head())
 ```
 
 ### Per-cell matrices
@@ -60,18 +58,22 @@ results = client.search("cells expressing markers of neurodegeneration")
 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])
+cells = client.retrieve_cells(result, include_sample_metadata=False)
+sample_id = int(cells.cells.iloc[0]["sample_id"])
+
+# Inspect cells from one real encoded sample ID
+sample_cells = client.retrieve_cells(result, sample_ids=[sample_id], include_sample_metadata=True)
+cell_ids = sample_cells.get_cell_ids()
+cell_df = sample_cells.to_dataframe(include_sample_metadata=True)
+print(cell_ids.head())
+print(cell_df.head())
+
+# Fetch all cells for that sample once from metadata for denominator analyses
+all_cells = client.get_cells_by_metadata(sample_ids=[sample_id])
+print(all_cells.head())
+
+# Full-database retrieval is also available; it queues a server-side export.
+# all_cells = client.get_cells_by_metadata(include_all_database_cells=True)
 ```
 
 ### Working with Results
@@ -79,10 +81,12 @@ value_cells = client.retrieve_cells(value_result, sample_ids=[123456])
 ```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')
+by_cell_type = results.aggregate_by('cell_type', agg_func='mean')
+print(filtered.df.head())
+print(by_cell_type.head())
 ```
 
 See the [tutorials](https://malva-client.readthedocs.io/en/latest/tutorials.html) for coverage analysis, dataset discovery, cell-level searches, and more.

{malva_client-0.3.2 → malva_client-0.3.4}/malva_client/__init__.py

@@ -6,7 +6,7 @@ try:
     from importlib.metadata import version as _get_version
     __version__ = _get_version("malva_client")
 except Exception:
-    __version__ = "0.3.2"
+    __version__ = "0.3.4"
 __author__ = "Malva Team"
 __email__ = "hello@malva.bio"