DSM-5 Hierarchical Symptom Database & Utilities

Author: Lee Boonstra

As a software engineer, I look at classification systems through the lens of data architecture, relational integrity, and decision trees.

When we look at traditional physical medicine, diagnostics are built on discrete, biologically isolated decision trees. For example, determining whether a patient has a Common Cold vs. COVID-19 is a binary, biological classification: you either have the rhinovirus or the SARS-CoV-2 virus. The diagnostic boundaries are clear, mutually exclusive, and physically verifiable.

In contrast, psychiatry's DSM-5-TR is built on a categorical classification model that completely lacks biological boundaries. It defines disorders not by unique pathology, but as arbitrary checklists of overlapping, descriptive symptoms.

Because distinct diagnostic categories share identical symptom definitions (e.g., fatigue, sleep disturbances, concentration difficulties), the boundaries between disorders are porous and fundamentally entangled. This creates massive comorbidity overlaps and tautological loops (such as the "Anxiety-Depression Vortex"), where a clinician is mathematically forced to diagnose a patient with multiple conditions simultaneously.

I believe this proves that the DSM's categorical boundaries are artificial. Instead of reflecting discrete medical realities, the DSM forces fluid clinical presentations into rigid, overlapping boxes.

I have built an interactive data science visualizer to map, calculate, and prove this hypothesis using the semantic geometry of the DSM-5.

You can interact with the live proof and run the simulations here: 👉 https://savelee.github.io/dsm-in-vector-space/

The application features:

1. Topological Network Graph: A live physics-based network mapping shared symptom nodes between disorder nodes, showing the porous structural overlap.
2. Semantic Vector Space: A 2D projection of clinical description embeddings mapped on a clean, dense blueprint grid. Points closer together share deep linguistic context, proving the semantic entanglement.
3. Virtual Shrink Simulator: A live diagnostic engine that calculates overlapping symptom profiles and triggers a "Comorbidity Loop Warning" when the categorical model collapses under high ambiguity.

This repository contains the structured JSON datasets representing the DSM-5-TR classification of mental disorders, along with database schemas, vector embedding utilities, and tools to parse, list, and validate diagnostic symptoms.

This project and its datasets are licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) License.

If you use this dataset or code in your own project, website, research, or application, you must provide attribution by linking back to the author's name and website:

DSM-5-TR JSON Database by Lee Boonstra (licensed under CC BY 4.0)

For details, see the full LICENSE file.

The core datasets are organized in the official DSM-5 diagnostic chapter order under the data/ directory.

A set of database migrations and models is available in the db/ directory to help you load and validate the diagnostic data in production applications:

• Relational Schema (SQL): A fully normalized 3NF PostgreSQL schema (db/schema.sql) separating chapters, diagnoses, and symptoms.
• Document Schema (JSON): A standard JSON Schema (db/schema.json) and TypeScript definitions (db/schema.ts) validating the improved, strongly-typed document format.
• Python Models: Python dataclass models (db/models.py) providing out-of-the-box parsing and automatic conversion of legacy payloads.

See the Database Schema README for detailed Entity-Relationship diagrams and getting started guides.

The repository includes an optimized utility script to pre-compute vector embeddings for all diagnoses and symptoms using state-of-the-art clinical text embedding models. Committing these vectors to GitHub saves API latency and costs for other developers.

To run the embedding generator on your local machine:

1. Install SDK Dependencies:

   make init-embeddings

2. Generate the Embedding Cache: Provide your active Cloud Project ID:

   make generate-embeddings PROJECT_ID=your-project-id

   This will generate a single optimized local vector lookup file at embeddings/embeddings_text_embedding_005.json.

• Python 3.12+
• uv package manager

Initialize the virtual environment and install the development dependencies:

make init

To run the unit test suite:

make test

To check and enforce PEP 8 coding standards:

make format
make lint

This is a pure client-side, touch-optimized, PWA-enabled web application. It runs 100% in the browser and requires no server-side running backend, making it perfect for free static hosting (like GitHub Pages, Vercel, or Firebase Hosting).

1. Install Dependencies:

   make init-modern-viz

2. Run Local Development Server:

   make run-modern-viz

   This starts the local development server at http://localhost:5173/.
3. Build Static Bundle:

   make build-modern-viz

   This compiles the application into an optimized static modern-viz/dist/ folder, ready for free instant hosting.