open-dicom
diff --git a/‎README.md‎
Lines changed: 42 additions & 1 deletion b/‎README.md‎
Lines changed: 42 additions & 1 deletion
diff --git a/‎csa_header/examples.py‎
Lines changed: 197 additions & 0 deletions b/‎csa_header/examples.py‎
Lines changed: 197 additions & 0 deletions
diff --git a/‎examples/README.md‎
Lines changed: 52 additions & 0 deletions b/‎examples/README.md‎
Lines changed: 52 additions & 0 deletions
@@ -71,12 +71,16 @@ pip install csa_header
 
 ### Optional Dependencies
 
-For working with the provided [NiBabel integration examples](#integration-with-nibabel):
+For working with the provided examples and automatic example data downloading:
 
 ```console
 pip install csa_header[examples]
 ```
 
+This installs:
+- `nibabel` for NiBabel integration examples
+- `pooch` for automatic downloading of example DICOM files
+
 For development (includes pre-commit hooks and IPython):
 
 ```console
@@ -85,6 +89,33 @@ pip install csa_header[dev]
 
 ## Quickstart
 
+### Option 1: Using Example Data (Easiest!)
+
+The quickest way to get started is using the built-in example data:
+
+```python
+>>> # Install with examples support
+>>> # pip install csa_header[examples]
+>>>
+>>> from csa_header.examples import fetch_example_dicom
+>>> from csa_header import CsaHeader
+>>> import pydicom
+>>>
+>>> # Fetch example DICOM (downloads once, then cached)
+>>> dicom_path = fetch_example_dicom()
+>>> dcm = pydicom.dcmread(dicom_path)
+>>>
+>>> # Parse CSA Series Header
+>>> raw_csa = dcm[(0x29, 0x1020)].value
+>>> parsed_csa = CsaHeader(raw_csa).read()
+>>> len(parsed_csa)
+79
+```
+
+The example file is an anonymized Siemens MPRAGE scan hosted on Zenodo: [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17482132.svg)](https://doi.org/10.5281/zenodo.17482132)
+
+### Option 2: Using Your Own DICOM Files
+
 Use [`pydicom`](https://github.com/pydicom/pydicom) to read a DICOM header:
 
 ```python
@@ -220,6 +251,12 @@ See [examples/nibabel_integration.py](examples/nibabel_integration.py) for compl
 
 The [examples/](examples/) directory contains comprehensive usage examples:
 
+- **[basic_usage_example.py](examples/basic_usage_example.py)**: Beginner-friendly introduction using example data
+  - Automatic download of example DICOM files
+  - Basic CSA header parsing
+  - Accessing specific CSA tags
+  - Perfect for first-time users!
+
 - **[nibabel_integration.py](examples/nibabel_integration.py)**: Complete workflow combining csa_header with NiBabel
   - Extract DWI parameters (b-values, gradients)
   - Extract fMRI parameters (slice timing, TR/TE)
@@ -228,6 +265,10 @@ The [examples/](examples/) directory contains comprehensive usage examples:
 
 Run examples:
 ```bash
+# Basic example with automatic data download
+python examples/basic_usage_example.py
+
+# NiBabel integration with your own DICOM
 python examples/nibabel_integration.py path/to/siemens_dicom.dcm
 ```
 
 
@@ -0,0 +1,197 @@
+"""Example data fetching using Pooch.
+
+This module provides functions to download example DICOM files with Siemens CSA headers
+for demonstration and testing purposes. The example data is hosted on Zenodo and
+downloaded on first use, then cached locally.
+
+Installation
+------------
+To use this module, install csa_header with the examples optional dependency::
+
+    pip install csa_header[examples]
+
+Usage
+-----
+>>> from csa_header.examples import fetch_example_dicom
+>>> dicom_path = fetch_example_dicom('mprage_example_anon.dcm')
+>>> import pydicom
+>>> dcm = pydicom.dcmread(dicom_path)
+>>> from csa_header import CsaHeader
+>>> csa = CsaHeader(dcm.get((0x29, 0x1020)).value)
+>>> result = csa.read()
+"""
+
+try:
+    import pooch  # type: ignore[import-not-found]
+
+    POOCH_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    POOCH_AVAILABLE = False  # pragma: no cover
+
+
+# Zenodo DOI and record information
+ZENODO_DOI = "10.5281/zenodo.17482132"
+ZENODO_RECORD_ID = "17482132"
+# Note: Zenodo API requires /content suffix to download actual file content
+ZENODO_BASE_URL = f"https://zenodo.org/api/records/{ZENODO_RECORD_ID}/files/{{fpath}}/content"
+
+# File registry with SHA256 checksums
+REGISTRY = {
+    "mprage_example_anon.dcm": "sha256:831fa610f8853fbd7f5602e896824480af701dfc7286f9df30d1cc2302c2022e",
+}
+
+# Available example files
+AVAILABLE_FILES = list(REGISTRY.keys())
+
+
+def fetch_example_dicom(filename="mprage_example_anon.dcm"):
+    """Fetch an example DICOM file with Siemens CSA headers.
+
+    Downloads example DICOM files from Zenodo on first use and caches them locally
+    for subsequent uses. All example files have been anonymized to remove Protected
+    Health Information (PHI).
+
+    Parameters
+    ----------
+    filename : str, optional
+        Name of the example file to fetch. Default is 'mprage_example_anon.dcm'.
+        Use `list_example_files()` to see all available files.
+
+    Returns
+    -------
+    str
+        Path to the downloaded and cached DICOM file.
+
+    Raises
+    ------
+    ImportError
+        If pooch is not installed. Install with: pip install csa_header[examples]
+    ValueError
+        If the specified filename is not available in the registry.
+
+    Examples
+    --------
+    >>> from csa_header.examples import fetch_example_dicom
+    >>> dicom_path = fetch_example_dicom()
+    >>> print(dicom_path)
+    /home/user/.cache/pooch/...mprage_example_anon.dcm
+
+    >>> # Use with pydicom and csa_header
+    >>> import pydicom
+    >>> from csa_header import CsaHeader
+    >>> dcm = pydicom.dcmread(dicom_path)
+    >>> csa_bytes = dcm.get((0x29, 0x1020)).value
+    >>> csa = CsaHeader(csa_bytes)
+    >>> tags = csa.read()
+
+    Notes
+    -----
+    The example data is hosted on Zenodo at https://doi.org/10.5281/zenodo.17482132
+    and is licensed under CC0 (Public Domain).
+
+    The MPRAGE example file contains:
+    - Modality: MR (Magnetic Resonance)
+    - Sequence: MPRAGE (Enhanced Contrast)
+    - Image dimensions: 224 x 224
+    - CSA Image Header: 11,196 bytes
+    - CSA Series Header: 139,232 bytes
+    """
+    if not POOCH_AVAILABLE:  # pragma: no cover
+        msg = (
+            "Example data fetching requires the 'pooch' package. "
+            "Install it with:\n\n"
+            "    pip install csa_header[examples]\n\n"
+            "or install pooch directly:\n\n"
+            "    pip install pooch"
+        )
+        raise ImportError(msg)
+
+    if filename not in REGISTRY:
+        available = ", ".join(AVAILABLE_FILES)
+        msg = (
+            f"File '{filename}' not found in registry. "
+            f"Available files: {available}. "
+            f"Use list_example_files() to see all options."
+        )
+        raise ValueError(msg)
+
+    # Create Pooch instance for fetching data
+    # Zenodo API requires special URL handling - we provide full URLs
+    fetcher = pooch.create(  # pragma: no cover
+        path=pooch.os_cache("csa_header"),
+        base_url="",  # Empty base_url since we provide full URLs
+        registry={filename: REGISTRY[filename]},  # Include hash in registry
+        urls={filename: f"https://zenodo.org/api/records/{ZENODO_RECORD_ID}/files/{filename}/content"},
+    )
+
+    # Fetch the file (downloads if not cached, validates checksum)
+    return fetcher.fetch(filename)  # pragma: no cover
+
+
+def list_example_files():
+    """List all available example DICOM files.
+
+    Returns
+    -------
+    list of str
+        Names of all available example files.
+
+    Examples
+    --------
+    >>> from csa_header.examples import list_example_files
+    >>> files = list_example_files()
+    >>> print(files)
+    ['mprage_example_anon.dcm']
+    """
+    return AVAILABLE_FILES.copy()
+
+
+def get_example_info(filename="mprage_example_anon.dcm"):
+    """Get information about an example file.
+
+    Parameters
+    ----------
+    filename : str, optional
+        Name of the example file. Default is 'mprage_example_anon.dcm'.
+
+    Returns
+    -------
+    dict
+        Dictionary containing information about the file including:
+        - name: filename
+        - checksum: SHA256 checksum
+        - url: Zenodo download URL
+        - doi: Zenodo DOI
+
+    Raises
+    ------
+    ValueError
+        If the specified filename is not available.
+
+    Examples
+    --------
+    >>> from csa_header.examples import get_example_info
+    >>> info = get_example_info()
+    >>> print(info['doi'])
+    10.5281/zenodo.17482132
+    """
+    if filename not in REGISTRY:
+        available = ", ".join(AVAILABLE_FILES)
+        msg = f"File '{filename}' not found in registry. Available files: {available}"
+        raise ValueError(msg)
+
+    return {
+        "name": filename,
+        "checksum": REGISTRY[filename],
+        "url": ZENODO_BASE_URL + filename,
+        "doi": ZENODO_DOI,
+    }
+
+
+__all__ = [
+    "AVAILABLE_FILES",
+    "ZENODO_DOI",
+    "fetch_example_dicom",
+    "get_example_info",
+    "list_example_files",
+]
@@ -2,8 +2,60 @@
 
 This directory contains examples demonstrating how to use csa_header in various scenarios.
 
+## Getting Started
+
+### Quick Start with Example Data
+
+The easiest way to get started is using the built-in example data:
+
+```bash
+# Install with examples support
+pip install csa_header[examples]
+
+# Run the basic example
+python basic_usage_example.py
+```
+
+This automatically downloads an anonymized example DICOM file from Zenodo (cached locally after first download).
+
 ## Examples
 
+### Basic Usage (`basic_usage_example.py`)
+
+Simple introduction to csa_header using built-in example data. Perfect for first-time users!
+
+**Features:**
+- Automatic download of example DICOM data (no need to find your own files)
+- Basic CSA header parsing
+- Accessing specific CSA tags
+- Clear, beginner-friendly code
+
+**Usage:**
+```bash
+python basic_usage_example.py
+```
+
+**Prerequisites:**
+```bash
+pip install csa_header[examples]
+```
+
+**Example output:**
+```
+BASIC CSA HEADER PARSING EXAMPLE
+======================================================================
+
+Available example files:
+  - mprage_example_anon.dcm
+
+Downloading example DICOM (cached after first download)...
+✓ Example file cached at: /home/user/.cache/pooch/...
+
+Parsing CSA headers...
+Parsed 101 tags from image header
+Parsed 79 tags from series header
+```
+
 ### NiBabel Integration (`nibabel_integration.py`)
 
 Comprehensive example showing how to integrate csa_header with NiBabel for neuroimaging workflows.