OpenMed Tutorials: Complete Guide to Examples, Documentation, and Getting Started

Yes, OpenMed provides comprehensive tutorials covering everything from one-line NER extraction to production REST API deployment, located in the docs/ and examples/ directories.

The maziyarpanahi/openmed repository ships with a complete tutorial suite designed to take you from basic installation to production deployment. These tutorials for OpenMed include ready-to-run Python scripts, conceptual guides, and real-world examples that demonstrate clinical text analysis, privacy filtering, and on-device deployment.

Where to Find OpenMed Tutorials

All learning resources are self-contained within the repository and organized into two primary locations. You can run the Python examples immediately after installing the package using pip install "openmed[hf]" for Hugging Face backends or pip install "openmed[mlx]" for Apple Silicon acceleration.

Documentation Guides (docs/)

The docs/ folder contains narrative Markdown guides that explain concepts, API parameters, and configuration options:

• docs/getting-started.md – Installation, basic usage, and configuration profiles
• docs/analyze-text.md – Deep dive into the analyze_text function and output formats
• docs/pii-smart-merging.md – Explains the smart merging feature that keeps dates and IDs as single entities
• docs/batch-processing.md – High-throughput pipeline implementation with performance benchmarks
• docs/rest-service.md – FastAPI service deployment with uvicorn commands
• docs/swift-openmedkit.md – Native iOS and macOS integration using the OpenMedKit Swift package

Runnable Examples (examples/)

The examples/ folder contains executable scripts demonstrating specific use cases:

• examples/pii_multilingual_new_languages.py – PII detection across 12 languages including Portuguese, Arabic, and Hindi
• examples/privacy_filter_unified.py – Unified extract_pii and deidentify API across MLX and PyTorch backends
• examples/pii_batch_processing.py – End-to-end batch PII workflow with performance benchmarks
• examples/custom_tokenizer/custom_tokenize_alignment.py – Building and comparing custom medical tokenizers against the built-in tokenizer

Step-by-Step Tutorial Topics

Basic Text Analysis and NER

The docs/analyze-text.md tutorial covers one-line Named Entity Recognition (NER) extraction using the analyze_text function. This guide teaches you to call the analysis pipeline and inspect returned entities.

from openmed import analyze_text

result = analyze_text(
    "Patient started on imatinib for chronic myeloid leukemia.",
    model_name="disease_detection_superclinical",
)

for entity in result.entities:
    print(f"{entity.label:<12} {entity.text:<30} {entity.confidence:.2f}")

This example is also referenced in the README.md file under the 30-second example section.

PII Detection and De-identification

The docs/pii-smart-merging.md tutorial explains how to use extract_pii and deidentify with smart merging enabled. This functionality supports both PyTorch and MLX backends for privacy protection.

from openmed import extract_pii, deidentify

text = "Paciente: Pedro Almeida, CPF 123.456.789-09, telefone +351 912 345 678."
pii = extract_pii(text, model_name="pii_superclinical_large", use_smart_merging=True)

print("Detected entities:", [(e.label, e.text) for e in pii.entities])

masked = deidentify(text, method="mask")
print("Masked:", masked.deidentified_text)

replaced = deidentify(text, method="replace", consistent=True, seed=42)
print("Replaced:", replaced.deidentified_text)

The full multilingual example is available in examples/pii_multilingual_new_languages.py.

Batch Processing at Scale

The docs/batch-processing.md guide demonstrates high-throughput processing using the BatchProcessor class. This tutorial handles automatic chunking and document grouping for production workloads.

from openmed import BatchProcessor

processor = BatchProcessor(
    model_name="disease_detection_superclinical",
    group_entities=True,
)

texts = [
    "Patient presents with hypertension and diabetes.",
    "Administer 5 mg of lisinopril daily.",
]

batch_results = processor.process_texts(texts)

for i, result in enumerate(batch_results):
    print(f"--- Document {i+1} ---")
    for ent in result.entities:
        print(ent.label, ent.text, f"{ent.confidence:.2f}")

Multilingual Support

OpenMed tutorials cover 12 languages for PII detection. The examples/pii_multilingual_new_languages.py script demonstrates how language codes affect the pipeline and how to run the same API across Portuguese, Arabic, Hindi, and other languages.

Custom Medical Tokenizers

The examples/custom_tokenizer/custom_tokenize_alignment.py tutorial guides you through building a custom tokenizer and comparing its alignment against the built-in medical tokenizer. This is essential for domain-specific preprocessing pipelines.

REST API Deployment

The docs/rest-service.md tutorial provides step-by-step instructions for deploying OpenMed as a FastAPI service. You can spin up the production-ready REST service with a single uvicorn command.

Swift Integration for iOS

The docs/swift-openmedkit.md tutorial covers on-device deployment for iOS and macOS applications using the OpenMedKit Swift package. This enables building native mobile healthcare apps with OpenMed models.

Hands-On Code Examples from the Repository

All three code examples above are extracted directly from the official OpenMed tutorials. You can copy-paste them into a new Python file and execute them immediately after installing the package.

For the complete multilingual PII workflow, reference examples/pii_multilingual_new_languages.py. For backend comparisons between MLX and PyTorch, see examples/privacy_filter_unified.py. For batch processing benchmarks, consult examples/pii_batch_processing.py.

Summary

• OpenMed tutorials are located in the docs/ (guides) and examples/ (scripts) folders
• Core functions covered include analyze_text, extract_pii, deidentify, and BatchProcessor.process_texts
• Installation requires pip install "openmed[hf]" for Hugging Face or pip install "openmed[mlx]" for Apple Silicon
• Key tutorials span basic NER, multilingual PII detection, batch processing, custom tokenizers, REST API deployment, and Swift iOS integration
• All tutorials are self-contained and runnable without additional configuration

Frequently Asked Questions

Where are the official OpenMed tutorials located?

The official tutorials reside in two locations within the maziyarpanahi/openmed repository: the docs/ folder contains Markdown guides explaining concepts and APIs, while the examples/ folder contains runnable Python scripts. Key files include docs/getting-started.md for installation and docs/analyze-text.md for basic usage.

Do I need a GPU to follow the OpenMed tutorials?

No, the tutorials support both CPU and GPU backends. You can run examples/privacy_filter_unified.py to see how the library auto-routes between PyTorch and MLX (Apple Silicon) backends. The tutorials include performance benchmarks so you can compare processing speeds across different hardware configurations.

How do I run the multilingual PII tutorial?

Execute the examples/pii_multilingual_new_languages.py script after installing with pip install "openmed[hf]". This tutorial demonstrates PII detection across 12 languages including Portuguese, Arabic, and Hindi, using the same extract_pii API with language-specific model configurations.

Can I use OpenMed tutorials to build an iOS app?

Yes, the docs/swift-openmedkit.md tutorial specifically covers integrating OpenMed into native iOS and macOS applications using the OpenMedKit Swift package. This allows you to deploy medical NLP models on-device for privacy-compliant mobile healthcare applications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}