medsci-skills 4.1.0

package/skills/deidentify/locales/_template.json

@@ -0,0 +1,45 @@
+{
+  "_comment": "Template for adding a new country locale to deidentify.py",
+  "_instructions": "Copy this file, rename to {country_code}.json, fill in patterns.",
+
+  "name": "Country Name",
+  "native_name": "Native Name",
+  "code": "xx",
+
+  "national_id": {
+    "label": "National ID Name",
+    "phi_type": "national_id",
+    "patterns": [
+      "REGEX_PATTERN_HERE"
+    ]
+  },
+
+  "phone": [
+    {"label": "Mobile", "pattern": "REGEX_PATTERN_HERE"},
+    {"label": "Landline", "pattern": "REGEX_PATTERN_HERE"}
+  ],
+
+  "address": {
+    "type": "keywords",
+    "keywords": ["Street", "Avenue"],
+    "min_ratio": 0.3
+  },
+
+  "name_heuristic": {
+    "type": "none",
+    "pattern": "",
+    "min_ratio": 0.3,
+    "only_in_name_columns": true
+  },
+
+  "date_formats": [
+    {"pattern": "REGEX_PATTERN_HERE", "label": "Local date format"}
+  ],
+
+  "column_names": {
+    "patient_name": "name",
+    "ssn": "national_id",
+    "phone": "phone",
+    "address": "address"
+  }
+}

package/skills/deidentify/locales/au.json

@@ -0,0 +1,43 @@
+{
+  "name": "Australia",
+  "native_name": "Australia",
+  "code": "au",
+
+  "national_id": {
+    "label": "Tax File Number (TFN) / Medicare Number",
+    "phi_type": "national_id",
+    "patterns": [
+      "\\b\\d{3}\\s?\\d{3}\\s?\\d{3}\\b",
+      "\\b\\d{4}\\s?\\d{5}\\s?\\d{1}\\b"
+    ]
+  },
+
+  "phone": [
+    {"label": "AU Mobile", "pattern": "\\b04\\d{2}\\s?\\d{3}\\s?\\d{3}\\b"},
+    {"label": "AU Landline", "pattern": "\\b0[2378]\\s?\\d{4}\\s?\\d{4}\\b"},
+    {"label": "AU +61", "pattern": "\\b\\+61\\s?4\\d{2}\\s?\\d{3}\\s?\\d{3}\\b"}
+  ],
+
+  "address": {
+    "type": "keywords",
+    "keywords": ["Street", "St", "Road", "Rd", "Avenue", "Ave", "Drive", "Dr", "Crescent", "Cres", "Court", "Ct", "Place", "Pl", "Lane", "Ln"],
+    "min_ratio": 0.3
+  },
+
+  "name_heuristic": {
+    "type": "none",
+    "pattern": "",
+    "min_ratio": 0.3,
+    "only_in_name_columns": true
+  },
+
+  "date_formats": [
+    {"pattern": "\\b(0?[1-9]|[12]\\d|3[01])/(0?[1-9]|1[0-2])/(19|20)\\d{2}\\b", "label": "AU date (DD/MM/YYYY)"}
+  ],
+
+  "column_names": {
+    "tfn": "national_id", "tax_file_number": "national_id",
+    "medicare_number": "national_id", "medicare_no": "national_id",
+    "postcode": "address"
+  }
+}

package/skills/deidentify/locales/ca.json

@@ -0,0 +1,44 @@
+{
+  "name": "Canada",
+  "native_name": "Canada",
+  "code": "ca",
+
+  "national_id": {
+    "label": "Social Insurance Number (SIN)",
+    "phi_type": "national_id",
+    "patterns": [
+      "\\b\\d{3}[- ]?\\d{3}[- ]?\\d{3}\\b"
+    ]
+  },
+
+  "phone": [
+    {"label": "Canadian phone", "pattern": "\\b\\(?\\d{3}\\)?[-.\\s]?\\d{3}[-.\\s]?\\d{4}\\b"},
+    {"label": "Canadian phone +1", "pattern": "\\b\\+?1[-.\\s]?\\(?\\d{3}\\)?[-.\\s]?\\d{3}[-.\\s]?\\d{4}\\b"}
+  ],
+
+  "address": {
+    "type": "keywords",
+    "keywords": ["Street", "St.", "Avenue", "Ave.", "Boulevard", "Blvd.", "Drive", "Dr.", "Road", "Rd.", "Rue", "Chemin"],
+    "postcode_pattern": "\\b[A-Z]\\d[A-Z]\\s?\\d[A-Z]\\d\\b",
+    "min_ratio": 0.3
+  },
+
+  "name_heuristic": {
+    "type": "none",
+    "pattern": "",
+    "min_ratio": 0.3,
+    "only_in_name_columns": true
+  },
+
+  "date_formats": [
+    {"pattern": "\\b(0?[1-9]|[12]\\d|3[01])/(0?[1-9]|1[0-2])/(19|20)\\d{2}\\b", "label": "DD/MM/YYYY"},
+    {"pattern": "\\b(0?[1-9]|1[0-2])/(0?[1-9]|[12]\\d|3[01])/(19|20)\\d{2}\\b", "label": "MM/DD/YYYY"}
+  ],
+
+  "column_names": {
+    "sin": "national_id", "social_insurance": "national_id",
+    "health_card": "national_id", "ohip": "national_id",
+    "postal_code": "address",
+    "numéro_assurance_sociale": "national_id"
+  }
+}

package/skills/deidentify/locales/cn.json

@@ -0,0 +1,47 @@
+{
+  "name": "China",
+  "native_name": "中国",
+  "code": "cn",
+
+  "national_id": {
+    "label": "身份证号 (Citizen ID)",
+    "phi_type": "national_id",
+    "patterns": [
+      "\\b\\d{17}[\\dXx]\\b",
+      "\\b\\d{15}\\b"
+    ]
+  },
+
+  "phone": [
+    {"label": "Mobile", "pattern": "\\b1[3-9]\\d{9}\\b"},
+    {"label": "Landline", "pattern": "\\b0\\d{2,3}-?\\d{7,8}\\b"}
+  ],
+
+  "address": {
+    "type": "suffix_regex",
+    "pattern": "(省|市|区|县|镇|乡|村|街道|路|号|弄|室)",
+    "min_ratio": 0.3
+  },
+
+  "name_heuristic": {
+    "type": "regex",
+    "pattern": "^[\\u4E00-\\u9FFF]{2,4}$",
+    "min_ratio": 0.3,
+    "only_in_name_columns": true
+  },
+
+  "date_formats": [
+    {"pattern": "\\b(19|20)\\d{2}年\\s?(0?[1-9]|1[0-2])月\\s?(0?[1-9]|[12]\\d|3[01])日\\b", "label": "Chinese date (YYYY年MM月DD日)"}
+  ],
+
+  "column_names": {
+    "患者姓名": "name", "姓名": "name", "名字": "name",
+    "身份证号": "national_id", "身份证": "national_id", "证件号": "national_id",
+    "出生日期": "date", "生日": "date",
+    "电话": "phone", "手机": "phone", "联系电话": "phone", "手机号": "phone",
+    "地址": "address", "住址": "address", "家庭住址": "address",
+    "邮箱": "email", "电子邮件": "email",
+    "病历号": "id", "住院号": "id", "门诊号": "id", "患者编号": "id",
+    "医保号": "insurance", "社保号": "insurance"
+  }
+}

package/skills/deidentify/locales/de.json

@@ -0,0 +1,48 @@
+{
+  "name": "Germany",
+  "native_name": "Deutschland",
+  "code": "de",
+
+  "national_id": {
+    "label": "Steuerliche Identifikationsnummer (Tax ID)",
+    "phi_type": "national_id",
+    "patterns": [
+      "\\b\\d{2}\\s?\\d{3}\\s?\\d{3}\\s?\\d{3}\\b"
+    ]
+  },
+
+  "phone": [
+    {"label": "German phone", "pattern": "\\b0\\d{2,5}[/-]?\\d{3,9}\\b"},
+    {"label": "German phone +49", "pattern": "\\b\\+49\\s?\\d{2,5}[/-]?\\d{3,9}\\b"}
+  ],
+
+  "address": {
+    "type": "keywords",
+    "keywords": ["Straße", "Strasse", "Str.", "Weg", "Platz", "Allee", "Gasse", "Ring", "Damm"],
+    "min_ratio": 0.3
+  },
+
+  "name_heuristic": {
+    "type": "none",
+    "pattern": "",
+    "min_ratio": 0.3,
+    "only_in_name_columns": true
+  },
+
+  "date_formats": [
+    {"pattern": "\\b(0?[1-9]|[12]\\d|3[01])\\.(0?[1-9]|1[0-2])\\.(19|20)\\d{2}\\b", "label": "German date (DD.MM.YYYY)"}
+  ],
+
+  "column_names": {
+    "patientenname": "name", "vorname": "name", "nachname": "name",
+    "name": "name", "familienname": "name",
+    "steuer_id": "national_id", "steuernummer": "national_id",
+    "geburtsdatum": "date", "geb_datum": "date",
+    "telefon": "phone", "telefonnummer": "phone", "handy": "phone", "mobilnummer": "phone",
+    "adresse": "address", "anschrift": "address", "wohnort": "address", "plz": "address",
+    "postleitzahl": "address",
+    "e_mail": "email",
+    "patientennummer": "id", "fallnummer": "id", "krankenhaus_id": "id",
+    "versichertennummer": "insurance", "krankenversicherung": "insurance"
+  }
+}

package/skills/deidentify/locales/fr.json

@@ -0,0 +1,48 @@
+{
+  "name": "France",
+  "native_name": "France",
+  "code": "fr",
+
+  "national_id": {
+    "label": "Numéro de sécurité sociale (NIR/INSEE)",
+    "phi_type": "national_id",
+    "patterns": [
+      "\\b[12]\\s?\\d{2}\\s?\\d{2}\\s?\\d{2}\\s?\\d{3}\\s?\\d{3}\\s?\\d{2}\\b"
+    ]
+  },
+
+  "phone": [
+    {"label": "French phone", "pattern": "\\b0[1-9]\\s?\\d{2}\\s?\\d{2}\\s?\\d{2}\\s?\\d{2}\\b"},
+    {"label": "French phone +33", "pattern": "\\b\\+33\\s?[1-9]\\s?\\d{2}\\s?\\d{2}\\s?\\d{2}\\s?\\d{2}\\b"}
+  ],
+
+  "address": {
+    "type": "keywords",
+    "keywords": ["Rue", "Avenue", "Boulevard", "Place", "Allée", "Impasse", "Chemin", "Cours", "Passage"],
+    "min_ratio": 0.3
+  },
+
+  "name_heuristic": {
+    "type": "none",
+    "pattern": "",
+    "min_ratio": 0.3,
+    "only_in_name_columns": true
+  },
+
+  "date_formats": [
+    {"pattern": "\\b(0?[1-9]|[12]\\d|3[01])/(0?[1-9]|1[0-2])/(19|20)\\d{2}\\b", "label": "French date (DD/MM/YYYY)"}
+  ],
+
+  "column_names": {
+    "nom_patient": "name", "nom": "name", "prénom": "name", "prenom": "name",
+    "nom_de_famille": "name",
+    "numéro_sécu": "national_id", "numero_secu": "national_id",
+    "nir": "national_id", "insee": "national_id",
+    "date_de_naissance": "date", "date_naissance": "date",
+    "téléphone": "phone", "telephone": "phone", "portable": "phone", "mobile": "phone",
+    "adresse": "address", "code_postal": "address",
+    "courriel": "email",
+    "numéro_patient": "id", "numero_patient": "id", "ipp": "id",
+    "numéro_assurance": "insurance", "numero_assurance": "insurance"
+  }
+}

package/skills/deidentify/locales/in.json

@@ -0,0 +1,48 @@
+{
+  "name": "India",
+  "native_name": "भारत",
+  "code": "in",
+
+  "national_id": {
+    "label": "Aadhaar / PAN",
+    "phi_type": "national_id",
+    "patterns": [
+      "\\b\\d{4}\\s?\\d{4}\\s?\\d{4}\\b",
+      "\\b[A-Z]{5}\\d{4}[A-Z]\\b"
+    ]
+  },
+
+  "phone": [
+    {"label": "Indian Mobile", "pattern": "\\b[6-9]\\d{9}\\b"},
+    {"label": "Indian Mobile +91", "pattern": "\\b\\+91[-.\\s]?[6-9]\\d{9}\\b"},
+    {"label": "Indian Landline", "pattern": "\\b0\\d{2,4}[-.\\s]?\\d{6,8}\\b"}
+  ],
+
+  "address": {
+    "type": "keywords",
+    "keywords": ["Road", "Rd.", "Nagar", "Colony", "Street", "Marg", "Path", "Lane", "Gali", "Mohalla", "Chowk", "District", "Dist."],
+    "postcode_pattern": "\\b\\d{6}\\b",
+    "min_ratio": 0.3
+  },
+
+  "name_heuristic": {
+    "type": "none",
+    "pattern": "",
+    "min_ratio": 0.3,
+    "only_in_name_columns": true
+  },
+
+  "date_formats": [
+    {"pattern": "\\b(0?[1-9]|[12]\\d|3[01])/(0?[1-9]|1[0-2])/(19|20)\\d{2}\\b", "label": "Indian date (DD/MM/YYYY)"},
+    {"pattern": "\\b(0?[1-9]|[12]\\d|3[01])-(0?[1-9]|1[0-2])-(19|20)\\d{2}\\b", "label": "Indian date (DD-MM-YYYY)"}
+  ],
+
+  "column_names": {
+    "aadhaar": "national_id", "aadhaar_number": "national_id",
+    "aadhar": "national_id", "aadhar_number": "national_id",
+    "pan": "national_id", "pan_number": "national_id",
+    "pin_code": "address", "pincode": "address",
+    "uhid": "id", "hospital_registration": "id",
+    "abha_number": "id", "health_id": "id"
+  }
+}

package/skills/deidentify/locales/jp.json

@@ -0,0 +1,48 @@
+{
+  "name": "Japan",
+  "native_name": "日本",
+  "code": "jp",
+
+  "national_id": {
+    "label": "マイナンバー (My Number)",
+    "phi_type": "national_id",
+    "patterns": [
+      "\\b\\d{4}\\s?\\d{4}\\s?\\d{4}\\b"
+    ]
+  },
+
+  "phone": [
+    {"label": "Mobile (090/080/070)", "pattern": "\\b0[789]0-?\\d{4}-?\\d{4}\\b"},
+    {"label": "Landline", "pattern": "\\b0\\d{1,4}-?\\d{1,4}-?\\d{4}\\b"}
+  ],
+
+  "address": {
+    "type": "suffix_regex",
+    "pattern": "(都|道|府|県|市|区|町|村|丁目|番地|号)",
+    "min_ratio": 0.3
+  },
+
+  "name_heuristic": {
+    "type": "regex",
+    "pattern": "^[\\u4E00-\\u9FFF\\u3040-\\u309F\\u30A0-\\u30FF]{2,6}$",
+    "min_ratio": 0.3,
+    "only_in_name_columns": true
+  },
+
+  "date_formats": [
+    {"pattern": "\\b(令和|平成|昭和)\\s?\\d{1,2}年\\s?\\d{1,2}月\\s?\\d{1,2}日\\b", "label": "Japanese era date"},
+    {"pattern": "\\b(19|20)\\d{2}年\\s?\\d{1,2}月\\s?\\d{1,2}日\\b", "label": "Japanese date (YYYY年MM月DD日)"}
+  ],
+
+  "column_names": {
+    "患者名": "name", "氏名": "name", "姓名": "name", "名前": "name",
+    "姓": "name", "名": "name",
+    "マイナンバー": "national_id", "個人番号": "national_id",
+    "生年月日": "date", "誕生日": "date",
+    "電話番号": "phone", "携帯番号": "phone", "連絡先": "phone",
+    "住所": "address", "自宅住所": "address", "居住地": "address",
+    "メール": "email", "メールアドレス": "email",
+    "患者番号": "id", "カルテ番号": "id", "診察券番号": "id",
+    "保険番号": "insurance", "被保険者番号": "insurance"
+  }
+}

package/skills/deidentify/locales/kr.json

@@ -0,0 +1,48 @@
+{
+  "name": "Korea",
+  "native_name": "한국",
+  "code": "kr",
+
+  "national_id": {
+    "label": "주민등록번호 (RRN)",
+    "phi_type": "rrn",
+    "patterns": [
+      "\\b\\d{6}-[1-4]\\d{6}\\b"
+    ]
+  },
+
+  "phone": [
+    {"label": "Mobile", "pattern": "\\b01[016789]-?\\d{3,4}-?\\d{4}\\b"},
+    {"label": "Landline", "pattern": "\\b0[2-6][0-9]{0,2}-?\\d{3,4}-?\\d{4}\\b"}
+  ],
+
+  "address": {
+    "type": "suffix_regex",
+    "pattern": "(특별시|광역시|특별자치시|특별자치도|도\\s|시\\s|군\\s|구\\s|읍\\s|면\\s|동\\s|리\\s|로\\s|길\\s)",
+    "min_ratio": 0.3
+  },
+
+  "name_heuristic": {
+    "type": "regex",
+    "pattern": "^[\\uAC00-\\uD7AF]{2,4}$",
+    "min_ratio": 0.3,
+    "only_in_name_columns": true
+  },
+
+  "date_formats": [
+    {"pattern": "\\b(19|20)\\d{2}년\\s*(0?[1-9]|1[0-2])월\\s*(0?[1-9]|[12]\\d|3[01])일\\b", "label": "Korean date (YYYY년 MM월 DD일)"}
+  ],
+
+  "column_names": {
+    "환자명": "name", "성명": "name", "이름": "name", "성함": "name",
+    "주민번호": "rrn", "주민등록번호": "rrn",
+    "생년월일": "date", "생년": "date", "출생일": "date",
+    "전화번호": "phone", "연락처": "phone", "핸드폰": "phone",
+    "휴대폰": "phone", "휴대전화": "phone", "자택전화": "phone",
+    "주소": "address", "자택주소": "address", "거주지": "address",
+    "이메일": "email",
+    "차트번호": "id", "등록번호": "id", "환자번호": "id",
+    "의무기록번호": "id", "원무번호": "id",
+    "보험번호": "insurance"
+  }
+}

package/skills/deidentify/locales/uk.json

@@ -0,0 +1,45 @@
+{
+  "name": "United Kingdom",
+  "native_name": "United Kingdom",
+  "code": "uk",
+
+  "national_id": {
+    "label": "NHS Number / National Insurance Number",
+    "phi_type": "national_id",
+    "patterns": [
+      "\\b\\d{3}\\s?\\d{3}\\s?\\d{4}\\b",
+      "\\b[A-CEGHJ-PR-TW-Z]{2}\\d{6}[A-D]\\b"
+    ]
+  },
+
+  "phone": [
+    {"label": "UK Mobile", "pattern": "\\b07\\d{3}\\s?\\d{6}\\b"},
+    {"label": "UK Landline", "pattern": "\\b0\\d{4}\\s?\\d{6}\\b"},
+    {"label": "UK +44", "pattern": "\\b\\+44\\s?\\d{4}\\s?\\d{6}\\b"}
+  ],
+
+  "address": {
+    "type": "keywords",
+    "keywords": ["Street", "St.", "Road", "Rd.", "Avenue", "Ave.", "Lane", "Ln.", "Close", "Crescent", "Terrace", "Drive"],
+    "postcode_pattern": "\\b[A-Z]{1,2}\\d[A-Z\\d]?\\s?\\d[A-Z]{2}\\b",
+    "min_ratio": 0.3
+  },
+
+  "name_heuristic": {
+    "type": "none",
+    "pattern": "",
+    "min_ratio": 0.3,
+    "only_in_name_columns": true
+  },
+
+  "date_formats": [
+    {"pattern": "\\b(0?[1-9]|[12]\\d|3[01])/(0?[1-9]|1[0-2])/(19|20)\\d{2}\\b", "label": "UK date (DD/MM/YYYY)"},
+    {"pattern": "\\b(0?[1-9]|[12]\\d|3[01])-(0?[1-9]|1[0-2])-(19|20)\\d{2}\\b", "label": "UK date (DD-MM-YYYY)"}
+  ],
+
+  "column_names": {
+    "nhs_number": "national_id", "nhs_no": "national_id",
+    "ni_number": "national_id", "national_insurance": "national_id",
+    "postcode": "address", "post_code": "address"
+  }
+}

package/skills/deidentify/locales/us.json

@@ -0,0 +1,43 @@
+{
+  "name": "United States",
+  "native_name": "United States",
+  "code": "us",
+
+  "national_id": {
+    "label": "Social Security Number (SSN)",
+    "phi_type": "rrn",
+    "patterns": [
+      "\\b\\d{3}-\\d{2}-\\d{4}\\b"
+    ]
+  },
+
+  "phone": [
+    {"label": "US Phone", "pattern": "\\b\\(?\\d{3}\\)?[-.\\s]?\\d{3}[-.\\s]?\\d{4}\\b"},
+    {"label": "US Phone +1", "pattern": "\\b\\+?1[-.\\s]?\\(?\\d{3}\\)?[-.\\s]?\\d{3}[-.\\s]?\\d{4}\\b"}
+  ],
+
+  "address": {
+    "type": "keywords",
+    "keywords": ["Street", "St.", "Avenue", "Ave.", "Boulevard", "Blvd.", "Drive", "Dr.", "Lane", "Ln.", "Road", "Rd.", "Court", "Ct.", "Suite", "Ste.", "Apt.", "P.O. Box"],
+    "min_ratio": 0.3
+  },
+
+  "name_heuristic": {
+    "type": "none",
+    "pattern": "",
+    "min_ratio": 0.3,
+    "only_in_name_columns": true
+  },
+
+  "date_formats": [
+    {"pattern": "\\b(0?[1-9]|1[0-2])/(0?[1-9]|[12]\\d|3[01])/(19|20)\\d{2}\\b", "label": "US date (MM/DD/YYYY)"},
+    {"pattern": "\\b(0?[1-9]|1[0-2])-(0?[1-9]|[12]\\d|3[01])-(19|20)\\d{2}\\b", "label": "US date (MM-DD-YYYY)"}
+  ],
+
+  "column_names": {
+    "social_security_number": "rrn", "social_security": "rrn",
+    "ssn": "rrn", "ss_number": "rrn",
+    "zip": "address", "zipcode": "address", "zip_code": "address",
+    "state": "address"
+  }
+}

package/skills/deidentify/references/date_shift_guide.md

@@ -0,0 +1,82 @@
+# Date Shifting Guide
+
+## What is Date Shifting?
+
+Date shifting replaces actual dates with shifted dates, preserving the relative time
+intervals between events for the same patient.  This maintains temporal relationships
+(e.g., "surgery was 3 days after admission") while removing the absolute dates that
+could identify individuals.
+
+## SANT Method (Shift and Truncate)
+
+The recommended approach, used by PCORI Clinical Data Research Networks:
+
+1. **Generate offset**: For each patient, draw a random integer from [-365, +365] days
+2. **Apply uniformly**: Shift ALL dates for that patient by the same offset
+3. **Truncate edges**: Remove records near dataset boundaries where shifting would
+   push dates outside the study period
+
+### Why per-patient offset?
+
+- Preserves relative intervals between events for the same patient
+- "Admission → Surgery → Discharge" intervals remain exact
+- Different patients get different offsets (prevents cross-patient inference)
+
+## Implementation Details
+
+### Seed Management
+
+- A random seed is generated once per run and stored in `mapping.json`
+- This makes the shifting deterministic and reproducible
+- Re-running with the same seed on the same data produces identical results
+- The seed should be kept as securely as the mapping file itself
+
+### Entity Identification
+
+The script looks for a patient/entity ID column to group dates:
+1. Columns classified as `id` type (차트번호, MRN, patient_id, etc.)
+2. If no ID column exists, all dates are shifted by the same global offset
+
+### Supported Date Formats
+
+| Format | Example | Preserved |
+|--------|---------|-----------|
+| ISO | 2024-03-15 | Yes |
+| Dot-separated | 2024.03.15 | Yes |
+| Slash-separated | 2024/03/15 | Yes |
+| Compact | 20240315 | Yes |
+| Korean | 2024년 3월 15일 | Yes |
+
+### Unparseable Dates
+
+If a date string cannot be parsed by any known format, it is replaced with
+`[DATE_SHIFTED]` rather than left unchanged (fail-safe).
+
+## When NOT to Date Shift
+
+- **Study-level dates** that are already public (e.g., "data collected 2020-2023")
+- **Seasonal analyses** where month or season is a study variable
+- **Age at event**: Calculate age before shifting, then shift the dates
+
+## Edge Cases
+
+- **Impossible dates after shift**: Feb 30 → script uses Python datetime which
+  handles month-end overflow (raises ValueError → caught and adjusted)
+- **Leap years**: Feb 29 shifted to a non-leap year → becomes Feb 28
+- **Cross-year boundaries**: Handled correctly by timedelta arithmetic
+- **Negative ages**: If birth date is shifted forward past an event date,
+  the relative interval (age at event) is still preserved
+
+## Re-identification Risk
+
+Even with date shifting, be aware:
+- Rare diseases + approximate date range can still narrow candidates
+- If attacker knows the shift range (±365), they have a 730-day window
+- For very small populations, consider larger shift ranges or year-only dates
+
+## References
+
+- Hripcsak G, et al. "Bias Associated with Mining Electronic Health Records."
+  J Biomed Inform. 2011;44(6):1120-1126. (Temporal relationship preservation)
+- Meystre SM, et al. "Automatic De-identification of Textual Documents in the
+  Electronic Health Record." BMC Med Res Methodol. 2010;10:70.

package/skills/deidentify/references/hipaa_18_identifiers.md

@@ -0,0 +1,48 @@
+# HIPAA Safe Harbor: 18 Identifiers
+
+Reference for the `deidentify` skill.  Based on HIPAA Privacy Rule 164.514(b)(2).
+
+## Identifier List
+
+| # | Identifier | Script action | Manual review needed |
+|---|-----------|--------------|---------------------|
+| 1 | Names | Pseudonymize (P001, P002...) | No |
+| 2 | Geographic data (< state) | Suppress | Yes — ZIP first 3 digits may be kept if population >= 20,000 |
+| 3 | Dates (except year) | Date shift (per-patient offset) | No |
+| 4 | Ages > 89 | Generalize to "90+" | No |
+| 5 | Telephone numbers | Suppress | No |
+| 6 | Fax numbers | Suppress | No |
+| 7 | Email addresses | Suppress | No |
+| 8 | Social Security numbers | Suppress | No |
+| 9 | Medical record numbers | Replace (ID001, ID002...) | No |
+| 10 | Health plan beneficiary numbers | Suppress | No |
+| 11 | Account numbers | Suppress | Yes — rare in research data |
+| 12 | Certificate/license numbers | Suppress | Yes — rare in research data |
+| 13 | Vehicle identifiers | Suppress | Yes — only in trauma data |
+| 14 | Device identifiers | Suppress | Yes — only in device studies |
+| 15 | Web URLs | Suppress | No |
+| 16 | IP addresses | Suppress | No |
+| 17 | Biometric identifiers | N/A (not in tabular data) | N/A |
+| 18 | Full-face photographs | N/A (not in tabular data) | N/A |
+
+## Korean Equivalents
+
+| HIPAA identifier | Korean equivalent | 한국 개인정보보호법 분류 |
+|-----------------|-------------------|----------------------|
+| Names | 성명 | 고유식별정보 |
+| SSN | 주민등록번호 | 고유식별정보 |
+| MRN | 차트번호/의무기록번호 | 개인정보 |
+| Phone | 전화번호/연락처 | 개인정보 |
+| Address | 주소 | 개인정보 |
+| DOB | 생년월일 | 개인정보 |
+| Email | 이메일 | 개인정보 |
+| Insurance no. | 건강보험증 번호 | 고유식별정보 |
+
+## Notes
+
+- Items 17-18 (biometrics, photos) are outside the scope of this tool (tabular data only).
+- Items 11-14 (accounts, certificates, vehicles, devices) are rare in clinical research datasets
+  but should be flagged if column names suggest their presence.
+- For Korean data, 주민등록번호 is the most critical direct identifier (combines birthdate + gender).
+- The script detects items 1-10 and 15-16 via column names and regex patterns.
+  Items 11-14 rely on column-name heuristics only.