# kjaqaman/smi-fsm architecture

> Architecture diagram of the GitHub repository kjaqaman/smi-fsm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kjaqaman/smi-fsm
- Repository: https://github.com/kjaqaman/smi-fsm

## Overview

##### Project type and purpose
- The README describes its goals: extracting dynamic properties of tracks and integrating those measurements in downstream analysis.

##### File structure
- Top-level:
- Code/       – all MATLAB routines and helper libraries
- HowToSMIFSM.pdf – user guide
- LICENSE, README.md
- Within Code/:
- .m files – core algorithms (tracking, moment calculations, diffusion analysis, plotting)
- extern/    – third-party MATLAB helpers
- mex/       – compiled MEX functions for performance (createDistanceMatrix)
- data files (.mat) – precomputed thresholds and constants
- testScriptforPackage.m – example end-to-end run script

##### README for additional insights
a) Single‐molecule tracking and property extraction
b) Actin speckle tracking and property extraction
- A final integration step correlates and statistically analyzes relationships.

1. Data Input
2. Preprocessing
- Image filtering (filterGauss1D, padarrayXT)
- Mask generation (getActinMask)
3. Tracking Modules
- Single‐Molecule Tracker
– convCoord2Img → getTrackSEL → getFsmTrackNum → calcTrackMoments
- Actin Speckle Tracker
– gridActinPropPerTimeInt → smactinClean → smactinMat
4. Feature Extraction
- Spatial/temporal metrics (basicTransientDiffusionAnalysis, trackDiffusionAnalysis1)
- Classification (classifyMaskGrid, stratifySmTrackletByBoxClass)
5. Statistical Analysis
- Gaussian fitting (fitHistWithGaussians)
- Comparative tests (multiCompareAnovaIndCellsMVRG, multiCompareIndCellsMVRG)
- Confidence intervals (positionConfidence*.mat)
6. Visualization & Reporting
- Plotting functions (plotTracksDiffAnalysis2D, plotBiphasicLines, notBoxPlot)
- Summary scripts (summarizeDiffAnRes, explainIndCellsMVRG)
7. Integration & Control
- testScriptforPackage.m or runSmactinAggMovExplain.m orchestrates end-to-end workflow
8. Performance Acceleration
- MEX library (createDistanceMatrix)
9. External Helpers
- extern/padcat, extern/sigstar

b. Relationships and data flow

c. Architectural patterns & design principles
- Functional decomposition: each stage encapsulates a distinct step in the pipeline
- Modular design: helper libraries (extern/), performance modules (mex/) separated from core code
- Script orchestration: a top-level script ties together modules in sequence

d. Key technologies & frameworks
- MATLAB (core language/runtime)
- MEX (for compute-intensive routines)
- Third-party MATLAB utilities (in extern/)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Input
    subgraph "Data Input"
        RI["Raw Two-Color Image Stacks"]:::io
    end

    %% Preprocessing
    subgraph "Preprocessing"
        FG["filterGauss1D.m"]:::core
        PA["padarrayXT.m"]:::core
        GMASK["getActinMask.m"]:::core
    end

    %% Tracking Modules
    subgraph "Tracking Modules"
        subgraph "Single-Molecule Tracker"
            CC2I["convCoord2Img.m"]:::core
            GTS["getTrackSEL.m"]:::core
            GFTN["getFsmTrackNum.m"]:::core
            CTM["calcTrackMoments.m"]:::core
        end
        subgraph "Actin Speckle Tracker"
            GAPTI["gridActinPropPerTimeInt.m"]:::core
            SMCLEAN["smactinClean.m"]:::core
            SMAT["smactinMat.m"]:::core
            SPP["smactinPropPerTimeInt.m"]:::core
        end
    end

    %% Feature Extraction
    subgraph "Feature Extraction"
        BTDA["basicTransientDiffusionAnalysisv1.m"]:::core
        TDA1["trackDiffusionAnalysis1.m"]:::core
        CMG["classifyMaskGrid.m"]:::core
        SSBBC["stratifySmTrackletByBoxClass.m"]:::core
    end

    %% Statistical Analysis
    subgraph "Statistical Analysis"
        FHWG["fitHistWithGaussians.m"]:::core
        MCAAIC["multiCompareAnovaIndCellsMVRG.m"]:::core
        MCIC["multiCompareIndCellsMVRG.m"]:::core
        PC1["positionConfidenceCI.mat"]:::core
        PC2["positionConfidenceDF.mat"]:::core
        PC3["positionConfidenceFC.mat"]:::core
    end

    %% Visualization & Reporting
    subgraph "Visualization & Reporting"
        PTDA2D["plotTracksDiffAnalysis2D.m"]:::io
        PBL["plotBiphasicLines.m"]:::io
        NBP["notBoxPlot.m"]:::io
        SDR["summarizeDiffAnRes.m"]:::io
        EIC["explainIndCellsMVRG.m"]:::io
    end

    %% Integration & Control
    subgraph "Integration & Control"
        TSP["testScriptforPackage.m"]:::core
        RSME["runSmactinAggMovExplain.m"]:::core
        SAM["smactinAggMov.m"]:::core
    end

    %% Performance Acceleration
    subgraph "Performance Acceleration (MEX)"
        CDM["createDistanceMatrix.*"]:::perf
    end

    %% External Helpers
    subgraph "External Helpers"
        PADCAT["padcat.m"]:::util
        SIGSTAR["sigstar.m"]:::util
    end

    %% Main Flow
    RI --> FG --> CC2I
    RI --> PA --> CC2I
    RI --> GMASK
    CC2I --> GTS --> GFTN --> CTM
    CTM --> BTDA --> FHWG --> PTDA2D
    GFTN --> GAPTI --> SMCLEAN --> SMAT --> SPP --> TDA1
    BTDA --> TDA1
    TDA1 --> CMG --> SSBBC --> MCAAIC
    MCAAIC --> MCIC --> PC1 --> PC2 --> PC3 --> SDR --> EIC

    %% Integration Control Arrows
    TSP --> RI
    TSP --> FG
    TSP --> CC2I
    TSP --> BTDA
    TSP --> FHWG
    TSP --> PTDA2D

    RSME --> RI
    RSME --> CTM
    RSME --> MCAAIC
    RSME --> EIC

    SAM --> RI
    SAM --> GAPTI
    SAM --> FHWG

    %% Performance Dotted Arrows
    CDM -.-> CC2I
    CDM -.-> CTM
    CDM -.-> BTDA

    %% External Helpers Arrows
    PADCAT --> PA
    PADCAT --> NBP
    SIGSTAR --> NBP

    %% Click Events
    click FG "https://github.com/kjaqaman/smi-fsm/blob/main/Code/filterGauss1D.m"
    click PA "https://github.com/kjaqaman/smi-fsm/blob/main/Code/padarrayXT.m"
    click GMASK "https://github.com/kjaqaman/smi-fsm/blob/main/Code/getActinMask.m"
    click CC2I "https://github.com/kjaqaman/smi-fsm/blob/main/Code/convCoord2Img.m"
    click GTS "https://github.com/kjaqaman/smi-fsm/blob/main/Code/getTrackSEL.m"
    click GFTN "https://github.com/kjaqaman/smi-fsm/blob/main/Code/getFsmTrackNum.m"
    click CTM "https://github.com/kjaqaman/smi-fsm/blob/main/Code/calcTrackMoments.m"
    click GAPTI "https://github.com/kjaqaman/smi-fsm/blob/main/Code/gridActinPropPerTimeInt.m"
    click SMCLEAN "https://github.com/kjaqaman/smi-fsm/blob/main/Code/smactinClean.m"
    click SMAT "https://github.com/kjaqaman/smi-fsm/blob/main/Code/smactinMat.m"
    click SPP "https://github.com/kjaqaman/smi-fsm/blob/main/Code/smactinPropPerTimeInt.m"
    click BTDA "https://github.com/kjaqaman/smi-fsm/blob/main/Code/basicTransientDiffusionAnalysisv1.m"
    click TDA1 "https://github.com/kjaqaman/smi-fsm/blob/main/Code/trackDiffusionAnalysis1.m"
    click CMG "https://github.com/kjaqaman/smi-fsm/blob/main/Code/classifyMaskGrid.m"
    click SSBBC "https://github.com/kjaqaman/smi-fsm/blob/main/Code/stratifySmTrackletByBoxClass.m"
    click FHWG "https://github.com/kjaqaman/smi-fsm/blob/main/Code/fitHistWithGaussians.m"
    click MCAAIC "https://github.com/kjaqaman/smi-fsm/blob/main/Code/multiCompareAnovaIndCellsMVRG.m"
    click MCIC "https://github.com/kjaqaman/smi-fsm/blob/main/Code/multiCompareIndCellsMVRG.m"
    click PC1 "https://github.com/kjaqaman/smi-fsm/blob/main/Code/positionConfidenceCI.mat"
    click PC2 "https://github.com/kjaqaman/smi-fsm/blob/main/Code/positionConfidenceDF.mat"
    click PC3 "https://github.com/kjaqaman/smi-fsm/blob/main/Code/positionConfidenceFC.mat"
    click PTDA2D "https://github.com/kjaqaman/smi-fsm/blob/main/Code/plotTracksDiffAnalysis2D.m"
    click PBL "https://github.com/kjaqaman/smi-fsm/blob/main/Code/plotBiphasicLines.m"
    click NBP "https://github.com/kjaqaman/smi-fsm/blob/main/Code/notBoxPlot.m"
    click SDR "https://github.com/kjaqaman/smi-fsm/blob/main/Code/summarizeDiffAnRes.m"
    click EIC "https://github.com/kjaqaman/smi-fsm/blob/main/Code/explainIndCellsMVRG.m"
    click TSP "https://github.com/kjaqaman/smi-fsm/blob/main/Code/testScriptforPackage.m"
    click RSME "https://github.com/kjaqaman/smi-fsm/blob/main/Code/runSmactinAggMovExplain.m"
    click SAM "https://github.com/kjaqaman/smi-fsm/blob/main/Code/smactinAggMov.m"
    click CDM "https://github.com/kjaqaman/smi-fsm/blob/main/Code/mex/createDistanceMatrix.*"
    click PADCAT "https://github.com/kjaqaman/smi-fsm/blob/main/Code/extern/padcat.m"
    click SIGSTAR "https://github.com/kjaqaman/smi-fsm/blob/main/Code/extern/sigstar.m"

    %% Styles
    classDef core fill:#a3c4f3,stroke:#333,stroke-width:1px
    classDef io fill:#b6f2a3,stroke:#333,stroke-width:1px
    classDef perf fill:#f2c98a,stroke:#333,stroke-width:1px
    classDef util fill:#d3d3d3,stroke:#333,stroke-width:1px
```
