Hosp Code

Hosp Code

Overview

Use this skill to turn research code into a hospital-ready handoff package that can run outside the developer's machine, explain exactly what the hospital must edit, protect sensitive row-level data, and produce reproducible clinical AI outputs.

For detailed acceptance criteria, read references/hospital-code-delivery-checklist.md when auditing a package, designing a new package, or investigating hospital feedback.

Workflow

1. Identify the task mode:
   • Package or retrofit: modify code/docs so the bundle can run at the hospital.
   • Audit: compare an existing package against the checklist and report gaps by severity.
   • Debug feedback: triage a hospital error from logs, preflight output, and used config.
2. Inspect the current bundle before editing. Locate the entrypoint, README, requirements, config template, input templates, experiment inventory, output folders, and any local absolute paths.
3. Keep the handoff contract narrow: one documented entrypoint, config-driven paths, no developer-machine assumptions, and clear boundaries between local sensitive inputs and returnable de-identified results.
4. Implement the smallest changes needed to satisfy the contract. Preserve existing scientific logic unless the user explicitly asks to redesign experiments.
5. Validate with compilation, preflight or dry-run where available, README/config consistency checks, and sensitive-output checks.
6. Report exactly what changed, what command the hospital should run, what version string should appear in logs, and any remaining limitations.

Non-Negotiables

• Provide a single main entrypoint such as run_all.py.
• Route all hospital-specific paths through config files such as config_template.json and config_hospital.json.
• Put the hospital's required edits at the top of the README: what to fill, environment setup, and run command.
• Print a package version at startup and write the same version into used_config.json.
• Run preflight before real experiments and write preflight_check.txt plus used_config.json.
• Make long runs observable with [INFO], [RUN], [DONE], [WARN], and [ERROR] logs, including heartbeat messages for slow steps and a clear final completion signal.
• Write FAILED_STEP_README.txt on fatal failure when practical.
• Treat To_hospital/ as a sensitive local sandbox and keep returnable result folders de-identified by default.
• Treat To_hospital_sensitive_do_not_return/ as a hospital-internal retention and verification directory that must not be sent back with result folders.
• Default to retain_sensitive_row_level_outputs=false unless the hospital explicitly enables local debugging output.
• Avoid Python 3.9+ assumptions and fragile dependency choices when the hospital may run Python 3.8 or older pandas/sklearn.

README Requirements

Put these as the first three README sections:

1. What the hospital must fill in or modify.
2. Environment setup.
3. Run command.

Include the exact clinical info file name, required columns, optional/recommended columns, fields the hospital should not edit, config keys to change, and the shortest command, for example:

python run_all.py --config config_hospital.json

If the package starts from de-identified feature tables rather than raw audio, ASR, or feature extraction, say so explicitly near the top.

Package Structure

Prefer a handoff package containing:

• README_医院交接说明.md or an equivalent README.
• run_all.py or one documented main entrypoint.
• requirements.txt.
• config_template.json.
• config_hospital.json if safe to include without real secrets or paths.
• An input template such as ID_info.xlsx.
• hospital_code_experiment_inventory.md or an equivalent code/experiment inventory.
• The project SOP or a pointer to it when useful.

Do not include local test outputs, __pycache__, result folders, or sensitive hospital data in the zip.

Preflight And Logging

Before modeling or analysis, preflight must check Python version, key dependency versions, required input files, required columns, sample ID columns, non-empty target columns, and missing recommended fields.

Error messages should tell the hospital which file or field is missing, which log to read first, and which artifacts to send back for debugging.

For each major step:

• Print [RUN] step name before it starts.
• Print [DONE] step name (xxs) after it succeeds, where xxs is elapsed time.
• If a step runs longer than 60 seconds, print [INFO] Still running: step name (xxs elapsed) every 60 seconds until it finishes.
• After all analyses finish, print [DONE] ALL ANALYSES COMPLETED as a highly visible final success signal.
• Print [INFO] package version at startup.
• Emit JSON summaries from child scripts when practical.

Sensitive Output Rules

Separate local sensitive data from returnable results:

• To_hospital/ may contain hospital-local ID_info and merged feature/clinical tables.
• To_hospital_sensitive_do_not_return/ is for hospital-local retention and verification only. It must not be bundled with returnable result directories.
• If present, To_hospital_sensitive_do_not_return/ should contain task_feature_info_merged_for_hospital_internal_use.csv, README_DO_NOT_RETURN.txt, and internal_archive_manifest.json.
• Result directories must not retain raw IDs, names, clinical details, or identifiable row-level tables by default.
• Per-subject predictions should use IDs such as anon_subject_id.
• Returnable row-level files should include no_id in filenames when applicable.
• Clean intermediate files that include ID fields before finishing unless local debugging output was explicitly requested.

In the README, state which directories can be sent back and which must stay inside the hospital. Explicitly mark To_hospital_sensitive_do_not_return/ as non-returnable.

Medical AI Experiment Scope

When the goal is a publishable medical AI analysis, make the experiment inventory distinguish:

• Cohort definitions and inclusion/exclusion rules.
• Internal CV, nested CV, temporal/site/device split, and external validation.
• Exploratory feature selection versus locked validation performance.
• Clinical baselines, traditional task scores, AI features, and combined models.
• Classification metrics, regression metrics, calibration, clinical utility, interpretability, subgroup fairness, missingness, and reproducibility artifacts.

Do not let optional modules such as SHAP, large visual reports, or long sensitivity analyses block the main run. They should write status files when unavailable.

Validation Before Handoff

Run the strongest checks available in the repo:

python -m py_compile path/to/script.py
python run_all.py --config config_hospital.json

If full execution is too expensive or needs real hospital data, prefer a --dry-run or preflight-only mode when it exists. Also inspect the final zip or folder for the latest version string, required templates, README order, requirements, config files, and absence of sensitive outputs.

Hospital Error Triage

When the hospital reports a failure, ask first for:

• Complete run log.
• First log line showing package version.
• preflight_check.txt.
• used_config.json.
• FAILED_STEP_README.txt.

Triage in this order: stale package version, path quoting or spaces, old Python/pandas/sklearn, missing fields or empty target columns, renamed or moved input files, missing optional dependencies, then sensitive files accidentally written into returnable results.