Getting Started

NAVAL·SEM v1.0 Documentation

🏁

v1.0.0 LTS — Long-Term Support. This is the recommended build for academic research. All public result schemas are frozen: field names and types will not change in patch or minor releases. Cite with confidence.

NAVAL·SEM is a free, open-source desktop application for Structural Equation Modeling (PLS-SEM and CB-SEM), fsQCA, and the full suite of measurement, validity, and robustness analyses required for journal submission. It runs a local FastAPI server that the UI communicates with over HTTP — meaning you can also call it from your own Python or R scripts.

# 1. Start the application (desktop mode launches browser automatically)
python launcher.py

# 2. Or start headless API server only
uvicorn app.main:app --port 8765

# 3. Verify server is up
curl http://localhost:8765/health
# → {"status": "ok", "version": "1.0.0"}

Installation

Installing NAVAL·SEM

Three distribution channels are available. All are free.

# Option A: Windows installer (SourceForge)
# Download naval-sem-v1.0.0-setup.exe from SourceForge and run

# Option B: From source (Python 3.10+)
git clone https://github.com/navalsingh9/naval-sem
cd naval-sem
pip install -r requirements.txt
python launcher.py

# Option C: Microsoft Store
# Search "NAVAL SEM" in the Microsoft Store

Zenodo DOI: Every release is archived on Zenodo for reproducibility. The v1.0.0 DOI is included in the CITATION.cff file in the repository root.

Core Endpoints

POST /run

Fit a structural equation model. Supports PLS-SEM, CB-SEM (ML), and WLS. Returns fit indices, loadings, path coefficients, R², VIF, and f².

POST /run

Parameter	Type	Required	Description
syntax	string	required	lavaan-style model syntax (`=~`, `~`, `~~`)
data	string (base64)	required	Base64-encoded CSV, XLSX, or SAV file
algorithm	string	optional	`"pls"` (default) \| `"cbsem"` \| `"wls"`
missing	string	optional	`"listwise"` (default) \| `"mean"`
bootstrap_n	integer	optional	Bootstrap replications (0 = off). Use `/bootstrap` for full results.

# Example: Run PLS-SEM on CorporateRep dataset
{
  "syntax": "QUAL =~ q1 + q2 + q3\nCUSTSAT =~ cs1 + cs2\nCUSTSAT ~ QUAL",
  "data": "base64encodedCSV...",
  "algorithm": "pls"
}

# Response (ModelResult — FROZEN schema)
{
  "parameters": [{ "lhs": "CUSTSAT", "rhs": "QUAL", "estimate": 0.74, "p": 0.001 }],
  "fit": { "cfi": 0.96, "rmsea": 0.048, "r2": { "CUSTSAT": 0.55 } },
  "vif": [{ "indicator": "q1", "vif": 2.1 }],
  "f2": [{ "path": "QUAL→CUSTSAT", "f2": 0.22, "size": "medium" }]
}

New in v1.0

POST /fsqca New

fuzzy-set Qualitative Comparative Analysis. Accepts raw case data, calibrates fuzzy-set membership, performs necessity analysis, constructs the truth table, and minimises it using Quine-McCluskey Boolean algebra. Returns complex, parsimonious, and intermediate solutions.

POST /fsqca v1.0 · FsQCAResult FROZEN

Parameter	Type	Required	Description
outcome	string	required	Column name of the outcome variable in the data
conditions	string[]	required	Array of condition column names (2–6 recommended)
data	string (base64)	required	Base64-encoded CSV/XLSX with outcome and condition columns
calibration.method	string	optional	`"direct"` (default) — uses crossover and thresholds
calibration.crossover	float	optional	Crossover point for calibration (default: 0.5)
calibration.thresholds	float[2]	optional	Full non-membership and full membership thresholds, e.g. `[0.05, 0.95]`
frequency_cutoff	integer	optional	Minimum cases per truth table row (default: 1)
consistency_cutoff	float	optional	Minimum row consistency to include in solution (default: 0.8)
solution_type	string	optional	`"complex"` (default) \| `"parsimonious"` \| `"intermediate"`

# Request
{
  "outcome": "HighPerformance",
  "conditions": ["LeaderSupport", "Resources", "Training"],
  "data": "base64...",
  "calibration": { "method": "direct", "crossover": 0.5, "thresholds": [0.05, 0.95] },
  "consistency_cutoff": 0.8,
  "solution_type": "complex"
}

# FsQCAResult response (FROZEN)
{
  "necessity": [
    { "condition": "LeaderSupport", "coverage": 0.81, "consistency": 0.92, "necessary": true }
  ],
  "truth_table": [
    { "config": [1,1,0], "n": 4, "consistency": 0.89, "raw_coverage": 0.34, "outcome": 1 }
  ],
  "solutions": [
    { "term": "LeaderSupport*Resources", "raw_coverage": 0.64, "unique_coverage": 0.19, "consistency": 0.91 }
  ],
  "solution_coverage": 0.76,
  "solution_consistency": 0.88,
  "bubble_chart": [{ "x": 0.82, "y": 0.75, "size": 3, "label": "case_4" }]
}

Interpreting solutions: A tilde prefix ~ denotes logical NOT (absent condition). For example, LeaderSupport*~Resources means "high leader support AND low resources." Each term in the solution array is a sufficient path to the outcome.

New in v1.0

POST /report New

Generate a submission-ready APA 7th edition Word (.docx) report aggregating all completed analysis results for a given run. Tables include measurement model, discriminant validity, structural paths, and indirect effects.

POST /report v1.0 · Returns .docx binary

Parameter	Type	Required	Description
run_id	string	required	Run ID from a previous `/run` call; the engine aggregates all results for this session.
include_htmt	boolean	optional	Include HTMT matrix table (default: `true` if HTMT was run)
include_indirect	boolean	optional	Include indirect effects table (default: `true` if /indirect was run)
ci_level	float	optional	Confidence interval level for bootstrap tables (default: 0.95)

# Typical usage — run model, then export report
run_result = requests.post("/run", json={ ... })
run_id = run_result.json()["run_id"]

# (optionally run /bootstrap, /htmt, /indirect first)

report_resp = requests.post("/report", json={ "run_id": run_id })
# → returns application/vnd.openxmlformats-officedocument.wordprocessingml.document
# Save as .docx and open in Word / LibreOffice
with open("report_APA7.docx", "wb") as f:
    f.write(report_resp.content)

APA 7 formatting: Tables use no vertical rules, horizontal rules at head and foot only, 12-pt Times New Roman body text, and double spacing per APA 7th edition Publication Manual §7.12. Significance levels are noted as footnotes (* p < .05, ** p < .01, *** p < .001).

Scale Development · v0.9

POST /cvi

Content Validity Index. Accepts an expert rating matrix (experts × items, ratings 1–4) and returns item-level I-CVI and scale-level S-CVI/Ave and S-CVI/UA. Polit & Beck (2006) thresholds applied automatically.

{ "ratings": [[3,4,4],[4,4,3]], "n_experts": 12, "n_items": 20 }
# → CVIResult: i_cvi[], s_cvi_ave, s_cvi_ua, verdicts

Scale Development · v0.9

POST /efa

Exploratory Factor Analysis with principal-axis factoring. Supports promax (oblique) and varimax (orthogonal) rotation. Kaiser criterion and scree-plot eigenvalues returned for factor retention guidance.

Parameter	Type	Required	Description
data	string (base64)	required	Dataset with indicator columns
rotation	string	optional	`"promax"` (default) \| `"varimax"`
n_factors	integer	optional	Force extraction of N factors. Omit for Kaiser automatic extraction.

Reference

Schema Stability

All public result schemas are frozen as of v1.0.0. The following guarantees apply to v1.x.x releases:

✓ No field in any frozen schema will be renamed or removed
✓ No field type will be narrowed (e.g., from float to int)
✓ New optional fields may be added — existing integrations will not break
✓ Extra fields in request bodies are silently ignored (extra="ignore")

ModelResult FROZEN

parameters · fit · vif · f2 · outer_weights · r2

FsQCAResult FROZEN

necessity · truth_table · solutions · bubble_chart

BootstrapResult FROZEN

paths · ci_lower · ci_upper · p_value

MGAResult FROZEN

groups · path_differences · permutation_p

CVIResult FROZEN

i_cvi · s_cvi_ave · s_cvi_ua · verdicts

NCAESSEResult FROZEN

entries · threshold_points · permutation_p

Reference

Migration from v0.9

v1.0.0 is a forward-only additive release. No existing calls need modification.

Zero breaking changes. All v0.9 API calls work unchanged on v1.0. The extra="ignore" change means request bodies with unexpected fields will no longer raise 422 errors — this is a relaxation, not a break.

New fields to expect: If you are deserialising ModelResult strictly, be prepared for new optional fields (e.g., run_id) that may appear in v1.x.x without notice — this is the schema stability guarantee in action. Use extra="ignore" in your own schema if you are building on top of NAVAL-SEM's API.

Reference

Citing NAVAL·SEM

If you use NAVAL·SEM in your research, please cite the software using the Zenodo DOI. A CITATION.cff is included in the repository for APA 7, BibTeX, and RIS export.

# APA 7 software citation template
Singh, N. (2026). NAVAL·SEM (Version 1.0.0) [Computer software].
Zenodo. https://doi.org/10.5281/zenodo.naval-sem-v1