NAVAL-SEM v0.9

Quick Start

1 · Launch the server

# From the extracted release folder
uvicorn app.main:app --reload --port 8000
# Or use the bundled launcher
python launcher.py

2 · POST your first model

All analysis endpoints accept multipart/form-data with a file upload (CSV / XLSX / SAV) and a model string in lavaan syntax.

curl -X POST http://localhost:8000/run \
  -F "file=@data.csv" \
  -F "model=Y =~ y1 + y2 + y3
X =~ x1 + x2 + x3
Y ~ X" \
  -F "algorithm=pls" \
  -F "bootstrap_n=500"

3 · Stream live logs (SSE)

const runId = crypto.randomUUID();
const es = new EventSource(`/logs/${runId}`);

es.onmessage = (e) => {
  const d = JSON.parse(e.data);
  if (d.done) { es.close(); return; }
  console.log(d.level, d.msg);
};

// Then POST /run with run_id in the form body
formData.append("run_id", runId);

Algorithms

All analysis endpoints that accept an algorithm parameter support three estimators:

lavaan Syntax

NAVAL-SEM parses a lavaan-compatible model string. Three operator types are supported:

Interaction terms

Use the * operator inside a structural path to specify moderation. The engine auto-creates the mean-centred product column.

# Standard moderation: X*M on outcome Y
Y  ~  X + M + X*M
X  =~ x1 + x2 + x3
M  =~ m1 + m2 + m3
Y  =~ y1 + y2 + y3

Auto reverse scoring

Prefix any indicator name with r (e.g. rx3) when the column x3 exists in the dataset but rx3 does not. The server applies (max + min) − value automatically before fitting.

SatisfactionLV =~ sat1 + sat2 + rsat3 + sat4
# rsat3 will be auto-reverse-scored from sat3

POST /run

Fit a full SEM model. Returns path coefficients, loadings, fit indices, validity metrics, and optionally bootstrap CIs. Generates a SHA-256 reproducibility fingerprint.

POST /bootstrap

Run standalone bootstrap without re-fitting the full model. Useful for extending an existing /run result with CIs post-hoc.

POST /indirect

Decompose indirect (mediation) effects for all variable pairs connected via paths of length ≥ 2. Returns bootstrap 95 % CIs and a total-effects matrix.

POST /predict

Predictive relevance suite: Stone-Geisser Q² (blindfolding), PLSpredict k-fold vs linear baseline, and CVPAT.

POST /cmb

Common Method Bias marker variable analysis (Lindell & Whitney 2001). Requires a marker variable theoretically unrelated to your constructs.

POST /mga

Multi-Group Analysis: per-group model fit, pairwise bootstrap path-difference CIs, and (for 2-group analyses) MICOM measurement invariance.

POST /moderation

Moderation analysis via the product-of-composites approach. Detects X*M interaction terms in the lavaan structural syntax and tests each one by comparing R² with vs. without the interaction term (Δ R², Cohen's f²) and computing bootstrap simple slopes at moderator = −1 SD, mean (0), +1 SD.

# Test whether trust (TR) moderates innovation (IN) → satisfaction (SA)
SA ~  IN + TR + IN*TR
IN =~ in1 + in2 + in3
TR =~ tr1 + tr2 + tr3
SA =~ sa1 + sa2 + sa3

POST /ipma

Importance-Performance Map Analysis (Ringle & Sarstedt 2016; Hair et al. 2022 Ch. 7). Computes for each predictor of a target latent variable: Importance = total effect (direct + all indirect paths) and Performance = mean composite score rescaled to 0–100.

POST /nca

Necessary Condition Analysis (Dul 2016, 2020). Tests whether each predictor is a necessary (not merely sufficient) condition for an outcome. Computes CE-FDH (staircase ceiling) and CR-FDH (regression ceiling) effect sizes plus permutation-based significance.

POST /mod-mediation

Moderated Mediation / Conditional Process Analysis (Edwards & Lambert 2007; Hayes 2018 Chapters 11–14). Detects interaction terms in the structural syntax and computes the Index of Moderated Mediation (IMM) with bootstrap 95 % CI plus conditional indirect effects at W = −1 SD, 0, +1 SD.

# H1: W moderates the X → M relationship
M ~  X + W + X*W
Y ~  X + M
X =~ x1 + x2 + x3
M =~ m1 + m2 + m3
W =~ w1 + w2 + w3
Y =~ y1 + y2 + y3

GET /logs/{run_id}

Server-Sent Events stream for a running analysis. Open immediately after submitting any endpoint that returns a run_id. The stream emits JSON objects and terminates with a done packet.

GET /fingerprint/{run_id}

Retrieve the full SHA-256 audit record for a completed run. The fingerprint covers model syntax hash, data hash (SHA-256 of sorted column hashes), algorithm, environment versions, and key fit metrics.

POST /upload/preview

Parse an uploaded file and return column names, row count, first 5 rows, and dtype map — without running any analysis. Useful for validating uploads before model submission.

GET /health

{ "status": "ok", "version": "0.7.1" }

Schemas

All response models are Pydantic v2 classes. Key schemas:

PathParameter

One row per model parameter (measurement loading, structural path, or covariance). std_error, z_value, and p_value are null for ~~ rows.

v0.9 Schemas

Fit Thresholds

Verdict flags set automatically by the engine:

Effect Sizes

Cohen's f² (structural paths)

Stone-Geisser Q² (predictive relevance)

NCA Effect Size d (Dul 2016)

POST /fimix

FIMIX-PLS (Finite Mixture PLS) detects unobserved heterogeneity by running an Expectation-Maximisation algorithm over PLS-SEM path weights to identify latent segments with distinct structural coefficient profiles. Reference: Hahn et al. 2002; Ringle et al. 2010.

POST /pos

PLS Prediction-Oriented Segmentation (PLS-POS) assigns observations to segments by minimising within-segment residuals iteratively — no distributional assumptions required. Reference: Becker et al. 2013.

POST /gaussian-copula

The Gaussian Copula approach (Park & Gupta 2012; Hult et al. 2018) corrects for endogeneity arising from non-normal, non-elliptical predictor distributions by augmenting the structural model with copula terms derived from the empirical CDF of each non-normal predictor.

POST /export/pdf

Generate a publication-ready PDF report from any completed run. The report covers measurement model validity, structural path estimates, bootstrapped confidence intervals, model fit indices, and any advanced analysis results (FIMIX, PLS-POS, Gaussian Copula, IPMA, NCA) that were included in the run. Tables follow APA 7th edition formatting conventions.

curl -X POST http://localhost:8000/export/pdf \
  -F "run_id=abc-123" \
  --output report.pdf

POST /cvi

Content Validity Index (Lynn 1986; Polit & Beck 2006). Accepts an expert ratings matrix — rows are experts, columns are scale items, values are 1–4 relevance ratings — and returns item-level I-CVI, scale-level S-CVI/Ave and S-CVI/UA, and modified kappa (κ*) correcting I-CVI for chance agreement.

# CSV — rows are experts (E1…E7), columns are items (Q1…Q6)
    ,Q1,Q2,Q3,Q4,Q5,Q6
E1 , 4, 3, 2, 4, 3, 4
E2 , 3, 4, 4, 4, 3, 3
E3 , 4, 4, 3, 3, 4, 4
# ... up to n_experts rows

curl -X POST http://localhost:8000/cvi \
  -F "file=@expert_ratings.csv" \
  -F "n_experts=7"

POST /efa

Exploratory Factor Analysis for early-stage scale development. Computes KMO adequacy and Bartlett's test of sphericity as suitability diagnostics, applies the Kaiser criterion (eigenvalue > 1) or a user-specified factor count, and extracts factors via sklearn's FactorAnalysis with the requested rotation. Flags weak-loading items (|λ| < 0.40) and cross-loading items (secondary |λ| > 0.30).

curl -X POST http://localhost:8000/efa \
  -F "file=@survey_items.csv" \
  -F "n_factors=3" \
  -F "rotation=varimax"

POST /nomological

Nomological Validity (Hair et al. 2019). Fits the structural model and checks whether each endogenous construct's R² meets the expected benchmark — the minimum explanatory power consistent with the theoretical nomological network the construct is embedded in. Returns a per-construct verdict (Substantial / Moderate / Weak / Not supported) using Cohen's (1988) conventional R² bands.

curl -X POST http://localhost:8000/nomological \
  -F "file=@data.csv" \
  -F "model=Y =~ y1+y2+y3\nX =~ x1+x2+x3\nY ~ X" \
  -F 'benchmarks={"Y":0.15,"*":0.10}'

POST /invariance

Measurement Invariance testing via a configural → metric → scalar sequence (Vandenberg & Lance 2000; Cheung & Rensvold 2002). Tests whether the same measurement model holds equivalently across groups, a prerequisite for meaningful multi-group structural comparisons. Uses ΔCFI ≤ −0.010 as the invariance failure criterion (robust to sample size). Returns a plain-English conclusion and, when scalar fails, a partial-invariance item release list.

curl -X POST http://localhost:8000/invariance \
  -F "file=@data.csv" \
  -F "model=X =~ x1+x2+x3\nY =~ y1+y2+y3" \
  -F "group_col=gender"

POST /nca-esse

NCA with Effect Size Sensitivity Extension (Becker, Richter, Ringle & Sarstedt 2026, Journal of Business Research, 206, 115920 — CC BY 4.0). Extends deterministic NCA (Dul 2016) by sweeping an ECDF removal threshold (default 0–5% in 0.5% steps) and recomputing CE-FDH ceiling lines at each step after discarding the most extreme ceiling-violating observations. Benchmarks the empirical sensitivity curve against a joint-uniform random distribution (no necessity by construction) and permutation-tests the effect size at every threshold, to distinguish genuine necessity from artefactual ceiling movement.

curl -X POST http://localhost:8000/nca-esse \
  -F "file=@data.csv" \
  -F "model=Y =~ y1+y2+y3\nX =~ x1+x2+x3\nY ~ X" \
  -F "n_permutations=500" \
  -F "n_benchmark_reps=500"

Becker, J.-M., Richter, N. F., Ringle, C. M., & Sarstedt, M. (2026).
Must-have, or maybe not? A sensitivity-based extension to necessary
condition analysis. Journal of Business Research, 206, 115920.
https://doi.org/10.1016/j.jbusres.2025.115920  (CC BY 4.0)

Changelog