SNAP: Technical Details

A deep dive into the architecture, requirements, and implementation of the SNAP simulation tool.

Overview

SNAP (Simulation of Nuclear and Affected Pedigrees) is a web-based tool hosted at https://statgen.uni-koeln.de/ for simulating genetic data. It supports case-control and family-based studies, generating synthetic datasets based on user-defined study designs, sampling strategies, and genotype-phenotype models. The backend, implemented in PHP (run.php), processes JSON inputs, generates settings files, executes SNAP binaries (snap3.1 or snap2.6.1), and delivers output files via a web interface.

This page details the technical architecture, requirements, functionalities, and recent updates to the SNAP backend.

Technical Requirements

Server Environment
  • PHP: Version 7.x or later, with error reporting (E_ALL).
  • Web Server: Apache with write access to /var/www/html/statgen.uni-koeln.de/software/snap/.
  • SNAP Binaries: snap3.1 and snap2.6.1 in snap/run/.
  • File System:
    • Base: /var/www/html/statgen.uni-koeln.de/software/snap/
    • Temp: snap/temp/ (permissions: 0775)
    • Run: snap/run/
    • Error Log: snap/run_error.log
Client-Side
  • Interface: HTML/JavaScript with Bootstrap 5.3 and Bootstrap Icons 1.10.5.
  • Input: JSON (SNAP_JSON) stored in localStorage, sent via AJAX POST to run.php.
  • Dependencies:
    • Bootstrap CSS/JS via CDN
    • Bootstrap Icons via CDN
Non-Functional
  • Performance: Process JSON and generate settings in seconds; efficient SNAP binary execution.
  • Security: Sanitize filenames, set file permissions (0644 for settings, 0444 for outputs).
  • Reliability: Robust handling of malformed JSON or missing data.
  • Maintainability: Modular PHP code with detailed logging.

Functionalities

Input Processing

Reads SNAP_JSON from php://input via AJAX POST, decoding it into a PHP array. Validates JSON and extracts sections:

  • SnapSettings: Filenames, output types.
  • DesignData: Study design, phenotype.
  • SexAgeData: Age/sex distributions.
  • ModelData: Genotype-phenotype models.
  • HaplotypeBloks: Haplotype configurations.

Validates flags (design_flag, model_flag, etc.) to ensure parameters are set.

Settings File Generation

Generates a .set file with sections:

  • [General]: Output filenames, format.
  • [Design]: Study/sampling design, counts.
  • [SexAge]: Sex ratio, age parameters.
  • [Model]: Penetrances or phenotypic means.
  • [Separators]: Output delimiters.
  • [Blocks]: Haplotype blocks.

Sanitizes filenames and validates numeric inputs.

Simulation Execution

Executes SNAP binary (snap3.1 or snap2.6.1) with the settings file, capturing output and errors to stderr.txt. Checks for success ("Data successfully generated.").

Output Handling

Moves outputs (.dat, .log) to a temp directory, creates a snap.tgz archive, and generates HTML with download links, valid for 24 hours.

Architecture

The SNAP backend is implemented in run.php, a PHP script that orchestrates input processing, simulation, and output delivery.

run.php Structure
  • Configuration:
    • SNAP_BASE_PATH: /var/www/html/statgen.uni-koeln.de/software/snap/
    • SNAP_TEMP_DIR, SNAP_RUN_DIR, MAX_AGE_SECONDS (24 hours).
  • Helper Functions:
    • logError($message): Logs to run_error.log.
    • sanitizeFilename($filename): Removes non-alphanumeric characters.
    • getArrayValue($array, $key, $default): Safe array access.
    • search_temp($directory): Finds unique temp directories.
  • Core Functions:
    • generateSettingsFile($data, $settingsFilePath): Builds .set file.
    • generateModelTypeSettings($modelData): Handles quantitative models.
    • generatePenetrancesSetting($modelData): Handles qualitative penetrances.
    • buildHTML(...): Main logic for JSON processing and output.
Input/Output

Input (SNAP_JSON):

{
  "SnapSettings": { "user_settings_filename": "string", ... },
  "DesignData": { "phenotype": "qualitative|quantitative", "study_design": "individuals|nuclear-families", ... },
  "SexAgeData": { "sexRatio": number, ... },
  "ModelData": { "number_loci": number, "penetrances": array, ... },
  "HaplotypeBloks": [{ "blockNumber": number, ... }]
}

Outputs:

  • settings.set: Simulation parameters.
  • data.dat: Genetic data.
  • settings_log.log: Modified settings.
  • stderr.txt: Errors/warnings.
  • snap.tgz: Archive of all files.

Recent Updates

Recent enhancements to run.php (Artifact ID: a709bb42-8a9c-479b-84b0-0a3f5954b05c) addressed issues and aligned with example settings:

Fixes
  • Undefined Variables: Fixed warnings for designFlag, penetranceFlag, modelFlag, blockFlag by validating DesignData, ModelData, and HaplotypeBloks: 
    $designData = isset($data['DesignData']) && is_array($data['DesignData']) ? $data['DesignData'] : [];
$designFlag = getArrayValue($designData, 'design_flag', 'true');
  • Typo: Corrected $userSettingsFile_stderr to $stderrFile.
[Design] Logic Improvements

Updated generateSettingsFile to match seven example settings:

  • Defaults: Changed StudyDesign to individuals, SamplingDesign to joint or random.
  • Validation: Added checks for valid values: 
    $validPhenotypes = ['qualitative', 'quantitative'];
$validStudyDesigns = ['individuals', 'nuclear-families'];
  • Conditional Logic: For individuals, include NumberOfCases/NumberOfControls (separate) or NumberOfIndividuals (joint). For nuclear-families, include NumberOfFamilies, NumberOfChildren, TypeOfFamily.
  • Logging: Added logs for invalid/missing parameters.

© 2025 SNAP Project, University of Cologne.

Hosted at https://statgen.uni-koeln.de/