MOSNA GUI

A graphical interface for MOSNA and Tysserand — spatial network construction and analysis tools developed by PancaldiLAB.

---

Table of contents

• Quick start
  • Linux / macOS
  • Windows
• Launching the app
• Requirements
• Tool overview
  • Architecture
  • Workflow
  • Input data format
  • Step 0 — Project setup
  • Step 1 — Tysserand spatial networks
  • Step 2 — Assortativity
  • Step 3 — Niche Analysis
• CLI usage
• Configuration reference

---

Quick start

Linux / macOS

Requirement: Miniconda or Anaconda must be installed and available in your PATH.

git clone <repo-url> MOSNA_GUI
cd MOSNA_GUI
bash setup.sh

Options:

Flag	Effect
--no-shortcut	Skip desktop launcher creation
--dev	Install mosna-package in editable mode (pip install -e)

The script will:

1. Create a mosna-GUI conda environment (Python 3.10)
2. Install all scientific dependencies via conda-forge
3. Install mosna-package into the environment
4. Generate MosnaGUI.sh and a Desktop shortcut

Windows

Requirement: No pre-requisite needed — Miniconda is downloaded automatically if absent.

1. Download or clone this repository
2. Double-click setup_windows.bat

The installer will:

1. Detect or download/install Miniconda silently
2. Create a mosna-GUI conda environment (Python 3.10)
3. Install all dependencies
4. Install mosna-package
5. Generate MosnaGUI.bat and a Desktop shortcut

---

Launching the app

Platform	Command
Linux / macOS	bash MosnaGUI.sh or double-click the Desktop shortcut
Windows	Double-click MosnaGUI.bat or the Desktop shortcut
Any (manual)	conda activate mosna-GUI && python GUI_MOSNA.py

---

Requirements

Dependency	Version
Python	3.10
PySide6	≥ 6.5
scanpy	≥ 1.9
scipy	1.13
pandas	≥ 2.0
mosna	from mosna-package/

Full list: requirements.txt

---

Tool overview

Architecture

MOSNA_GUI/
├── GUI_MOSNA.py          ← Main GUI entry point
├── package/
│   ├── tysserand_network.py   ← Step 1 runner
│   ├── assortativity.py       ← Step 2 runner
│   ├── niche_analysis.py      ← Step 3 runner
│   ├── core/                  ← Analysis cores
│   ├── utils/                 ← Shared utilities
│   └── style.qss              ← Qt stylesheet
├── CONFIG/
│   └── configuration.yaml.example   ← Config template
├── mosna-package/         ← MOSNA Python package (unchanged)
├── setup.sh               ← Linux/macOS installer
└── setup_windows.bat      ← Windows installer

Workflow

[Step 0]  Set working directory + data paths
    ↓
[Step 1]  Tysserand — Build spatial networks from cell coordinates
    ↓
[Step 2]  Assortativity — Compute mixing statistics per network
    ↓
[Step 3]  Niche Analysis — Cluster niches from aggregated neighborhoods

Input data format

Your input files must be CSV or Parquet tables following this structure:

CellID	patient	sample	X_position	Y_position	Phenotype
c001	pt-01	s1	120.3	84.7	CD8_T
…	…	…	…	…	…

File naming convention expected by the tool:

nodes_patient-01_sample-s1.parquet
nodes_patient-02_sample-s1.parquet

---

Step 0 — Project setup

Parameter	Description
Nodes directory	Folder containing your spatial cell tables
Network directory	Folder with pre-built edges/nodes (default: auto-generated by Step 1)
Patient column name	Column used as the first grouping level (e.g. patient)
Sample column name	Optional second grouping level (e.g. sample)
Extension	File format: csv, parquet, or tsv

---

Step 1 — Tysserand spatial networks

Parameter	Description
X / Y coordinates column	Spatial position columns
Phenotype column	Cell type or cluster column
Edges method	delaunay (triangulation) or knn (k-nearest neighbours)
Min neighbors	Minimum neighbours for KNN
CPU	Cores for parallel processing

---

Step 2 — Assortativity

Parameter	Description
Phenotype column	Column defining cell types
Index	Cell index column (index = DataFrame index)
Number of shuffle	Randomizations to build the null distribution
Randomization diagnostic	Estimate time cost for your shuffle count

---

Step 3 — Niche Analysis (NAS)

Parameter	Description
Saving directory	Output subfolder name
Processing method	Aggregated nodes or Per sample
Niches method	NAS (SCAN-IT is work in progress)
Phenotype column	Cell type column
Column to aggregate	Columns used in the aggregated network
X / Y coordinates for niches	Spatial columns to rebuild coloured networks
CPU	Cores for parallel processing

Clustering parameters:

Parameter	Description
order	Neighborhood order (1 = direct neighbors)
stat_funcs	Aggregation functions: np.mean, np.std, …
clusterer_type	gmm, leiden, hdbscan, spectral, ecg
metric	Distance metric: euclidean, manhattan, cosine
normalize	Feature normalization: total, niche, obs, clr, all
reducer_type	Dimensionality reduction: umap
n_neighbors	Neighbors for graph/UMAP construction
min_dist	UMAP tightness (smaller = more compact)
dim_clust	Reduced dimensions used for clustering
n_clusters	Number of clusters (gmm, spectral)
resolution	Leiden resolution (higher = more clusters)
min_cluster_size	HDBSCAN minimum cluster size

---

CLI usage

conda activate mosna-GUI
cd /path/to/MOSNA_GUI

python -m package.tysserand_network \
    --file CONFIG/configuration.yaml \
    --working_dir /path/to/output/

python -m package.assortativity \
    --file CONFIG/configuration.yaml \
    --working_dir /path/to/output/

python -m package.niche_analysis \
    --file CONFIG/configuration.yaml \
    --working_dir /path/to/output/

---

Configuration reference

Copy CONFIG/configuration.yaml.example to CONFIG/configuration.yaml and fill in your paths. The configuration.yaml file is git-ignored (it contains absolute paths specific to your machine).