NAVAL-SEM v0.8

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.

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

Changelog