Add README.md

README.md

@@ -0,0 +1,178 @@
+---
+library_name: pytorch
+license: mit
+tags:
+  - tabular
+  - structured-data
+  - binary-classification
+  - medical
+  - autism
+  - screening
+language:
+  - en
+metrics:
+  - accuracy
+  - f1
+  - roc_auc
+---
+
+# Autism Spectrum Disorder Screening Model
+
+## Model Description
+
+A feedforward neural network for autism spectrum disorder (ASD) risk screening using 8 structured clinical input features.
+
+**Important:** This is a screening tool, NOT a diagnostic instrument. Results must be interpreted by qualified healthcare professionals.
+
+## Intended Use
+
+- **Primary use:** Clinical decision support for ASD screening
+- **Users:** Healthcare professionals, clinical software systems
+- **Out of scope:** Self-diagnosis, definitive diagnosis
+
+## Input Features
+
+| Field | Type | Valid Values | Description |
+|-------|------|--------------|-------------|
+| `developmental_milestones` | categorical | `N`, `G`, `M`, `C` | Normal, Global delay, Motor delay, Cognitive delay |
+| `iq_dq` | numeric | 20-150 | IQ or Developmental Quotient |
+| `intellectual_disability` | categorical | `N`, `F70.0`, `F71`, `F72` | None, Mild, Moderate, Severe (ICD-10) |
+| `language_disorder` | binary | `N`, `Y` | No / Yes |
+| `language_development` | categorical | `N`, `delay`, `A` | Normal, Delayed, Absent |
+| `dysmorphism` | binary | `NO`, `Y` | No / Yes |
+| `behaviour_disorder` | binary | `N`, `Y` | No / Yes |
+| `neurological_exam` | text | non-empty string | `N` for normal, or description |
+
+## Output
+
+```json
+{
+  "prediction": "Healthy" | "ASD",
+  "probability": 0.0-1.0,
+  "risk_level": "low" | "medium" | "high"
+}
+```
+
+### Risk Level Thresholds
+- **Low:** probability < 0.4
+- **Medium:** 0.4 ≤ probability < 0.7
+- **High:** probability ≥ 0.7
+
+## How to Use
+
+```python
+import json
+import torch
+from pathlib import Path
+from huggingface_hub import snapshot_download
+
+# Download model
+model_dir = Path(snapshot_download("toderian/autism-detector"))
+
+# Load config
+with open(model_dir / "preprocessor_config.json") as f:
+    preprocess_config = json.load(f)
+
+# Load model
+model = torch.jit.load(model_dir / "autism_detector_traced.pt")
+model.eval()
+
+# Preprocessing function
+def preprocess(data, config):
+    features = []
+    for feature_name in config["feature_order"]:
+        if feature_name in config["categorical_features"]:
+            feat_config = config["categorical_features"][feature_name]
+            if feat_config["type"] == "text_binary":
+                value = 0 if data[feature_name].upper() == feat_config["normal_value"] else 1
+            else:
+                value = feat_config["mapping"][data[feature_name]]
+        else:
+            feat_config = config["numeric_features"][feature_name]
+            raw = float(data[feature_name])
+            value = (raw - feat_config["min"]) / (feat_config["max"] - feat_config["min"])
+        features.append(value)
+    return torch.tensor([features], dtype=torch.float32)
+
+# Example inference
+input_data = {
+    "developmental_milestones": "N",
+    "iq_dq": 85,
+    "intellectual_disability": "N",
+    "language_disorder": "N",
+    "language_development": "N",
+    "dysmorphism": "NO",
+    "behaviour_disorder": "N",
+    "neurological_exam": "N"
+}
+
+input_tensor = preprocess(input_data, preprocess_config)
+with torch.no_grad():
+    output = model(input_tensor)
+    probs = torch.softmax(output, dim=-1)
+    asd_probability = probs[0, 1].item()
+
+print(f"ASD Probability: {asd_probability:.2%}")
+print(f"Prediction: {'ASD' if asd_probability > 0.5 else 'Healthy'}")
+```
+
+## Training Details
+
+- **Dataset:** 315 ASD patients + 100 healthy controls (415 total)
+- **Preprocessing:** Min-max normalization for numeric, label encoding for categorical
+- **Architecture:** Feedforward NN (input → 64 → 32 → 2)
+- **Loss:** Cross-entropy
+- **Optimizer:** Adam (lr=0.001)
+
+## Evaluation
+
+| Metric | Value |
+|--------|-------|
+| Accuracy | 0.9759 |
+| F1 Score | 0.9839 |
+| ROC-AUC | 0.9913 |
+| Sensitivity | 0.9683 |
+| Specificity | 1.0000 |
+
+### Confusion Matrix (Test Set, n=83)
+
+|  | Predicted Healthy | Predicted ASD |
+|--|-------------------|---------------|
+| Actual Healthy | 20 | 0 |
+| Actual ASD | 2 | 61 |
+
+## Limitations
+
+- Trained on limited dataset (415 samples)
+- Healthy controls are synthetically generated
+- Not validated across diverse populations
+- Screening tool only, not diagnostic
+- Requires all 8 input fields
+
+## Ethical Considerations
+
+- Results should always be reviewed by qualified professionals
+- Should not be used as sole basis for clinical decisions
+- Model performance may vary across different populations
+- False negatives (2 in test set) may delay intervention
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `autism_detector_traced.pt` | TorchScript model (load with `torch.jit.load()`) |
+| `config.json` | Model architecture configuration |
+| `preprocessor_config.json` | Feature preprocessing rules (JSON, no pickle) |
+| `model.py` | Model class definition |
+| `requirements.txt` | Python dependencies |
+
+## Citation
+
+```bibtex
+@misc{asd_detector_2026,
+  title={Autism Spectrum Disorder Screening Model},
+  year={2026},
+  publisher={Archicava},
+  url={https://huggingface.co/archicava/autism-detector}
+}
+```