Metadata-Version: 2.4
Name: cytodataframe
Version: 0.3.1
Summary: An in-memory data analysis format for single-cell profiles alongside their corresponding images and segmentation masks.
Author: Way Science Community
License-Expression: BSD-3-Clause
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: imagecodecs<2027,>=2024.9.22
Requires-Dist: imageio<3,>=2.37
Requires-Dist: ipython<10,>=8.12.3
Requires-Dist: ipyvolume<0.7,>=0.6.3
Requires-Dist: ipywidgets<9,>=8.1.7
Requires-Dist: matplotlib<4,>=3.9.3
Requires-Dist: nest-asyncio<2,>=1.6
Requires-Dist: ome-arrow<0.0.9,>=0.0.3
Requires-Dist: opencv-python<5,>=4.10.0.84
Requires-Dist: pandas<4,>=2.2.2
Requires-Dist: pyarrow>=16
Requires-Dist: pyvista>=0.46.4
Requires-Dist: pywavelets>1.4.1
Requires-Dist: scikit-image>0.19.3
Requires-Dist: trame>=3.12
Requires-Dist: trame-vtk>=2.10
Requires-Dist: trame-vuetify>=3.1
Dynamic: license-file

<img height="200" src="https://raw.githubusercontent.com/cytomining/cytodataframe/main/logo/with-text-for-light-bg.png?raw=true">

# CytoDataFrame

[![PyPI - Version](https://img.shields.io/pypi/v/cytodataframe)](https://pypi.org/project/CytoDataFrame/)
[![Build Status](https://github.com/cytomining/CytoDataFrame/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/cytomining/CytoDataFrame/actions/workflows/run-tests.yml?query=branch%3Amain)
![Coverage Status](https://raw.githubusercontent.com/cytomining/CytoDataFrame/main/media/coverage-badge.svg)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Software DOI badge](https://zenodo.org/badge/DOI/10.5281/zenodo.14797074.svg)](https://doi.org/10.5281/zenodo.14797074)

![](https://raw.githubusercontent.com/cytomining/coSMicQC/refs/heads/main/docs/presentations/2024-09-18-SBI2-Conference/images/cosmicqc-example-cytodataframe.png)
_CytoDataFrame extends Pandas functionality to help display single-cell profile data alongside related images._

CytoDataFrame is an advanced in-memory data analysis format designed for single-cell profiling, integrating not only the data profiles but also their corresponding microscopy images and segmentation masks.
Traditional single-cell profiling often excludes the associated images from analysis, limiting the scope of research.
CytoDataFrame bridges this gap, offering a purpose-built solution for comprehensive analysis that incorporates both the data and images, empowering more detailed and visual insights in single-cell research.

CytoDataFrame is best suited for work within Jupyter notebooks.
With CytoDataFrame you can:

- View image objects alongside their feature data using a Pandas DataFrame-like interface.
- Highlight image objects using mask or outline files to understand their segmentation.
- Adjust image displays on-the-fly using interactive slider widgets.
- Automatically detect 3D image volumes and render interactive [trame](https://github.com/Kitware/trame) views in notebooks when 3D dependencies are installed (with graceful fallback otherwise).

For 3D notebook display behavior:

- 3D-aware rendering is enabled by default (`display_options={"auto_trame_for_3d": True}`).
- Disable automatic trame switching with `display_options={"auto_trame_for_3d": False}`.
- Force trame layout regardless of auto-detection with `display_options={"view": "trame"}`.

For row display in notebook/widget tables:

- CytoDataFrame respects pandas display settings (`display.max_rows`, `display.min_rows`).
- When the table is larger than `display.max_rows`, the widget table inserts a midpoint ellipsis row (`…`) to indicate omitted rows.
- You can control truncation behavior by changing pandas display options before rendering.

📓 ___Want to see CytoDataFrame in action?___ Check out our [example notebook](docs/src/examples/cytodataframe_at_a_glance.ipynb) for a quick tour of its key features.

> ✨ CytoDataFrame development began within **[coSMicQC](https://github.com/cytomining/coSMicQC)** - a single-cell profile quality control package.
> Please check out our work there as well!

## Installation

Install CytoDataFrame from source using the following:

```shell
# install from pypi
pip install cytodataframe

# or install directly from source
pip install git+https://github.com/cytomining/CytoDataFrame.git
```

## Contributing, Development, and Testing

Please see our [contributing](https://cytomining.github.io/CytoDataFrame/main/contributing) documentation for more details on contributions, development, and testing.

## References

- [coSMicQC](https://github.com/cytomining/coSMicQC)
- [pycytominer](https://github.com/cytomining/pycytominer)
- [CellProfiler](https://github.com/CellProfiler/CellProfiler)
- [CytoTable](https://github.com/cytomining/CytoTable)
