# obrien-lab-psu/ncledetector architecture

> Architecture diagram of the GitHub repository obrien-lab-psu/ncledetector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/obrien-lab-psu/ncledetector
- Repository: https://github.com/obrien-lab-psu/ncledetector

## Overview

NCLEdetector is a Python toolkit for analyzing non-covalent lasso entanglements in protein structures and folding simulations, then comparing results with experiments and modeling populations. The principal workflow runs structure or trajectory analysis, derives entanglement and order-parameter features, and supports downstream clustering, MSM, and statistical analysis. The graph includes the documented resolution-conversion capability and the Jwalk components used for SASD calculations. Relationships are limited to README statements and SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`NCLEdetector/order_params.py`](https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/order_params.py) (Order parameters), [`scripts/run_nativeNCLE.py`](https://github.com/obrien-lab-psu/ncledetector/blob/main/scripts/run_nativeNCLE.py) (Native NCLE), [`scripts/run_compare_sim2exp.py`](https://github.com/obrien-lab-psu/ncledetector/blob/main/scripts/run_compare_sim2exp.py) (Sim-experiment workflow), [`NCLEdetector/_logging.py`](https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/_logging.py) (Logging helper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Workflow entrypoints"]
  node_native_cli["Native NCLE<br/>[run_nativeNCLE.py]"]
  node_trajectory_cli["Trajectory workflow"]
  node_compare_cli["Sim-experiment workflow"]
  node_msm_cli["MSM workflow<br/>[run_MSM.py]"]
  node_population_cli["Population workflow"]
end

subgraph group_analysis["Entanglement analysis"]
  node_gaussian["Gaussian entanglement"]
  node_features["Entanglement features"]
  node_clustering["Clustering and MSM<br/>[clustering.py]"]
  node_comparison["Experimental comparison<br/>[compare_sim2exp.py]"]
end

subgraph group_trajectory["Trajectory analysis"]
  node_order_params["Order parameters<br/>[order_params.py]"]
  node_jwalk_grid["Jwalk grid<br/>[GridTools.py]"]
  node_jwalk_pdb["Jwalk structure tools<br/>[PDBTools.py]"]
  node_jwalk_surface["Jwalk surface tools<br/>[SurfaceTools.py]"]
  node_jwalk_sasd["Jwalk SASD<br/>[SASDTools.py]"]
end

subgraph group_support["Modeling and support"]
  node_resolution["Resolution conversion"]
  node_statistics["Statistical modeling<br/>[statistics.py]"]
  node_logging["Logging helper<br/>[_logging.py]"]
end

node_researcher(("Researcher"))
node_results["Analysis outputs"]

node_researcher -->|"runs"| node_native_cli
node_researcher -->|"runs"| node_trajectory_cli
node_researcher -->|"runs"| node_compare_cli
node_researcher -->|"runs"| node_msm_cli
node_researcher -->|"runs"| node_population_cli
node_native_cli -->|"calculates"| node_gaussian
node_native_cli -->|"uses"| node_clustering
node_native_cli -->|"generates"| node_features
node_trajectory_cli -->|"calculates"| node_order_params
node_order_params -->|"uses"| node_jwalk_grid
node_order_params -->|"uses"| node_jwalk_pdb
node_order_params -->|"uses"| node_jwalk_surface
node_order_params -->|"uses"| node_jwalk_sasd
node_compare_cli -->|"compares"| node_comparison
node_compare_cli -->|"uses"| node_gaussian
node_compare_cli -->|"uses"| node_clustering
node_msm_cli -->|"builds"| node_clustering
node_population_cli -->|"models"| node_statistics
node_population_cli -->|"writes"| node_results
node_native_cli -->|"writes"| node_results
node_trajectory_cli -->|"writes"| node_results
node_compare_cli -->|"writes"| node_results
node_msm_cli -->|"writes"| node_results
node_resolution -->|"converts structures"| node_results
node_statistics -->|"models"| node_results
node_gaussian -->|"configures"| node_logging
node_clustering -->|"configures"| node_logging
node_comparison -->|"configures"| node_logging
node_order_params -->|"configures"| node_logging
node_statistics -->|"configures"| node_logging

click node_native_cli "https://github.com/obrien-lab-psu/ncledetector/blob/main/scripts/run_nativeNCLE.py"
click node_trajectory_cli "https://github.com/obrien-lab-psu/ncledetector/blob/main/scripts/run_OP_on_simulation_traj.py"
click node_compare_cli "https://github.com/obrien-lab-psu/ncledetector/blob/main/scripts/run_compare_sim2exp.py"
click node_msm_cli "https://github.com/obrien-lab-psu/ncledetector/blob/main/scripts/run_MSM.py"
click node_population_cli "https://github.com/obrien-lab-psu/ncledetector/blob/main/scripts/run_population_modeling.py"
click node_gaussian "https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/gaussian_entanglement.py"
click node_features "https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/entanglement_features.py"
click node_clustering "https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/clustering.py"
click node_order_params "https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/order_params.py"
click node_jwalk_grid "https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/Jwalk/GridTools.py"
click node_jwalk_pdb "https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/Jwalk/PDBTools.py"
click node_jwalk_surface "https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/Jwalk/SurfaceTools.py"
click node_jwalk_sasd "https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/Jwalk/SASDTools.py"
click node_comparison "https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/compare_sim2exp.py"
click node_resolution "https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/change_resolution.py"
click node_statistics "https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/statistics.py"
click node_logging "https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/_logging.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_native_cli,node_trajectory_cli,node_compare_cli,node_msm_cli,node_population_cli toneBlue
class node_gaussian,node_features,node_clustering,node_comparison toneAmber
class node_order_params,node_jwalk_grid,node_jwalk_pdb,node_jwalk_surface,node_jwalk_sasd toneMint
class node_resolution,node_statistics,node_logging toneRose
class node_researcher,node_results toneIndigo
```

## Components

### Workflow entrypoints

- [Native NCLE](https://github.com/obrien-lab-psu/ncledetector/blob/main/scripts/run_nativeNCLE.py): `scripts/run_nativeNCLE.py`
- [Trajectory workflow](https://github.com/obrien-lab-psu/ncledetector/blob/main/scripts/run_OP_on_simulation_traj.py): `scripts/run_OP_on_simulation_traj.py`
- [Sim-experiment workflow](https://github.com/obrien-lab-psu/ncledetector/blob/main/scripts/run_compare_sim2exp.py): `scripts/run_compare_sim2exp.py`
- [MSM workflow](https://github.com/obrien-lab-psu/ncledetector/blob/main/scripts/run_MSM.py): `scripts/run_MSM.py`
- [Population workflow](https://github.com/obrien-lab-psu/ncledetector/blob/main/scripts/run_population_modeling.py): `scripts/run_population_modeling.py`

### Entanglement analysis

- [Gaussian entanglement](https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/gaussian_entanglement.py): `NCLEdetector/gaussian_entanglement.py`
- [Entanglement features](https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/entanglement_features.py): `NCLEdetector/entanglement_features.py`
- [Clustering and MSM](https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/clustering.py): `NCLEdetector/clustering.py`
- [Experimental comparison](https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/compare_sim2exp.py): `NCLEdetector/compare_sim2exp.py`

### Trajectory analysis

- [Order parameters](https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/order_params.py): `NCLEdetector/order_params.py`
- [Jwalk grid](https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/Jwalk/GridTools.py): `NCLEdetector/Jwalk/GridTools.py`
- [Jwalk structure tools](https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/Jwalk/PDBTools.py): `NCLEdetector/Jwalk/PDBTools.py`
- [Jwalk surface tools](https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/Jwalk/SurfaceTools.py): `NCLEdetector/Jwalk/SurfaceTools.py`
- [Jwalk SASD](https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/Jwalk/SASDTools.py): `NCLEdetector/Jwalk/SASDTools.py`

### Modeling and support

- [Resolution conversion](https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/change_resolution.py): `NCLEdetector/change_resolution.py`
- [Statistical modeling](https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/statistics.py): `NCLEdetector/statistics.py`
- [Logging helper](https://github.com/obrien-lab-psu/ncledetector/blob/main/NCLEdetector/_logging.py): `NCLEdetector/_logging.py`

### Other components

- **Researcher**
- **Analysis outputs**

## Connections

- Researcher → Native NCLE: runs
- Researcher → Trajectory workflow: runs
- Researcher → Sim-experiment workflow: runs
- Researcher → MSM workflow: runs
- Researcher → Population workflow: runs
- Native NCLE → Gaussian entanglement: calculates (evidence: `scripts/run_nativeNCLE.py`)
- Native NCLE → Clustering and MSM: uses (evidence: `scripts/run_nativeNCLE.py`)
- Native NCLE → Entanglement features: generates (evidence: `scripts/run_nativeNCLE.py`)
- Trajectory workflow → Order parameters: calculates (evidence: `scripts/run_OP_on_simulation_traj.py`)
- Order parameters → Jwalk grid: uses (evidence: `NCLEdetector/order_params.py`)
- Order parameters → Jwalk structure tools: uses (evidence: `NCLEdetector/order_params.py`)
- Order parameters → Jwalk surface tools: uses (evidence: `NCLEdetector/order_params.py`)
- Order parameters → Jwalk SASD: uses (evidence: `NCLEdetector/order_params.py`)
- Sim-experiment workflow → Experimental comparison: compares (evidence: `scripts/run_compare_sim2exp.py`)
- Sim-experiment workflow → Gaussian entanglement: uses (evidence: `scripts/run_compare_sim2exp.py`)
- Sim-experiment workflow → Clustering and MSM: uses (evidence: `scripts/run_compare_sim2exp.py`)
- MSM workflow → Clustering and MSM: builds (evidence: `scripts/run_MSM.py`)
- Population workflow → Statistical modeling: models (evidence: `scripts/run_population_modeling.py`)
- Population workflow → Analysis outputs: writes
- Native NCLE → Analysis outputs: writes
- Trajectory workflow → Analysis outputs: writes
- Sim-experiment workflow → Analysis outputs: writes
- MSM workflow → Analysis outputs: writes
- Resolution conversion → Analysis outputs: converts structures
- Statistical modeling → Analysis outputs: models
- Gaussian entanglement → Logging helper: configures (evidence: `NCLEdetector/gaussian_entanglement.py`)
- Clustering and MSM → Logging helper: configures (evidence: `NCLEdetector/clustering.py`)
- Experimental comparison → Logging helper: configures (evidence: `NCLEdetector/compare_sim2exp.py`)
- Order parameters → Logging helper: configures (evidence: `NCLEdetector/order_params.py`)
- Statistical modeling → Logging helper: configures (evidence: `NCLEdetector/statistics.py`)