Skip to main content
JC

PROJECT CASE STUDY

Proteomics CSV Validation System

A repeatable local checkpoint for processed proteomics CSVs before further analysis or data handoff

proteomics-csv-validation is a local Python system for structural and technical review of processed-sample proteomics CSV files. The browser application is the primary human-facing workflow; the CLI supports direct, reproducible command-line use.

I independently designed and built the system during an eight-week graduate capstone that reached version 0.5.0. Version 0.5.1 is the post-capstone open-source successor, with Apache License 2.0 and software citation metadata. Validation logic and bundled validation profiles are unchanged from v0.5.0.

Source repository v0.5.1 release
Application
0.5.1
Runtime
Local Python ≥3.11
Regression
342 tests
Capstone public-data evaluation
42 records

01 / PRODUCT

Rule-based findings for technical review

Version 0.5.0 adds a local review workflow to the structural validator. Reviewers submit a compatible CSV, inspect run details and findings, reopen prior runs through History, compare compatible runs deterministically, and export the exact stored Result Bundle.

Why I built the workflow this way. I designed the workflow to preserve the submitted source, define review rules explicitly, and store a durable record that reviewers can reopen, compare, and export without rerunning validation.

Finding counts summarize conditions detected by the configured structural rules. They are not quality scores. Scientific validity, biological interpretation, experimental quality, repository acceptance, and clinical validity require separate evaluation.

Dark-theme Review result page showing a completed structural review with four findings, run details, and source details.
Result view from the controlled seeded-errors fixture.

02 / WORKFLOW

Review → Result → History → Compare → Export

  1. 01
    Review

    Submit a compatible CSV under the selected profile and mapping mode.

  2. 02
    Result

    Inspect run identity, source details, configuration, summary counts, individual findings, and Result Bundle contents.

  3. 03
    History

    Reopen completed prior runs from saved local History.

  4. 04
    Compare

    Compare compatible prior runs using right-minus-left descriptive deltas.

  5. 05
    Export

    Export the stored Result Bundle byte-for-byte without rerunning validation.

Command-Line Interface

The CLI is supported alongside the browser workflow. proteomics-csv-validate is available for reproducible command-line review, automation, and package-level verification.

03 / REVIEW MODEL

Profiles define requirements; mapping resolves names

Profiles

Profile 0.2.0 is the six-field default. Profile 0.3.0 is the selectable Reduced Metadata profile. Historical profile 0.1.0 is packaged for compatibility.

Mapping

The system supports strict, automatic, and explicit mapping modes. Mapping resolves recognized source headers to canonical field names, while profile selection is separate.

Validation Rules

Schema, identifier, and required-value missingness checks handle distinct structural conditions, avoiding duplicate classification.

Component Versions

Descriptor Schema
1.0.0

Mapping Specification
1.0.0

Missingness Rule
missingness.required_value 1.0.0

Application Version
0.5.1

04 / ARCHITECTURE

Durable local state and exact Result Bundle exports

SQLite stores run and configuration state plus records for stored Result Bundles. The Result Bundle files are stored on the filesystem. Before a stored result is reopened or exported, the application checks that the database record and file still agree.

Runtime Dependencies

The base CLI uses only the Python standard library at runtime. Browser dependencies are isolated in the web extra.

Server-Rendered Interface

Core reviewer tasks use server-rendered HTML/CSS and function without JavaScript.

Stored-Result Integrity

If stored data is corrupted or no longer matches its record, the application reports an integrity failure instead of trusting the result.

Implementation and Security

Web Extra
FastAPI 0.141.1 · Uvicorn 0.52.4 · Jinja2 3.1.6 · python-multipart 0.0.32

Persistence
stdlib sqlite3 · explicit migrations · WAL

Request Safeguards
HMAC-based cross-site request forgery (CSRF) protection · same-origin checks · trusted hosts · bounded multipart handling

Filesystem Safeguards
filename sanitization · application-owned staging · security headers

05 / APPEARANCE

Consistent information hierarchy in light and dark modes

The application follows the operating system's appearance preference. The paired screenshots show the same Compare state in light and dark modes.

Light-theme Compare review runs page showing two selected run identifiers and links to their stored review records.
Light appearance
Dark-theme Compare review runs page showing the same comparison state under the alternate system appearance.
Dark appearance

06 / COMPARE

Descriptive differences between completed runs

Compare reports exact structural differences between compatible completed runs, with deltas calculated as right minus left.

The deltas describe structural differences only; they do not indicate quality, improvement, regression, or biological meaning.

Dark-theme Summary comparison showing right-minus-left totals by finding category, code, severity, and scope.
Summary comparison for a zero-finding baseline and a four-finding seeded-errors run.

07 / TESTING & EVALUATION

Testing, public-data evaluation, and release verification

Current Release 342

Regression Tests

The v0.5.1 regression suite contains 342 passing tests.

Public Data 42

PXD060583 Records

At the v0.5.0 capstone endpoint, a separate public-data structural evaluation used 42 processed-sample records derived from PXD060583. The evaluation covered the selected profiles, mappings, structural rules, and derivation only.

Capstone Hosted CI 7

Successful CI Jobs

The final v0.5.0 hosted CI run completed six platform/interpreter test jobs plus one release-artifact build job.

Release Integrity 3

Release Assets

The immutable v0.5.1 release publishes the wheel, source distribution, and SHA-256 checksum record. Public assets were downloaded and rehashed after publication.

Historical Controlled Fixtures and v0.2.0 Testing

Three controlled synthetic fixtures established exact known outcomes: a zero-finding baseline, four seeded schema/identifier findings, and three required-value missingness findings.

Historical v0.2.0 system testing ran a 12-case compatible-input matrix twice across six hosted environments, for 144 successful executions. A Windows path assumption in the test harness was corrected without changing application behavior.

Historical Performance, Sustained-Load, and Concurrency Testing

Historical v0.2.0 installed-command timing used five warm-ups and 30 measured runs at each of 1,000, 10,000, and 100,000 rows, for 90 observations on an Apple M1 workstation under local single-process execution.

Installed-Command Latency

Historical v0.2.0 · Apple M1 · 90 measured observations

Median latency with interquartile range (IQR). Bar lengths show relative median latency within this recorded protocol.

1,000 rows 0.074087 s median · IQR 0.005143 s
10,000 rows 0.119931 s median · IQR 0.001670 s
100,000 rows 0.656833 s median · IQR 0.018199 s

Exact values and variability are shown above. The bars provide a within-protocol visual comparison only.

A separate local load and concurrency test completed 500 sequential executions at 100,000 rows and 150 executions across concurrency levels 1, 2, 4, and 8 with zero failures and zero normalized-result mismatches.

These measurements apply only to the documented local conditions and should not be treated as production-capacity benchmarks or generalized to other hardware.

Historical Independent Usability Evaluation

The final v0.4.0 usability evaluation involved two independent technically literate reviewers completing eight predefined tasks each. All 16 answers matched the predefined scoring key without substantive facilitator assistance.

These results reflect two participants; broader usability conclusions would require a larger predefined study.

Historical v0.5.0 Release and Distribution Verification

Version 0.5.0 was rebuilt from the release source revision, installed as a wheel under Python 3.11 and 3.14, checked against its release asset hashes, and published as an immutable GitHub release. The release and all three asset attestations were verified.

08 / RELEASE PROGRESSION

From local validation to review, history, comparison, and export

  1. v0.1.067 tests

    Initial local validation workflow

  2. v0.2.075 tests

    Required-value missingness

  3. v0.3.098 tests

    Automatic and explicit header mapping

  4. v0.4.0111 tests

    Reduced Metadata profile at the release checkpoint

  5. v0.5.0342 tests

    Browser review, History, Compare, and exact Export

  6. v0.5.1342 tests

    Post-capstone open-source release with Apache-2.0 and software citation metadata

Selected Engineering Decisions
  • Test-harness failures were separated from application defects before changing product behavior.
  • SQLite stores the local run ledger without an ORM dependency.
  • Run and configuration state lives in SQLite, while immutable Result Bundle files are stored on the filesystem.
  • Browser dependencies are packaged in the optional web extra; the base CLI has zero third-party runtime dependencies.
  • Appearance follows the operating-system preference without a JavaScript theme toggle.
Technologies Evaluated During Development

During development, I evaluated scikit-learn, Pyteomics, pyOpenMS, pymzQC, SDRF tooling, HTMX, and Playwright. The evaluations informed scope decisions; none of those tools are package dependencies in v0.5.1.

09 / FUTURE DIRECTIONS

What I would test next

Proteomics Interoperability

Evaluate SDRF-Proteomics, PSI controlled-vocabulary alignment, mzQC exchange, and mzML-linked metadata workflows using tools such as sdrf-pipelines, pymzQC, Pyteomics, or pyOpenMS. Separate development research examined public DDA/LFQ, TMT, DIA, and mzML/QC datasets to test interoperability assumptions and future QC directions; these were distinct from the v0.5.0 PXD060583 processed-CSV evaluation.

SDRF conformity, repository-submission readiness, and raw LC-MS processing are outside the current system's scope.

Deeper Structural and Cohort Review

Explore numeric syntax, controlled vocabularies, batch/group summaries, profile-specific ranges, richer profiles, and predefined outlier or cohort checks.

Structural outlier flags would require separate biological interpretation and would not trigger automatic correction.

Model-Assisted Review

Study scikit-learn-backed review prioritization or unusual-pattern detection as an adjunct to deterministic findings.

Any model would require defined training data, leakage-controlled evaluation, predefined metrics, baseline comparisons, reproducibility and privacy controls, and human review.

Evaluation and Scale

Broaden independent reviewers and public datasets, then measure memory, cold/warm execution, sustained runs, concurrency, recovery timing, and additional physical hardware.

Broader claims would require broader evaluation.
Longer-Term Architecture

Research-object packaging such as RO-Crate could be evaluated for a defined multi-artifact archival use case. A hosted service would require a separate architecture for authentication, authorization, storage, monitoring, backup and recovery, incident handling, and threat modeling.

10 / SCOPE

Outside the system's scope

Scientific Validityrequires separate scientific evaluation
Biological Meaningrequires downstream biological and statistical interpretation
Repository Acceptancedepends on the selected repository's specification and submission process
Normalization / Imputationrequires study-specific analytical methods and decisions
Clinical Validityrequires separate clinical evaluation
Dataset Approvalis a reviewer decision

11 / RESOURCES

Source, release, citation, and preservation

Source RepositoryCode, tests, documentation, and release historyOpen repository ↗ Current Releasev0.5.1 · wheel · source distribution · SHA-256 recordOpen release ↗ Zenodo DOIVersion 0.5.1 software record · DOI 10.5281/zenodo.22700241Open Zenodo ↗ Software HeritageArchived v0.5.1 source snapshotOpen archive ↗