thomasbtf / document-anonymization

Personal data redaction on images based on FHIR patient resources.

DocNo - Document Pseudonymization

This workflow redacted personal information on given images. The personal information must be provided as FHIR patient resource.

Authors

• Thomas Battenfeld (@thomasbtf)
• Simon Magin (@simakro)
• Josefa Welling (@josefawelling)
• Christin Seifert
• Folker Meyer (@folker)

Usage

Step 1: Obtain a copy of this workflow

If you simply want to use this workflow, download and extract the latest release. If you intend to modify and further extend this workflow or want to work under version control, fork this repository as outlined in Advanced. The latter way is recommended.

In any case, if you use this workflow in a paper, don't forget to give credits to the authors by citing the URL of this repository and, if available, its DOI (see above).

Step 2: Configure workflow

Configure the workflow according to your needs by editing the files in the config/ folder. Adjust the config/config.yaml to configure the workflow execution, and the config/pep/documents.csv to specify your documents and meta data.

Step 3: Install Snakemake

Install Snakemake using conda:

conda create -c bioconda -c conda-forge -n snakemake snakemake

For installation details, see the instructions in the Snakemake documentation.

Step 4: Execute workflow

Activate the conda environment:

conda activate snakemake

Test your configuration by performing a dry-run via

snakemake --use-conda -n

Then execute the workflow with $N cores via

snakemake --use-conda --cores $N

If you not only want to fix the software stack but also the underlying OS, use

snakemake --use-conda --use-singularity

in combination with the modes above. See the Snakemake documentation for further details.

Step 5: Investigate results

After successful execution, you can create a self-contained interactive HTML report with all results via:

snakemake --report report.zip

This report can, e.g., be forwarded to your collaborators. An example (using some trivial test data) can be seen here.

Advanced

The following recipe provides established best practices for running and extending this workflow in a reproducible way.

1. Fork the repo to a personal or lab account.
2. Clone the fork to the desired working directory for the concrete project/run on your machine.
3. Create a new branch (the project-branch) within the clone and switch to it. The branch will contain any project-specific modifications (e.g. to configuration, but also to code).
4. Modify the config, and any necessary sheets (and probably the workflow) as needed.
5. Commit any changes and push the project-branch to your fork on github.
6. Run the analysis.
7. Optional: Merge back any valuable and generalizable changes to the upstream repo via a pull request. This would be greatly appreciated.
8. Optional: Push results (plots/tables) to the remote branch on your fork.
9. Optional: Create a self-contained workflow archive for publication along with the paper (snakemake --archive).
10. Optional: Delete the local clone/workdir to free space.

Testing

Test cases are in the subfolder .test. They are automatically executed via continuous integration with Github Actions.