example.py

"""
STPuppeteer — minimal end-to-end example

Run:
    python examples/example.py
"""

from STpuppeteer.simulation import SimulationConfig, SpotlessSimulator

# ── 1. Configure ──────────────────────────────────────────────────────────────
config = SimulationConfig(
    n_cells=200,
    n_celltype=3,
    celltype_proportion=[0.5, 0.3, 0.2],
    n_genes=500,
    n_markers=[100, 80, 60],           # marker genes per cell type
    leakage_by_celltype=[0.1, 0.15, 0.05],
    seed=42,
)

# ── 2. Run ─────────────────────────────────────────────────────────────────────
sim = SpotlessSimulator(config)
sim.run_full_simulation()

# ── 3. Inspect ─────────────────────────────────────────────────────────────────
print(sim.summary())

print("\nCell data (first 5 rows):")
print(sim.cell_gdf[["cell_id", "celltype", "nucleus_area", "cell_area", "scale"]].head())

print(f"\nCount matrix: {sim.count_array.shape}  "
      f"(total transcripts: {sim.count_array.sum():,})")

leaked = sim.trs_df["is_leaked"].mean()
print(f"Leaked transcripts: {leaked:.1%}")

# ── 4. Save ────────────────────────────────────────────────────────────────────
paths = sim.save_simple("example_output/", prefix="sim")
print(f"\nSaved to example_output/: {[p.name for p in paths.values()]}")

# Optional: SpatialData format (requires: pip install spatialdata)
# sim.save_spatialdata("example_output.zarr")

# Optional: 10x Xenium format
# sim.save_xenium("example_xenium/")