toxsim 0.1.0__py3-none-any.whl

toxsim/__init__.py

@@ -0,0 +1,11 @@
+"""Public API for context-aware synthetic poisoned-patient generation."""
+
+from .simulator import ModelData, ModelDataError, create_patient, create_patients, load_model_data
+
+__all__ = [
+    "ModelData",
+    "ModelDataError",
+    "create_patient",
+    "create_patients",
+    "load_model_data",
+]

toxsim/data/model/age_score.yml

@@ -0,0 +1,32 @@
+criteria: range
+values:
+  - name: "<25"
+    representation: "<25"
+    min: 0
+    max: 24
+    score: 0
+  - name: "25-35"
+    representation: "25-35"
+    min: 25
+    max: 34
+    score: 2
+  - name: "35-45"
+    representation: "35-45"
+    min: 35
+    max: 44
+    score: 4
+  - name: "45-55"
+    representation: "45-55"
+    min: 45
+    max: 54
+    score: 6
+  - name: "55-65"
+    representation: "55-65"
+    min: 55
+    max: 64
+    score: 8
+  - name: ">65"
+    representation: '$\geq$ 65'
+    min: 65
+    max: 100
+    score: 10

toxsim/data/model/cirrhosis_score.yml

@@ -0,0 +1,8 @@
+criteria: categorical
+values:
+  - name: "Yes"
+    score: 7
+    representation: "Yes"
+  - name: "No"
+    score: 0
+    representation: "No"

toxsim/data/model/dysrhythmia_score.yml

@@ -0,0 +1,8 @@
+criteria: categorical
+values:
+  - name: "Yes"
+    score: 5
+    representation: "Yes"
+  - name: "No"
+    score: 0
+    representation: "No"

toxsim/data/model/gcs_score.yml

@@ -0,0 +1,22 @@
+criteria: range
+values:
+  - name: $\geq 14$
+    representation: ">= 14"
+    min: 14
+    max: 15
+    score: 0
+  - name: 9-14
+    representation: "9-14"
+    min: 9
+    max: 13
+    score: 3
+  - name: 6-9
+    representation: "6-9"
+    min: 7
+    max: 8
+    score: 6
+  - name: "<6"
+    representation: "$\\leq 6$"
+    min: 0
+    max: 6
+    score: 9

toxsim/data/model/hr_score.yml

@@ -0,0 +1,27 @@
+criteria: range
+values:
+  - name: "<75"
+    representation: $<75$
+    min: 20
+    max: 74
+    score: 0
+  - name: "75-85"
+    representation: $75-85$
+    min: 75
+    max: 84
+    score: 1
+  - name: "85-95"
+    representation: $85-95$
+    min: 85
+    max: 94
+    score: 2
+  - name: "95-105"
+    representation: $95-105$
+    min: 95
+    max: 104
+    score: 3
+  - name: "<105"
+    representation: $\geq 105$
+    min: 105
+    max: 300
+    score: 4

toxsim/data/model/intoxicant_score.yml

@@ -0,0 +1,26 @@
+criteria: categorical
+values:
+  - name: Alcohol
+    score: -5
+    representation: Alcohol
+  - name: Analgesic
+    score: 1
+    representation: Analgesic
+  - name: Antidepressant
+    score: 0
+    representation: Antidepressant
+  - name: Street Drugs
+    score: 1
+    representation: Street Drugs
+  - name: Sedatives
+    score: -1
+    representation: Sedatives
+  - name: "CO, As, CN"
+    score: -6
+    representation: "CO, As, CN"
+  - name: Toxins NOS
+    score: 2
+    representation: Toxins NOS
+  - name: Polysubstance
+    score: 0
+    representation: Polysubstance

toxsim/data/model/predictive_variables.yml

@@ -0,0 +1,89 @@
+- name: intoxicant 
+  repr: Exposure Category
+  type: categorical
+  allowed_values:
+    - Alcohol
+    - Analgesic
+    - Antidepressant
+    - Street Drugs
+    - Sedatives
+    - "CO, As, CN"
+    - Toxins NOS
+    - Polysubstance
+- name: age
+  type: continuous
+  allowed_values: 
+    min: 12
+    max: 100
+- name: sbp
+  repr: Systolic Blood Pressure
+  type: continuous
+  allowed_values:
+    min: 100
+    max: 140
+- name: hr
+  repr: Heart Rate
+  type: continuous
+  allowed_values:
+    min: 60
+    max: 200
+- name: gcs
+  type: categorical
+  allowed_values:
+    - 3
+    - 4
+    - 5
+    - 6
+    - 7
+    - 8
+    - 9
+    - 10
+    - 11
+    - 12
+    - 13
+    - 14
+    - 15
+- name: second_diagnose
+  repr: Other Reason for ICU Admission
+  type: categorical
+  dist:
+    - value: No
+      probability: 0.7
+    - value: Yes
+      probability: 0.3
+  allowed_values:
+    - No
+    - Yes
+- name: cirrhosis
+  repr: History of Cirrhosis
+  type: categorical
+  allowed_values:
+    - No
+    - Yes
+  dist:
+    - value: No
+      probability: 0.9
+    - value: Yes
+      probability: 0.1
+- name: dysrhythmia
+  repr: Dysrhythmia
+  type: categorical
+  dist:
+    - value: No
+      probability: 0.8
+    - value: Yes
+      probability: 0.2
+  allowed_values:
+    - No
+    - Yes
+- name: respiratory
+  repr: Respiratory Failure
+  dist:
+    - value: No
+      probability: 0.6
+    - value: Yes
+      probability: 0.4
+  type: categorical
+  allowed_values:
+    - No
+    - Yes

toxsim/data/model/respiratory_score.yml

@@ -0,0 +1,8 @@
+criteria: categorical
+values:
+  - name: "Yes"
+    score: 8
+    representation: "Yes"
+  - name: "No"
+    score: 0
+    representation: "No"

toxsim/data/model/sbp_score.yml

@@ -0,0 +1,32 @@
+criteria: range
+values:
+  - name: "<=140"
+    score: -3
+    representation: "$\\geq$ 140"
+    min: 140
+    max: 999
+  - name: 130-140
+    score: -1
+    representation: "130-140"
+    min: 130
+    max: 139
+  - name: 120-130
+    score: 0
+    representation: "120-130"
+    min: 120
+    max: 129
+  - name: 110-120
+    score: 1
+    representation: "110-120"
+    min: 110
+    max: 119
+  - name: 100-110
+    score: 2
+    representation: "100-110"
+    min: 100
+    max: 109
+  - name: <100"
+    score: 4
+    representation: "$<100$"
+    min: 0
+    max: 99

toxsim/data/model/second_diagnose_score.yml

@@ -0,0 +1,8 @@
+criteria: categorical
+values:
+  - name: "Yes"
+    score: 7
+    representation: "Yes"
+  - name: "No"
+    score: 0
+    representation: "No"

toxsim/data/model.schema.yml

@@ -0,0 +1,7 @@
+- "@context": https://schema.org
+  "@id": https://w3.org/yaml-ld/
+  "@type": WebContent
+  name: YAML-LD
+  author:
+  "@id": https://www.w3.org/community/json-ld
+  name: JSON-LD Community Group

toxsim/generate.py

@@ -0,0 +1,103 @@
+"""Command-line generation of JSON and JSONL synthetic-patient datasets."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Sequence
+
+from .simulator import ModelDataError, create_patients, load_model_data
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the CLI argument parser."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--count", type=int, default=1, help="Number of patients to generate.")
+    destination_group = parser.add_mutually_exclusive_group()
+    destination_group.add_argument(
+        "--destination",
+        type=Path,
+        help="Directory to receive patients.json and/or patients.jsonl.",
+    )
+    destination_group.add_argument(
+        "--output",
+        type=Path,
+        help="Output file path ending in .json or .jsonl; its suffix selects the format.",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("json", "jsonl", "both"),
+        help="Output format for --destination (default: both).",
+    )
+    parser.add_argument("--seed", type=int, help="Seed for deterministic output.")
+    parser.add_argument(
+        "--model-data-dir",
+        type=Path,
+        help="Directory containing predictive_variables.yml and score YAML files.",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Generate patient files and return a shell-compatible exit code."""
+    args = build_parser().parse_args(argv)
+    if args.count < 0:
+        raise SystemExit("--count must be non-negative.")
+    try:
+        model_data = load_model_data(args.model_data_dir)
+    except ModelDataError as error:
+        raise SystemExit(f"toxsim-generate: {error}") from error
+
+    patients = create_patients(model_data, args.count, seed=args.seed)
+    if args.output is not None:
+        output_format = _format_from_output_path(args.output)
+        if args.format is not None and args.format != output_format:
+            raise SystemExit(
+                f"--format {args.format!r} conflicts with --output suffix {args.output.suffix!r}."
+            )
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        _write_patients(args.output, patients, output_format)
+        outputs = [args.output]
+    else:
+        destination = args.destination or Path(".")
+        output_format = args.format or "both"
+        destination.mkdir(parents=True, exist_ok=True)
+        outputs = _write_destination(destination, patients, output_format)
+    print("Generated", args.count, "patients:", ", ".join(str(path) for path in outputs))
+    return 0
+
+
+def _format_from_output_path(path: Path) -> str:
+    suffix = path.suffix.lower()
+    if suffix == ".json":
+        return "json"
+    if suffix == ".jsonl":
+        return "jsonl"
+    raise SystemExit("--output must end in .json or .jsonl.")
+
+
+def _write_destination(destination: Path, patients: list[dict], output_format: str) -> list[Path]:
+    outputs: list[Path] = []
+    if output_format in {"json", "both"}:
+        path = destination / "patients.json"
+        path.write_text(json.dumps(patients, indent=2) + "\n", encoding="utf-8")
+        outputs.append(path)
+    if output_format in {"jsonl", "both"}:
+        path = destination / "patients.jsonl"
+        _write_patients(path, patients, "jsonl")
+        outputs.append(path)
+    return outputs
+
+
+def _write_patients(path: Path, patients: list[dict], output_format: str) -> None:
+    if output_format == "json":
+        path.write_text(json.dumps(patients, indent=2) + "\n", encoding="utf-8")
+        return
+    with path.open("w", encoding="utf-8") as handle:
+        for patient in patients:
+            handle.write(json.dumps(patient) + "\n")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

toxsim/simulator.py

@@ -0,0 +1,553 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+from uuid import UUID
+
+import numpy as np
+import yaml
+from scipy.stats import truncnorm
+
+
+class ModelDataError(ValueError):
+    """Raised when synthetic-patient model configuration cannot be loaded."""
+
+
+@dataclass(frozen=True)
+class ModelData:
+    """Predictive variables and their corresponding scoring tables."""
+
+    predictive_variables: tuple[dict[str, Any], ...]
+    scores: Mapping[str, dict[str, Any]]
+
+
+@dataclass
+class _Context:
+    intoxicant: str | None = None
+    severity: int | None = None
+    gcs: int | None = None
+    respiratory: str | None = None
+    dysrhythmia: str | None = None
+    hr_true: int | None = None
+    sbp_true: int | None = None
+
+
+def load_model_data(model_data_dir: str | Path | None = None) -> ModelData:
+    """Load model YAML data from a directory or packaged resources."""
+    if model_data_dir is None:
+        root = resources.files("toxsim").joinpath("data", "model")
+        source = "packaged toxsim model data"
+    else:
+        root = Path(model_data_dir).expanduser()
+        source = f"model-data directory {root}"
+
+    predictive_path = root.joinpath("predictive_variables.yml")
+    if not predictive_path.is_file():
+        raise ModelDataError(
+            f"Could not find predictive_variables.yml in {source}. "
+            "Provide a directory containing predictive_variables.yml and one "
+            "<variable-name>_score.yml file for every predictive variable, "
+            "for example load_model_data('/path/to/model-data') or "
+            "toxsim-generate --model-data-dir /path/to/model-data."
+        )
+
+    predictive_variables = _load_yaml_list(predictive_path)
+    scores: dict[str, dict[str, Any]] = {}
+    for variable in predictive_variables:
+        name = variable.get("name")
+        if not isinstance(name, str) or not name:
+            raise ModelDataError(
+                f"{predictive_path} contains a variable without a non-empty string name."
+            )
+        score_path = root.joinpath(f"{name}_score.yml")
+        if not score_path.is_file():
+            raise ModelDataError(
+                f"Missing score file {name}_score.yml in {source}. "
+                "Supply a score YAML file for every predictive variable."
+            )
+        score = _load_yaml_mapping(score_path)
+        if "criteria" not in score or "values" not in score:
+            raise ModelDataError(f"{score_path} must define 'criteria' and 'values'.")
+        scores[name] = score
+
+    return ModelData(tuple(predictive_variables), scores)
+
+
+def create_patient(
+    predictive_variables: ModelData | Sequence[Mapping[str, Any]] | None = None,
+    scores: Mapping[str, Mapping[str, Any]] | None = None,
+    *,
+    model_data: ModelData | None = None,
+    model_data_dir: str | Path | None = None,
+    seed: int | None = None,
+    rng: np.random.Generator | None = None,
+) -> dict[str, Any]:
+    """Create one context-aware synthetic patient.
+
+    With no model arguments, bundled model data is loaded lazily. To provide
+    custom data, pass either *model_data*, *model_data_dir*, or both
+    *predictive_variables* and *scores*. Passing a :class:`ModelData` as the
+    first positional argument is retained for compatibility.
+
+    Supply either *seed* or *rng*, not both. A seed makes all generated fields,
+    including the patient ID, deterministic.
+    """
+    resolved_model_data = _resolve_model_data(
+        predictive_variables=predictive_variables,
+        scores=scores,
+        model_data=model_data,
+        model_data_dir=model_data_dir,
+    )
+    generator = _resolve_rng(seed, rng)
+    variables = _variables_by_name(resolved_model_data)
+    order = _generation_order(variables)
+
+    for _ in range(10):
+        context = _Context()
+        presentation = [
+            _create_feature(variables[name], context, resolved_model_data.scores, generator)
+            for name in order
+        ]
+        if _plausible(context, generator):
+            return {
+                "presentation": presentation,
+                "patient_id": str(_random_uuid(generator)),
+                "extras": {
+                    "severity": context.severity,
+                    "hr_true": context.hr_true,
+                    "sbp_true": context.sbp_true,
+                },
+                "risk": int(sum(feature["score"] for feature in presentation)),
+            }
+
+    # The tenth sample remains valid even if it failed a probabilistic
+    # plausibility screen; rejecting it would needlessly hide a valid patient.
+    return {
+        "presentation": presentation,
+        "patient_id": str(_random_uuid(generator)),
+        "extras": {
+            "severity": context.severity,
+            "hr_true": context.hr_true,
+            "sbp_true": context.sbp_true,
+        },
+        "risk": int(sum(feature["score"] for feature in presentation)),
+    }
+
+
+def create_patients(
+    model_data: ModelData | None = None,
+    count: int = 1,
+    *,
+    predictive_variables: Sequence[Mapping[str, Any]] | None = None,
+    scores: Mapping[str, Mapping[str, Any]] | None = None,
+    model_data_dir: str | Path | None = None,
+    seed: int | None = None,
+    rng: np.random.Generator | None = None,
+) -> list[dict[str, Any]]:
+    """Create *count* patients using bundled or explicitly supplied model data.
+
+    The model source arguments have the same behavior as :func:`create_patient`.
+    Supplying *model_data* positionally remains compatible with earlier releases.
+    """
+    if count < 0:
+        raise ValueError("count must be non-negative.")
+    resolved_model_data = _resolve_model_data(
+        predictive_variables=predictive_variables,
+        scores=scores,
+        model_data=model_data,
+        model_data_dir=model_data_dir,
+    )
+    generator = _resolve_rng(seed, rng)
+    return [create_patient(resolved_model_data, rng=generator) for _ in range(count)]
+
+
+def score_from_value(value: Any, score_table: Mapping[str, Any]) -> int:
+    """Return the score associated with a categorical or ranged value."""
+    criteria = score_table["criteria"]
+    values = score_table["values"]
+    if criteria == "categorical":
+        normalized = _normalize_bool(value)
+        for item in values:
+            if normalized == item["name"]:
+                return int(item["score"])
+        raise ValueError(f"Value {value!r} is not in the categorical score table.")
+    if criteria == "range":
+        for item in values:
+            if float(item["min"]) <= float(value) <= float(item["max"]):
+                return int(item["score"])
+        raise ValueError(f"Value {value!r} is not in the range score table.")
+    raise ValueError(f"Unknown score criteria: {criteria!r}.")
+
+
+def _load_yaml_list(path: Any) -> list[dict[str, Any]]:
+    with path.open("r", encoding="utf-8") as handle:
+        data = yaml.safe_load(handle)
+    if not isinstance(data, list) or not all(isinstance(item, dict) for item in data):
+        raise ModelDataError(f"{path} must contain a YAML list of variable mappings.")
+    return data
+
+
+def _load_yaml_mapping(path: Any) -> dict[str, Any]:
+    with path.open("r", encoding="utf-8") as handle:
+        data = yaml.safe_load(handle)
+    if not isinstance(data, dict):
+        raise ModelDataError(f"{path} must contain a YAML mapping.")
+    return data
+
+
+def _resolve_rng(
+    seed: int | None, rng: np.random.Generator | None
+) -> np.random.Generator:
+    if seed is not None and rng is not None:
+        raise ValueError("Pass either seed or rng, not both.")
+    return rng if rng is not None else np.random.default_rng(seed)
+
+
+def _resolve_model_data(
+    *,
+    predictive_variables: ModelData | Sequence[Mapping[str, Any]] | None,
+    scores: Mapping[str, Mapping[str, Any]] | None,
+    model_data: ModelData | None,
+    model_data_dir: str | Path | None,
+) -> ModelData:
+    has_explicit_tables = predictive_variables is not None or scores is not None
+    if model_data is not None:
+        if has_explicit_tables or model_data_dir is not None:
+            raise ModelDataError(
+                "Pass only one model source: model_data, model_data_dir, or "
+                "predictive_variables with scores."
+            )
+        return model_data
+    if isinstance(predictive_variables, ModelData):
+        if scores is not None or model_data_dir is not None:
+            raise ModelDataError(
+                "A positional ModelData cannot be combined with scores or model_data_dir."
+            )
+        return predictive_variables
+    if has_explicit_tables:
+        if model_data_dir is not None:
+            raise ModelDataError(
+                "Pass either model_data_dir or predictive_variables with scores, not both."
+            )
+        if predictive_variables is None or scores is None:
+            raise ModelDataError(
+                "Explicit model data requires both predictive_variables and scores."
+            )
+        return ModelData(
+            tuple(dict(variable) for variable in predictive_variables),
+            {name: dict(score) for name, score in scores.items()},
+        )
+    return load_model_data(model_data_dir)
+
+
+def _variables_by_name(model_data: ModelData) -> dict[str, dict[str, Any]]:
+    variables: dict[str, dict[str, Any]] = {}
+    for variable in model_data.predictive_variables:
+        name = variable.get("name")
+        if not isinstance(name, str) or not name:
+            raise ModelDataError(
+                "Every predictive variable must have a non-empty string name."
+            )
+        if name in variables:
+            raise ModelDataError(f"Duplicate predictive variable name: {name}.")
+        if name not in model_data.scores:
+            raise ModelDataError(
+                f"No score table was supplied for predictive variable {name}."
+            )
+        variables[name] = variable
+    return variables
+
+
+def _generation_order(variables: Mapping[str, dict[str, Any]]) -> list[str]:
+    contextual = [
+        "intoxicant",
+        "age",
+        "cirrhosis",
+        "second_diagnose",
+        "gcs",
+        "respiratory",
+        "dysrhythmia",
+        "hr",
+        "sbp",
+    ]
+    return [name for name in contextual if name in variables] + [
+        name for name in variables if name not in contextual
+    ]
+
+
+def _create_feature(
+    variable: Mapping[str, Any],
+    context: _Context,
+    scores: Mapping[str, Mapping[str, Any]],
+    rng: np.random.Generator,
+) -> dict[str, Any]:
+    name = variable["name"]
+    value, true_value = _simulate_value_with_context(variable, context, scores, rng)
+    feature: dict[str, Any] = {
+        "name": name,
+        "value": value,
+        "score": score_from_value(value, scores[name]),
+    }
+    if variable["type"] == "categorical":
+        feature["in_original_range"] = True
+    else:
+        feature["true_value"] = true_value
+        feature["in_original_range"] = _is_value_in_range(true_value, variable)
+        feature["model_range"] = {
+            "min": float(variable["allowed_values"]["min"]),
+            "max": float(variable["allowed_values"]["max"]),
+        }
+    return feature
+
+
+def _simulate_value_with_context(
+    variable: Mapping[str, Any],
+    context: _Context,
+    scores: Mapping[str, Mapping[str, Any]],
+    rng: np.random.Generator,
+) -> tuple[Any, Any]:
+    name = variable["name"]
+    if name == "intoxicant":
+        value = _simulate_categorical(variable, rng)
+        context.intoxicant = str(value)
+        return value, None
+    if name == "age":
+        bounds = variable["allowed_values"]
+        value = int(
+            round(
+                int(bounds["min"])
+                + rng.beta(2.2, 3.0) * (int(bounds["max"]) - int(bounds["min"]))
+            )
+        )
+        return value, value
+
+    if context.severity is None and context.intoxicant is not None:
+        context.severity = _sample_severity(context.intoxicant, rng)
+
+    intoxicant = context.intoxicant or "Polysubstance"
+    severity = context.severity if context.severity is not None else 1
+    if name == "gcs":
+        value = _sample_gcs_from_bins(scores["gcs"], intoxicant, severity, rng)
+        context.gcs = value
+        return value, value
+    if name == "respiratory":
+        value = _sample_respiratory(context.gcs or 15, intoxicant, severity, rng)
+        context.respiratory = value
+        return value, None
+    if name == "dysrhythmia":
+        value = _sample_dysrhythmia(intoxicant, severity, rng)
+        context.dysrhythmia = value
+        return value, None
+    if name == "hr":
+        true_value = _sample_hr_true(
+            intoxicant,
+            severity,
+            context.dysrhythmia or "No",
+            context.respiratory or "No",
+            rng,
+        )
+        value = int(true_value)
+        context.hr_true = value
+        return value, true_value
+    if name == "sbp":
+        true_value = _sample_sbp_true(intoxicant, severity, context.hr_true or 90, rng)
+        value = int(round(true_value / 2.0) * 2)
+        context.sbp_true = value
+        return value, true_value
+
+    if variable["type"] == "categorical":
+        return _simulate_categorical(variable, rng), None
+    if variable["type"] == "continuous":
+        value = _simulate_continuous(variable, rng)
+        return value, value
+    raise ValueError(f"Unknown variable type: {variable.get('type')!r}.")
+
+
+def _simulate_categorical(variable: Mapping[str, Any], rng: np.random.Generator) -> Any:
+    distribution = variable.get("dist")
+    if distribution:
+        options = [item["value"] for item in distribution]
+        probabilities = [float(item["probability"]) for item in distribution]
+        return _normalize_bool(_weighted_choice(options, probabilities, rng))
+    return _normalize_bool(rng.choice(variable["allowed_values"]).item())
+
+
+def _simulate_continuous(variable: Mapping[str, Any], rng: np.random.Generator) -> int:
+    bounds = variable["allowed_values"]
+    low, high = float(bounds["min"]), float(bounds["max"])
+    return _truncnorm_int(low, high, (low + high) / 2.0, (high - low) / 6.0, rng)
+
+
+def _sample_severity(intoxicant: str, rng: np.random.Generator) -> int:
+    probabilities = {
+        "Alcohol": [0.60, 0.25, 0.12, 0.03],
+        "Analgesic": [0.45, 0.28, 0.18, 0.09],
+        "Antidepressant": [0.45, 0.30, 0.18, 0.07],
+        "Street Drugs": [0.45, 0.30, 0.17, 0.08],
+        "Sedatives": [0.40, 0.28, 0.22, 0.10],
+        "CO, As, CN": [0.35, 0.30, 0.22, 0.13],
+        "Toxins NOS": [0.45, 0.30, 0.18, 0.07],
+        "Polysubstance": [0.30, 0.30, 0.25, 0.15],
+    }.get(intoxicant, [0.45, 0.30, 0.18, 0.07])
+    return int(_weighted_choice([0, 1, 2, 3], probabilities, rng))
+
+
+def _sample_gcs_from_bins(
+    score_table: Mapping[str, Any],
+    intoxicant: str,
+    severity: int,
+    rng: np.random.Generator,
+) -> int:
+    bins = sorted(score_table["values"], key=lambda item: item["max"], reverse=True)
+    probabilities = np.array(
+        {
+            0: [0.82, 0.14, 0.03, 0.01],
+            1: [0.55, 0.28, 0.12, 0.05],
+            2: [0.28, 0.35, 0.22, 0.15],
+            3: [0.06, 0.22, 0.34, 0.38],
+        }[severity],
+        dtype=float,
+    )
+    if intoxicant in {"Sedatives", "Analgesic", "Alcohol", "Polysubstance"}:
+        probabilities *= [0.85, 1.10, 1.15, 1.25]
+    elif intoxicant == "Street Drugs":
+        probabilities *= [1.10, 1.05, 0.90, 0.80]
+    selected = _weighted_choice(bins, probabilities, rng)
+    return int(rng.integers(int(selected["min"]), int(selected["max"]) + 1))
+
+
+def _sample_respiratory(
+    gcs: int, intoxicant: str, severity: int, rng: np.random.Generator
+) -> str:
+    probability = 0.05 + 0.07 * severity
+    if gcs <= 8:
+        probability += 0.45
+    if gcs <= 6:
+        probability += 0.20
+    if intoxicant in {"Sedatives", "Analgesic", "Alcohol", "Polysubstance"}:
+        probability += 0.12
+    if intoxicant == "CO, As, CN":
+        probability += 0.05
+    return "Yes" if rng.random() < min(probability, 0.95) else "No"
+
+
+def _sample_dysrhythmia(
+    intoxicant: str, severity: int, rng: np.random.Generator
+) -> str:
+    probability = 0.06 + 0.06 * severity
+    if intoxicant in {"Antidepressant", "Street Drugs", "CO, As, CN"}:
+        probability += 0.10
+    if intoxicant == "Polysubstance":
+        probability += 0.07
+    return "Yes" if rng.random() < min(probability, 0.60) else "No"
+
+
+def _sample_hr_true(
+    intoxicant: str,
+    severity: int,
+    dysrhythmia: str,
+    respiratory: str,
+    rng: np.random.Generator,
+) -> int:
+    abnormal_mean = {
+        "Street Drugs": 145,
+        "Antidepressant": 120,
+        "Sedatives": 62,
+        "Analgesic": 62,
+        "Alcohol": 62,
+    }.get(intoxicant, 110)
+    probability = 0.10 + 0.15 * severity
+    if dysrhythmia == "Yes":
+        probability += 0.20
+    if respiratory == "Yes":
+        probability += 0.10
+    mean, deviation = (
+        (abnormal_mean, 28) if rng.random() < min(probability, 0.90) else (85, 12)
+    )
+    return int(round(np.clip(rng.normal(mean, deviation), 40, 250)))
+
+
+def _sample_sbp_true(
+    intoxicant: str, severity: int, hr: int, rng: np.random.Generator
+) -> int:
+    mean = 125.0
+    if intoxicant == "Street Drugs":
+        mean += 18
+    if intoxicant in {"Sedatives", "Analgesic", "Alcohol"}:
+        mean -= 10
+    if intoxicant == "Polysubstance":
+        mean -= 6
+    mean -= 9 * severity
+    if severity >= 2 and hr >= 140:
+        mean -= 6
+    return int(round(np.clip(rng.normal(mean, 14 + 6 * severity), 60, 220)))
+
+
+def _plausible(context: _Context, rng: np.random.Generator) -> bool:
+    if (
+        context.gcs is None
+        or context.respiratory is None
+        or context.hr_true is None
+        or context.sbp_true is None
+    ):
+        return True
+    if context.gcs <= 6 and context.respiratory == "No":
+        return bool(rng.random() < 0.25)
+    if context.respiratory == "Yes" and context.gcs >= 14:
+        return bool(rng.random() < 0.20)
+    if context.sbp_true <= 80 and context.hr_true <= 55:
+        return bool(rng.random() < 0.30)
+    return True
+
+
+def _truncnorm_int(
+    low: float, high: float, mean: float, deviation: float, rng: np.random.Generator
+) -> int:
+    deviation = max(deviation, 1e-6)
+    value = truncnorm.rvs(
+        (low - mean) / deviation,
+        (high - mean) / deviation,
+        loc=mean,
+        scale=deviation,
+        random_state=rng,
+    )
+    return int(round(value))
+
+
+def _weighted_choice(
+    options: Sequence[Any], probabilities: Sequence[float], rng: np.random.Generator
+) -> Any:
+    weights = np.asarray(probabilities, dtype=float)
+    if (
+        len(options) != len(weights)
+        or not len(options)
+        or np.any(weights < 0)
+        or weights.sum() <= 0
+    ):
+        raise ValueError(
+            "Options and non-negative probabilities with a positive sum are required."
+        )
+    index = rng.choice(len(options), p=weights / weights.sum())
+    return options[int(index)]
+
+
+def _is_value_in_range(value: Any, variable: Mapping[str, Any]) -> bool:
+    if value is None:
+        return True
+    bounds = variable["allowed_values"]
+    return float(bounds["min"]) <= float(value) <= float(bounds["max"])
+
+
+def _normalize_bool(value: Any) -> Any:
+    if isinstance(value, (bool, np.bool_)):
+        return "Yes" if value else "No"
+    return value
+
+
+def _random_uuid(rng: np.random.Generator) -> UUID:
+    raw = bytearray(rng.bytes(16))
+    raw[6] = (raw[6] & 0x0F) | 0x40
+    raw[8] = (raw[8] & 0x3F) | 0x80
+    return UUID(bytes=bytes(raw))

toxsim-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.5
+Name: toxsim
+Version: 0.1.0
+Summary: Context-aware synthetic poisoned-patient simulator
+Author: toxsim contributors
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scipy>=1.9
+Provides-Extra: cli
+Requires-Dist: rich>=13.0; extra == 'cli'
+Requires-Dist: tqdm>=4.64; extra == 'cli'
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# toxsim
+
+`toxsim` generates context-aware synthetic poisoned-patient presentations. It
+ports the latent-severity behavior from INTOXICATE: intoxication class affects
+severity, which in turn influences GCS, respiratory failure, dysrhythmia, heart
+rate, and systolic blood pressure.
+
+## Installation
+
+```shell
+python -m pip install toxsim
+# Include optional progress and rich CLI output:
+python -m pip install "toxsim[cli]"
+```
+
+## Model data
+
+The package includes the canonical clinical model configuration as package
+data, including `predictive_variables.yml`, each variable's score file, and
+`model.schema.yml`. `load_model_data()` uses these resources by default and
+never depends on the current working directory.
+
+```text
+toxsim/data/
+  model.schema.yml
+  model/
+  predictive_variables.yml
+  <variable-name>_score.yml
+```
+
+Pass a directory to `load_model_data()` or `toxsim-generate
+--model-data-dir` to override the bundled model with a compatible
+configuration. An override directory contains `predictive_variables.yml` and
+one `<variable-name>_score.yml` file for every predictive variable.
+
+## Python API
+
+```python
+from toxsim import create_patient, create_patients
+
+patient = create_patient(seed=2026)
+patients = create_patients(count=100, seed=2026)
+```
+
+Both functions lazily load the bundled model data by default. A seed produces
+the same patient data across runs, including the generated patient ID. Each
+presentation entry has `name`, `value`, and `score`; continuous variables also
+include the model range and whether its underlying value was within that range.
+The patient-level `risk` equals the sum of presentation scores.
+
+To use a compatible external model directory, pass
+`model_data_dir="/path/to/model-data"`. Advanced callers can use
+`create_patient(predictive_variables=variables, scores=score_tables)` or load
+once with `model = load_model_data(...)` and pass that `ModelData` object as
+the first argument to `create_patient(model)` or `create_patients(model,
+count=100)`.
+
+## CLI
+
+```shell
+toxsim-generate \
+  --count 100 \
+  --output patients.jsonl \
+  --seed 2026
+```
+
+`--output` writes one file and infers the format from its `.json` or `.jsonl`
+suffix. To generate named default files in a directory instead, use
+`--destination ./generated --format both`; `--format` accepts `json`, `jsonl`,
+or `both` (the default). Add `--model-data-dir /path/to/model-data` to use a
+compatible override.

toxsim-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+toxsim/__init__.py,sha256=mXu6S4WfBYLxT74hF31HxOoEwR-nxsXyshc-SOyWpm4,296
+toxsim/generate.py,sha256=Mt6OpqLqlxc5UW-zPrWOsrF0Xies3xdMt2b-KfhQGWI,3789
+toxsim/simulator.py,sha256=EI6vsqTwn3DyrXTgEGf8ZKnPgOn9nGKjdwKTeazVWzg,19557
+toxsim/data/model.schema.yml,sha256=jwvHuz9KIk8GMYtv2CJdLN0reo_WM5Xya4bmqW-1pIQ,192
+toxsim/data/model/age_score.yml,sha256=sZQYyVz7K89EUIMGSkBAXH8Yor2718f2ggiHlaiKT9Y,521
+toxsim/data/model/cirrhosis_score.yml,sha256=UOQ6aTeOCPNuvSeojDRmHE2vsyKQyZ9Y3knvMCyu9Pg,138
+toxsim/data/model/dysrhythmia_score.yml,sha256=FUCK4Muof8AsyLs-4iZGqVT6N80XtES-lkd5tWYFax4,138
+toxsim/data/model/gcs_score.yml,sha256=x87IvJs5jWGxx4rHxhGA0TSed0M_pb5Wygd8YtzFV00,344
+toxsim/data/model/hr_score.yml,sha256=Afhrn8FC6runSoc5q0xxaGwlc7Ah4Ly4bRRbwoc6dhE,442
+toxsim/data/model/intoxicant_score.yml,sha256=c42v1CkOiEm0kylCQSlte_O9gepTnohBX2bteSY0Fs8,565
+toxsim/data/model/predictive_variables.yml,sha256=s7ybFOLSS1uJsNbVkTWeMUJsn6K2iBHJFdHQHWH2lps,1434
+toxsim/data/model/respiratory_score.yml,sha256=xBuOzlj8hUiDHHiyR-nBC_M3d8rz0e-0omq2GuKKTnw,138
+toxsim/data/model/sbp_score.yml,sha256=LMbS_nS9IErLozLvJcxBx1-FHvuSikL8uMX9uKRAOVg,546
+toxsim/data/model/second_diagnose_score.yml,sha256=UOQ6aTeOCPNuvSeojDRmHE2vsyKQyZ9Y3knvMCyu9Pg,138
+toxsim-0.1.0.dist-info/METADATA,sha256=si4dky_PONyYKkDn6p16REbAW36SiCihhO9IY6ssFWI,2889
+toxsim-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+toxsim-0.1.0.dist-info/entry_points.txt,sha256=KvCTTi4nZbxwn8O62XN461aFER-uPMp6zIvKxdfyhNI,57
+toxsim-0.1.0.dist-info/RECORD,,

toxsim-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

toxsim-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+toxsim-generate = toxsim.generate:main