I/O and format conversion#

The ktch.io module handles reading and writing morphometrics file formats and converting between file-format representations and analysis-ready data structures.

Module structure#

The module provides:

Readers and writers (read_tps, write_nef, etc.) that parse or serialize specific file formats
Data containers (NefData, SpharmPdmData, etc.) that hold parsed data in a format-faithful representation
Converter functions that bridge between file-format containers and the coefficient formats used by analysis classes

Readers, writers, and data containers are organized by file format. Converters are in a single internal module (_converters.py) for discoverability.

Converters#

Bridge converters translate between a data container and the flat coefficient array that a ktch.harmonic transformer produces or consumes:

from ktch.io import (
    nef_to_efa_coeffs, efa_coeffs_to_nef,           # NEF <-> EFA
    spharmpdm_to_sha_coeffs, sha_coeffs_to_spharmpdm,  # SPHARM-PDM <-> SHA
)

Each pair follows the naming pattern {format}_to_{tool}_coeffs / {tool}_coeffs_to_{format}, where format refers to the file format and tool refers to the analysis class.

A typical workflow:

from ktch.io import read_spharmpdm_coef, spharmpdm_to_sha_coeffs
from ktch.harmonic import SphericalHarmonicAnalysis

# Read file -> data container -> analysis-ready coefficients
data = read_spharmpdm_coef("specimen.coef")
sha_coeffs = spharmpdm_to_sha_coeffs(data)

# Reconstruct surface
sha = SphericalHarmonicAnalysis(n_harmonics=data.l_max)
surface = sha.inverse_transform(sha_coeffs)

Two utility functions convert coordinate DataFrames (from read_tps or read_chc with as_frame=True) into formats suitable for analysis: convert_coords_df_to_list produces a list of per-specimen arrays, and convert_coords_df_to_df_sklearn_transform produces a wide DataFrame compatible with sklearn transformers.

Low-level format packing and unpacking functions (e.g., converting between SPHARM-PDM’s interleaved storage layout and a structured coefficient list) are private (_ prefix) and not part of the public API. Bridge converters call them internally, so users do not need to interact with them directly.

Data containers#

Each file format has a corresponding dataclass that holds parsed data:

Container	File format	Content
`NefData`	`.nef`	Normalized elliptic Fourier descriptors
`ChainCodeData`	`.chc`	Freeman chain codes
`TPSData`	`.tps`	Landmark coordinates
`SpharmPdmData`	`.coef`	SPHARM-PDM spherical harmonic coefficients

All containers implement the MorphoData protocol, providing to_numpy(), to_dataframe(), and the __array__ interface.

Data containers store coefficients in a representation faithful to the file format. For example, SpharmPdmData.coeffs uses complex-valued arrays reflecting the SPHARM-PDM convention, even though SphericalHarmonicAnalysis internally uses real spherical harmonics. The bridge converter handles the basis conversion.

Separation from analysis modules#

Converter functions live in ktch.io, not in the analysis modules (ktch.harmonic, ktch.landmark, etc.). The io module does not import from any analysis module, and analysis modules do not import from io.

This separation follows the ports-and-adapters pattern. Each analysis module defines its own input/output interface (the “port”) — for example, SphericalHarmonicAnalysis expects a flat float64 coefficient array, and GeneralizedProcrustesAnalysis expects a list of coordinate arrays. The io module provides adapters that translate between external file formats and these interfaces. File-format details do not leak into the analysis modules, and analysis modules do not need to know about any particular file format.

When a bridge converter requires domain-specific logic (e.g., complex-to-real spherical harmonic basis conversion for SPHARM-PDM), the formulas are implemented locally in _converters.py rather than imported from the analysis module. This avoids circular dependencies and keeps the modules independently testable.