Repository navigation
Convert: pycistopic CistopicObject pickles #28
Description
Constraints
- A
CistopicObjectis a Python pickle ofpycisTopic.cistopic_class.CistopicObject. Unpickling needs pycistopic installed (and its scipy/pandas stack) and executes arbitrary code from the file. - Put it behind an optional extra (
pyadata-cli[pycistopic]), import lazily with a clear error when missing, require an explicit--from pycistopic, and document the security caveat. - Alternative to evaluate: run the unpickling in a subprocess via
uv run --with pycisTopicso the core install stays clean and heavy deps never land in the main environment.
Mapping
| CistopicObject | AnnData |
|---|---|
fragment_matrix (scipy sparse, regions × cells) |
X as cells × regions CSR |
binary_matrix |
layers["binary"] |
cell_names, cell_data |
obs_names, obs |
region_names, region_data |
var_names, var |
selected_model.cell_topic |
obsm["X_topic"] |
selected_model.topic_region |
varm["topic_region"] |
selected_model metrics / parameters |
uns["pycistopic"]["model"] |
projections |
obsm["X_<name>"] |
project, path_to_fragments |
uns["pycistopic"] |
Plan
Unpickle → write through the elements.write helpers. This path is necessarily in memory (the pickle is); document that clearly.
Tests
Fixture pickled in a uv run --with pycisTopic subprocess under the integration marker; check shapes, names and topic matrices.
Activity
adata convertto and from h5ad/zarr #20Merge pull request #67 from cellgeni/feat/convert-cistopic
Claptar commentedon Oct 21, 2026
Done in #67, released in 0.14.0.
adata convert cistopic_obj.pkl -o atac.h5adreads a CistopicObject (fragment and binary matrices, cell and region data, the selected model's topics, projections, and the rest inuns["pycistopic"]) and a CistopicImputedFeatures, without pycisTopic: an allowlisted unpickler refuses any global such an object never holds, so nothing in the file runs. pandas and scipy come withpip install 'pyadata-cli[pickle]'; the Docker image has them. Checked against GEO GSE292438's pickle (pycisTopic's pandas 1.5), converted under pandas 2.2 and 3 in CI.