How kojix2/unclone works
Purpose and executable entry point
UnClone is a command-line cancer clonal-analysis tool: a near-parity PyClone-VI-style variational inference mode plus experimental PhyClone-style phylogenetic sampling and trace post-processing. The Crystal executable starts at src/main.cr, delegates CLI orchestration through src/unclone/cli.cr, and is built as bin/unclone by Makefile.
CLI orchestration and mode dispatch
The Crystal layer owns argument parsing, validation, deterministic seed/control configuration, file paths, and user-facing errors. It dispatches vi to the VI kernel path and phy run/map/consensus/topology-report to phylogenetic operations.
• src/unclone/cli.cr
• src/unclone/run.cr
• src/unclone/config.cr
Input normalization and result boundaries
TSV mutation/sample observations enter Crystal-side parsing and sanitization, where required PyClone-compatible count/copy-number fields and optional purity/error values are validated and normalized. Crystal domain/result objects bridge parsed data to inference and serialize TSV or JSON/JSONL outputs; this is the principal boundary between filesystem formats and numerical/runtime kernels.
• src/unclone/input.cr
• src/unclone/sanitize.cr
• src/unclone/output.cr
Rust kernel FFI boundary
Crystal invokes a Rust static/native kernel through bindings and a C ABI. This isolates memory layout, ownership, error/result conversion, and Rust parallel execution from the CLI runtime. The public native interface is represented by the C header and Rust entry points.
• src/unclone/ffi.cr
• rust-kernel/include/pcv_kernel.h
• rust-kernel/src/c_api/entrypoints.rs
VI inference pipeline
VI transforms normalized observations into kernel-ready tensors, preprocesses likelihood inputs, then optimizes cluster assignments, mixture weights, and cellular-prevalence grid parameters across restarts. It supports binomial/beta-binomial likelihoods, ELBO-based best-restart selection, optional profiling/debug initialization, and Rayon-controlled kernel threads. Final cluster IDs/results return to Crystal for TSV generation.
• src/unclone/vi_kernel.cr
• rust-kernel/src/core/preprocess.rs
• rust-kernel/src/core/inference.rs
Numerical core and parallel runtime
The Rust core centralizes typed inference inputs/results, likelihood evaluation, and numerical primitives used by VI. Rust/Cargo is the compute runtime; Rayon is the material parallelism mechanism indicated by the kernel design, while Crystal can separately control restart-level orchestration.
• rust-kernel/src/core/types.rs
• rust-kernel/src/core/likelihood.rs
• rust-kernel/src/core/math.rs
Phylogenetic sampling and trace workflow
Phy mode is a separate Rust compatibility implementation rather than reuse of the VI engine. phy run builds tree/data models and performs MCMC/SMC-style proposals and sampling, emitting JSONL traces. Crystal then supports MAP, consensus/clade reconstruction, and topology-support summaries over those traces. Optional cluster TSV metadata informs loss-prior behavior.
• src/unclone/phyclone.cr
• src/unclone/phyclone_kernel.cr
• rust-kernel/src/phyclone/compat/smc.rs
Build, compatibility, and research artifacts
Builds combine Crystal with Cargo and expose CPU-target choices for portable versus AVX2/FMA-oriented releases. CI is GitHub Actions. The repository also contains a reproducible benchmark/paper pipeline that runs measurements and generates figures, distinct from the production CLI.
• Makefile
• .github/workflows/build.yml
• paper/scripts/benchmark.py
Main entry points: cli.cr CLI dispatch · phyclone.cr Phy commands · sanitize.cr Observation sanitization · ffi.cr Native FFI bindings
Components 20
Crystal CLI
User-facing orchestration and format boundary.
- Executable entry
src/main.cr - CLI dispatch · Routes VI and phy commands after validation.
src/unclone/cli.cr - Run controls · Seed, paths, and execution controls.
src/unclone/run.cr - Mode configuration
src/unclone/config.cr - Input normalization · Validates and normalizes mutation observations.
src/unclone/input.cr - Observation sanitization
src/unclone/sanitize.cr - Result serialization
src/unclone/output.cr - Native FFI bindings · Owns ABI conversion and native error handling.
src/unclone/ffi.cr
VI kernel
Rust variational-inference pipeline.
- Kernel C ABI
rust-kernel/include/pcv_kernel.h - Rust entrypoints
rust-kernel/src/c_api/entrypoints.rs - VI tensor adapter · Converts normalized observations to kernel inputs.
src/unclone/vi_kernel.cr - Likelihood preprocessing
rust-kernel/src/core/preprocess.rs - VI optimization · Optimizes assignments, weights, and prevalence grids across restarts.
rust-kernel/src/core/inference.rs - Numerical core · Typed inputs, likelihoods, and numerical primitives; uses Rayon parallelism.
rust-kernel/src/core/likelihood.rs
Phy workflow
Separate sampling and trace-analysis path.
- Phy commands · Runs sampling and post-processes JSONL traces.
src/unclone/phyclone.cr - Phy kernel bridge
src/unclone/phyclone_kernel.cr - Phy sampling · Builds phylogenetic models, proposes trees, and emits traces.
rust-kernel/src/phyclone/compat/smc.rs
Build & research
- Production build · Combines Crystal and Cargo into bin/unclone with CPU-target variants.
Makefile - Build CI
.github/workflows/build.yml - Benchmark pipeline · Runs reproducible measurements and figure generation.
paper/scripts/benchmark.py
Connections 21
- Executable entry → CLI dispatch: starts
- CLI dispatch → Run controls: configures
- CLI dispatch → Mode configuration: parses mode options
- CLI dispatch → Input normalization: reads TSV
- Input normalization → Observation sanitization: validates fields
- Observation sanitization → VI tensor adapter: normalized observations
- VI tensor adapter → Native FFI bindings: kernel request
- Native FFI bindings → Kernel C ABI: C ABI
- Kernel C ABI → Rust entrypoints: implemented by
- Rust entrypoints → Likelihood preprocessing: VI inputs
- Likelihood preprocessing → VI optimization: prepared likelihood data
- VI optimization → Numerical core: likelihood evaluation
- Native FFI bindings → Result serialization: cluster results
- CLI dispatch → Phy commands: phy run / map / consensus
- Observation sanitization → Phy commands: observations and metadata
- Phy commands → Phy kernel bridge: sampling request
- Phy kernel bridge → Phy sampling: native execution
- Phy commands → Result serialization: trace reports
- Production build → Executable entry: builds bin/unclone
- Build CI → Production build: runs
- Benchmark pipeline → Production build: uses executable