Integrate csa_header for CSA parsing?

[ZviBaratz]

Following up on the question in open-dicom/csa_header#10 about the relationship between csa_header and NiBabel - I think we should add csa_header as an optional dependency.

Why?

Our current CSA parser works, but csa_header is significantly better:

• 96% test coverage vs. our ~40%
• Complete type hints (mypy-clean)
• Built-in ASCCONV parsing
• Better error handling

Since Matthew is involved in both projects and the dependencies align (both need numpy + pydicom), this seems like a natural fit.

How?

Use the existing optional_package() pattern with an adapter for format compatibility:

from nibabel.optpkg import optional_package
csa_header_pkg, HAVE_CSA_HEADER, _ = optional_package('csa_header')

def read(csa_str):
    if HAVE_CSA_HEADER:
        return _read_with_csa_header(csa_str)  # New
    return _read_legacy(csa_str)  # Current implementation

Key points:

• Zero breaking changes (adapter converts between formats)
• Automatic fallback if csa_header not installed
• Can force legacy with NIBABEL_USE_LEGACY_CSA=1 for debugging

Changes needed:

• Add csa_header >=1.0.2,<2.0 to dicom extra in pyproject.toml
• Add CsaHeaderAdapter class (~100 lines) to convert formats
• Refactor read() to dispatcher, rename current to _read_legacy()
• Add tests for both parsers

Migration Timeline

Not proposing to remove the legacy parser anytime soon - just make the new one available:

• Now (5.4?): Add as optional, both parsers work
• Later (6.0?): Add deprecation warning for legacy
• Much later (7.0?): Consider removing legacy

This gives users 2+ years to transition if we go that route.

Questions

1. Does this make sense given csa_header's relationship to the project?
2. Should we do this for 5.4 or wait?
3. Any concerns about the approach?

[effigies]

Add csa_header >=1.0.2,<2.0 to dicom extra in pyproject.toml

I would just use >=1.0.2. If there's ever a 2.0, we can adapt to the changing API. Upper bounds tend to cause more pain than they relieve in the long run.

Otherwise this sounds good to me. No need to wait, we'll decide on the version when it comes time to release.