Buscar

About

Buscar (Bioactive Unbiased Single-cell Compound Assessment and Ranking) is an open-source Python package for reproducible perturbation hit calling in high-content screening that operates directly on distributions of single-cell image-based profiles. The name is also a play on the Spanish and Portuguese verb "buscar," meaning "to search" or "to seek," reflecting the framework's core goal of identifying biologically active perturbations. Traditional high-content screening approaches rely on population-based aggregated profiles to evaluate compound-induced morphological activity, which obscures the biological heterogeneity present across individual cells within a treatment group. Buscar addresses this limitation by operating directly on single-cell profiles, enabling a more nuanced and interpretable assessment of perturbation activity.

Buscar requires two reference populations defining distinct morphology states, for example diseased and healthy cells. It uses these populations to separate the high-dimensional feature space into two complementary, mutually exclusive signatures: an on-morphology signature (features that differ significantly between the reference and target states) and an off-morphology signature (features that remain unchanged). This separation enables the independent tracking of perturbation efficacy and specificity for every perturbation in a given screen. Buscar is designed to be compatible with the Cytomining Ecosystem, ensuring seamless interoperability with tools like Pycytominer, coSMicQC, and CytoTable. All analysis conducted in this project can be found in the Buscar-benchmark-analysis repository.

Implementation

Figure: Figure: Schematic overview of the Buscar framework, highlighting its two main modules and their roles in perturbation hit calling.

Installation

Install from PyPI

Install Buscar with pip:

pip install buscar

Or add it to a uv-managed project:

uv add buscar

Install from source

To install the current repository version:

uv add "buscar @ git+https://github.com/WayScience/buscar.git"

Development

Buscar uses uv for environment and package management.

1. Clone the repository

git clone https://github.com/WayScience/buscar.git
cd buscar

2. Create the development environment

uv sync --frozen --group dev

3. Run tests

uv run --frozen pytest

4. Run tests with coverage

uv run --frozen pytest --cov=buscar --cov-report=term-missing --cov-report=xml --cov-report=html

5. Run linting and formatting checks

pre-commit run --all-files

See CONTRIBUTING.md for contribution guidelines and the full local development checklist.

Build and validate

Build the source distribution and wheel:

uv build

Validate the package metadata:

uv run --frozen twine check dist/*

Install the built wheel in an isolated environment to verify the package import:

uv run --isolated --no-project --with ./dist/buscar-*.whl -- \
  python -c "import buscar; print(buscar.__name__, buscar.__version__)"

Package metadata and dependencies are defined in pyproject.toml; the uv lockfile is used for reproducible local and CI development environments.

Notes

Parallel Processing Issue: The on-Buscar score utilizes Earth Mover's Distance (EMD) via the Python Optimal Transport (POT) library. There is a known upstream issue where multithreading significantly degrades performance, causing calculations to be extremely slow.

Recommendation: We strongly recommend running on-Buscar scoring in single-threaded mode until this is resolved in the core POT library.