caideface 0.2.0__tar.gz → 0.3.0__tar.gz

{caideface-0.2.0/src/caideface.egg-info → caideface-0.3.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: caideface
-Version: 0.2.0
+Version: 0.3.0
 Summary: MRI defacing pipeline with skull-stripping and affine registration from cai4cai
 Author-email: Lorena Garcia-Foncillas <lorenagarfon00@gmail.com>
-License-Expression: MIT
+License: MIT
 Project-URL: Homepage, https://github.com/cai4cai/defacing_pipeline
 Project-URL: Repository, https://github.com/cai4cai/defacing_pipeline
-Keywords: MRI,defacing,anonymisation,skull-stripping,neuroimaging
+Keywords: MRI,defacing,anonymisation,skull-stripping,neuroimaging,NER,text-anonymization
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
@@ -22,6 +22,8 @@ Requires-Dist: pandas>=1.5
 Requires-Dist: natsort>=8.0
 Requires-Dist: tqdm>=4.60
 Requires-Dist: hd-bet
+Requires-Dist: spacy>=3.5
+Requires-Dist: faker>=18.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
@@ -29,19 +31,28 @@ Dynamic: license-file
 
 # caideface
 
-**MRI defacing pipeline with skull-stripping and affine registration** from the [cai4cai](https://cai4cai.ml/) research group (Contextual Artificial Intelligence for Computer Assisted Interventions).
+**MRI defacing and text anonymisation toolkit** from the [cai4cai](https://cai4cai.ml/) research group (Contextual Artificial Intelligence for Computer Assisted Interventions).
 
-This pipeline anonymises head MRI scans by removing facial features while preserving brain structures, as described in the paper *"A Generalisable Head MRI Defacing Pipeline: Evaluation on 2,566 Meningioma Scans"* ([arXiv:2505.12999](https://arxiv.org/abs/2505.12999)).
+This package provides two complementary anonymisation capabilities:
+
+- **Image defacing** -- removes facial features from head MRI scans while preserving brain structures, as described in the paper *"A Generalisable Head MRI Defacing Pipeline: Evaluation on 2,566 Meningioma Scans"* ([arXiv:2505.12999](https://arxiv.org/abs/2505.12999)).
+- **Text anonymisation** -- detects personal names in medical reports using a trained spaCy NER model and replaces them with realistic fake names (Hiding in Plain Sight / HIPS technique).
 
 ## Pipeline overview
 
-The pipeline consists of three steps:
+### Image defacing pipeline
+
+The defacing pipeline consists of three steps:
 
 1. **Reorientation** -- Aligns NIfTI scans to LAS canonical orientation (MNI152 standard) using nibabel.
 2. **Skull-stripping** -- Extracts brain masks using [HD-BET](https://github.com/MIC-DKFZ/HD-BET), then applies dynamic dilation to preserve peripheral brain structures.
 3. **Registration & Defacing** -- Registers each scan to the MNI152 template using BRAINSFit (affine), warps a face mask into the scan's space, and applies it to remove facial features.
 
-The MNI152 skull-stripped template and face mask are **bundled with the package**, so no additional downloads are needed.
+### Text anonymisation (NER + HIPS)
+
+The text anonymisation module uses a trained spaCy Named Entity Recognition (NER) model to identify personal names (`PER` entities) in `.txt` files and replaces them with realistic fake names generated by the [Faker](https://faker.readthedocs.io/) library. This "Hiding in Plain Sight" (HIPS) approach produces anonymised reports that remain naturally readable. Consistent name mapping ensures that the same real name is always replaced with the same fake name within a document.
+
+All required models and data are **bundled with the package**, so no additional downloads are needed.
 
 ## Requirements
 
@@ -106,7 +117,7 @@ pip install -e .
 
 ## Usage
 
-### CLI -- Full pipeline
+### CLI -- Full defacing pipeline
 
 Run all three steps in one command:
 
@@ -134,7 +145,7 @@ This creates three subdirectories under `./output`:
 | `--steps` | `all` | Run specific steps: `reorient`, `skull_strip`, `deface` (comma-separated) |
 | `-v` | off | Verbose/debug logging |
 
-### CLI -- Individual steps
+### CLI -- Individual defacing steps
 
 Run each step separately for more control:
 
@@ -151,8 +162,100 @@ caideface deface ./reoriented ./hdbet ./defaced \
   --brainsresample /path/to/BRAINSResample
 ```
 
+### CLI -- Text anonymisation
+
+#### Single file
+
+```bash
+caideface anonymize-single ./reports/report_1.txt ./anonymized/report_1.txt
+```
+
+#### Batch (all `.txt` files in a directory)
+
+```bash
+caideface anonymize ./reports ./anonymized_reports
+```
+
+#### Options
+
+Both commands accept the same options:
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--model` | bundled | Path to a custom spaCy NER model directory |
+| `--n-names` | `50` | Size of the fake name pool |
+| `--seed` | none | Random seed for reproducible output |
+| `-v` | off | Verbose/debug logging |
+
+#### Example
+
+**Input** (`reports/report_1550.txt`):
+```
+Reported by Danielle Smith and William Stuart on 03/10/2014
+```
+
+**Output** (`anonymized_reports/report_1550.txt`):
+```
+Reported by Ryan Munoz and Holly Wood on 03/10/2014
+```
+
+The batch command saves an `anonymization_log.csv` alongside the output files with a summary of replacements per file.
+
+### Python API -- Text anonymisation
+
+#### Single file
+
+```python
+from caideface.anonymize import load_ner_model, generate_fake_names, anonymize_single
+
+# Load model and generate fake name pool (do this once)
+nlp = load_ner_model()                        # uses bundled model
+fake_names = generate_fake_names(n=50, seed=42)
+
+# Anonymise a single report
+result = anonymize_single(
+    input_file="reports/report_1.txt",
+    output_file="anonymized/report_1.txt",
+    nlp=nlp,
+    fake_names=fake_names,
+)
+print(result["replacements"])   # number of names replaced
+print(result["names_found"])    # list of original names detected
+print(result["name_mapping"])   # {original_name: fake_name} mapping
+```
+
+#### Batch processing
+
+```python
+from caideface import anonymize_batch
+
+# Anonymise all .txt files in a directory
+log_df = anonymize_batch(
+    input_dir="reports/",
+    output_dir="anonymized_reports/",
+    seed=42,
+)
+print(log_df)  # DataFrame with file, replacements, names_found per file
+```
+
+#### All available imports
+
+```python
+from caideface import (
+    DefacePipeline,           # Full image defacing pipeline
+    reorient_batch,           # Step 1
+    skull_strip_batch,        # Step 2
+    deface_batch,             # Step 3
+    anonymize_batch,          # Text anonymisation (batch)
+    anonymize_single,         # Text anonymisation (single file)
+    default_ner_model_path,   # Path to bundled NER model
+)
+```
+
 ## Output structure
 
+### Image defacing
+
 ```
 output/
 ├── reoriented/
@@ -170,6 +273,16 @@ output/
         └── hd_bet_dilated_<scan>_masked.nii.gz  # Final defaced scan
 ```
 
+### Text anonymisation
+
+```
+anonymized_reports/
+├── anonymization_log.csv                  # Replacements per file
+├── report_1.txt                           # Anonymised report
+├── report_2.txt
+└── ...
+```
+
 ## Existing transforms
 
 If you have pre-computed registration transforms (e.g. from 3D Slicer), place a file named `Transform_to_template.txt` in the same directory as the dilated skull-stripped scan. The pipeline will use it instead of running BRAINSFit. Both plain 4x4 text matrices and ITK/Slicer transform formats are supported.
@@ -199,6 +312,22 @@ If you use HD-BET (skull-stripping, Step 2), please also cite:
 }
 ```
 
+If you use the text anonymisation (NER + HIPS), please also cite:
+
+```bibtex
+@article{garcia2025ner,
+  title={Evaluation of Named Entity Recognition for Automated Extraction of Present Tumor Size and Personal Names from Radiology Reports Using Spacy},
+  author={Garcia-Foncillas Macias, Lorena and Barfoot, Theodore and Vercauteren, Tom and Shapey, Jonathan},
+  journal={Journal of Neurological Surgery Part B: Skull Base},
+  volume={86},
+  number={S 01},
+  year={2025},
+  doi={10.1055/s-0045-1803715}
+}
+```
+
+
+
 ## License
 
 This project is licensed under the MIT License -- see the [LICENSE](LICENSE.md) file for details.

{caideface-0.2.0 → caideface-0.3.0}/README.md

@@ -1,18 +1,27 @@
 # caideface
 
-**MRI defacing pipeline with skull-stripping and affine registration** from the [cai4cai](https://cai4cai.ml/) research group (Contextual Artificial Intelligence for Computer Assisted Interventions).
+**MRI defacing and text anonymisation toolkit** from the [cai4cai](https://cai4cai.ml/) research group (Contextual Artificial Intelligence for Computer Assisted Interventions).
 
-This pipeline anonymises head MRI scans by removing facial features while preserving brain structures, as described in the paper *"A Generalisable Head MRI Defacing Pipeline: Evaluation on 2,566 Meningioma Scans"* ([arXiv:2505.12999](https://arxiv.org/abs/2505.12999)).
+This package provides two complementary anonymisation capabilities:
+
+- **Image defacing** -- removes facial features from head MRI scans while preserving brain structures, as described in the paper *"A Generalisable Head MRI Defacing Pipeline: Evaluation on 2,566 Meningioma Scans"* ([arXiv:2505.12999](https://arxiv.org/abs/2505.12999)).
+- **Text anonymisation** -- detects personal names in medical reports using a trained spaCy NER model and replaces them with realistic fake names (Hiding in Plain Sight / HIPS technique).
 
 ## Pipeline overview
 
-The pipeline consists of three steps:
+### Image defacing pipeline
+
+The defacing pipeline consists of three steps:
 
 1. **Reorientation** -- Aligns NIfTI scans to LAS canonical orientation (MNI152 standard) using nibabel.
 2. **Skull-stripping** -- Extracts brain masks using [HD-BET](https://github.com/MIC-DKFZ/HD-BET), then applies dynamic dilation to preserve peripheral brain structures.
 3. **Registration & Defacing** -- Registers each scan to the MNI152 template using BRAINSFit (affine), warps a face mask into the scan's space, and applies it to remove facial features.
 
-The MNI152 skull-stripped template and face mask are **bundled with the package**, so no additional downloads are needed.
+### Text anonymisation (NER + HIPS)
+
+The text anonymisation module uses a trained spaCy Named Entity Recognition (NER) model to identify personal names (`PER` entities) in `.txt` files and replaces them with realistic fake names generated by the [Faker](https://faker.readthedocs.io/) library. This "Hiding in Plain Sight" (HIPS) approach produces anonymised reports that remain naturally readable. Consistent name mapping ensures that the same real name is always replaced with the same fake name within a document.
+
+All required models and data are **bundled with the package**, so no additional downloads are needed.
 
 ## Requirements
 
@@ -77,7 +86,7 @@ pip install -e .
 
 ## Usage
 
-### CLI -- Full pipeline
+### CLI -- Full defacing pipeline
 
 Run all three steps in one command:
 
@@ -105,7 +114,7 @@ This creates three subdirectories under `./output`:
 | `--steps` | `all` | Run specific steps: `reorient`, `skull_strip`, `deface` (comma-separated) |
 | `-v` | off | Verbose/debug logging |
 
-### CLI -- Individual steps
+### CLI -- Individual defacing steps
 
 Run each step separately for more control:
 
@@ -122,8 +131,100 @@ caideface deface ./reoriented ./hdbet ./defaced \
   --brainsresample /path/to/BRAINSResample
 ```
 
+### CLI -- Text anonymisation
+
+#### Single file
+
+```bash
+caideface anonymize-single ./reports/report_1.txt ./anonymized/report_1.txt
+```
+
+#### Batch (all `.txt` files in a directory)
+
+```bash
+caideface anonymize ./reports ./anonymized_reports
+```
+
+#### Options
+
+Both commands accept the same options:
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--model` | bundled | Path to a custom spaCy NER model directory |
+| `--n-names` | `50` | Size of the fake name pool |
+| `--seed` | none | Random seed for reproducible output |
+| `-v` | off | Verbose/debug logging |
+
+#### Example
+
+**Input** (`reports/report_1550.txt`):
+```
+Reported by Danielle Smith and William Stuart on 03/10/2014
+```
+
+**Output** (`anonymized_reports/report_1550.txt`):
+```
+Reported by Ryan Munoz and Holly Wood on 03/10/2014
+```
+
+The batch command saves an `anonymization_log.csv` alongside the output files with a summary of replacements per file.
+
+### Python API -- Text anonymisation
+
+#### Single file
+
+```python
+from caideface.anonymize import load_ner_model, generate_fake_names, anonymize_single
+
+# Load model and generate fake name pool (do this once)
+nlp = load_ner_model()                        # uses bundled model
+fake_names = generate_fake_names(n=50, seed=42)
+
+# Anonymise a single report
+result = anonymize_single(
+    input_file="reports/report_1.txt",
+    output_file="anonymized/report_1.txt",
+    nlp=nlp,
+    fake_names=fake_names,
+)
+print(result["replacements"])   # number of names replaced
+print(result["names_found"])    # list of original names detected
+print(result["name_mapping"])   # {original_name: fake_name} mapping
+```
+
+#### Batch processing
+
+```python
+from caideface import anonymize_batch
+
+# Anonymise all .txt files in a directory
+log_df = anonymize_batch(
+    input_dir="reports/",
+    output_dir="anonymized_reports/",
+    seed=42,
+)
+print(log_df)  # DataFrame with file, replacements, names_found per file
+```
+
+#### All available imports
+
+```python
+from caideface import (
+    DefacePipeline,           # Full image defacing pipeline
+    reorient_batch,           # Step 1
+    skull_strip_batch,        # Step 2
+    deface_batch,             # Step 3
+    anonymize_batch,          # Text anonymisation (batch)
+    anonymize_single,         # Text anonymisation (single file)
+    default_ner_model_path,   # Path to bundled NER model
+)
+```
+
 ## Output structure
 
+### Image defacing
+
 ```
 output/
 ├── reoriented/
@@ -141,6 +242,16 @@ output/
         └── hd_bet_dilated_<scan>_masked.nii.gz  # Final defaced scan
 ```
 
+### Text anonymisation
+
+```
+anonymized_reports/
+├── anonymization_log.csv                  # Replacements per file
+├── report_1.txt                           # Anonymised report
+├── report_2.txt
+└── ...
+```
+
 ## Existing transforms
 
 If you have pre-computed registration transforms (e.g. from 3D Slicer), place a file named `Transform_to_template.txt` in the same directory as the dilated skull-stripped scan. The pipeline will use it instead of running BRAINSFit. Both plain 4x4 text matrices and ITK/Slicer transform formats are supported.
@@ -170,6 +281,22 @@ If you use HD-BET (skull-stripping, Step 2), please also cite:
 }
 ```
 
+If you use the text anonymisation (NER + HIPS), please also cite:
+
+```bibtex
+@article{garcia2025ner,
+  title={Evaluation of Named Entity Recognition for Automated Extraction of Present Tumor Size and Personal Names from Radiology Reports Using Spacy},
+  author={Garcia-Foncillas Macias, Lorena and Barfoot, Theodore and Vercauteren, Tom and Shapey, Jonathan},
+  journal={Journal of Neurological Surgery Part B: Skull Base},
+  volume={86},
+  number={S 01},
+  year={2025},
+  doi={10.1055/s-0045-1803715}
+}
+```
+
+
+
 ## License
 
 This project is licensed under the MIT License -- see the [LICENSE](LICENSE.md) file for details.

{caideface-0.2.0 → caideface-0.3.0}/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "caideface"
-version = "0.2.0"
+version = "0.3.0"
 description = "MRI defacing pipeline with skull-stripping and affine registration from cai4cai"
 readme = "README.md"
-license = "MIT"
+license = {text = "MIT"}
 requires-python = ">=3.9"
 authors = [
     {name = "Lorena Garcia-Foncillas", email = "lorenagarfon00@gmail.com"},
 ]
-keywords = ["MRI", "defacing", "anonymisation", "skull-stripping", "neuroimaging"]
+keywords = ["MRI", "defacing", "anonymisation", "skull-stripping", "neuroimaging", "NER", "text-anonymization"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Science/Research",
@@ -29,6 +29,8 @@ dependencies = [
     "natsort>=8.0",
     "tqdm>=4.60",
     "hd-bet",
+    "spacy>=3.5",
+    "faker>=18.0",
 ]
 
 [project.optional-dependencies]
@@ -48,4 +50,7 @@ Repository = "https://github.com/cai4cai/defacing_pipeline"
 where = ["src"]
 
 [tool.setuptools.package-data]
-caideface = ["data/*.nii.gz"]
+caideface = [
+    "data/*.nii.gz",
+    "data/ner_model/**/*",
+]

{caideface-0.2.0 → caideface-0.3.0}/src/caideface/__init__.py

@@ -1,17 +1,20 @@
-"""caideface - MRI defacing pipeline from cai4cai.
+"""caideface - MRI defacing and text anonymisation pipeline from cai4cai.
 
 A three-step pipeline for anonymising head MRI scans:
 1. Reorientation to MNI152 atlas reference (nibabel)
 2. Skull-stripping with HD-BET and dynamic dilation
 3. Affine registration and defacing (BRAINSFit)
+
+Plus standalone text anonymisation via NER + HIPS (Hiding in Plain Sight).
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 from .pipeline import DefacePipeline
 from .reorient import reorient_batch, reorient_single
 from .skull_strip import skull_strip_batch, skull_strip_single
 from .register import deface_batch, deface_single
+from .anonymize import anonymize_batch, anonymize_single, default_ner_model_path
 
 __all__ = [
     "DefacePipeline",
@@ -21,4 +24,7 @@ __all__ = [
     "skull_strip_single",
     "deface_batch",
     "deface_single",
+    "anonymize_batch",
+    "anonymize_single",
+    "default_ner_model_path",
 ]