MTH5 Validator Quick Start

Installation

The validator is included with mth5 v0.6.1+:

pip install mth5

Quick Validation

Command Line

# Basic validation
mth5-cli validate myfile.mth5

# Verbose output (shows all checks)
mth5-cli validate myfile.mth5 --verbose

# Check data integrity (slower)
mth5-cli validate myfile.mth5 --check-data

# JSON output (for scripts/CI)
mth5-cli validate myfile.mth5 --json

Python

from mth5.utils.mth5_validator import validate_mth5_file

# Validate a file
results = validate_mth5_file('myfile.mth5')

# Check results
if results.is_valid:
    print("✓ File is valid!")
else:
    print(f"✗ Found {results.error_count} errors")
    results.print_report()

What Gets Validated?

✓ File format (HDF5 structure)
✓ MTH5 version (0.1.0 or 0.2.0)
✓ Required groups (Survey/Experiment, Stations, etc.)
✓ Group hierarchy
✓ Metadata attributes
✓ Summary tables
✓ Optional: Channel data integrity

Common Use Cases

Pre-Processing Check

from mth5.utils.mth5_validator import validate_mth5_file

def safe_process(filepath):
    results = validate_mth5_file(filepath)
    if not results.is_valid:
        raise ValueError(f"Invalid file: {filepath}")
    # Continue processing...

Batch Validation

# Validate all files in directory
for file in data/*.mth5; do
    mth5-cli validate "$file" || echo "FAILED: $file"
done

CI/CD Integration

# In your CI pipeline
mth5-cli validate data.mth5 --json > validation_report.json
mth5-cli validate data.mth5  # Exit code 0=valid, 1=invalid

Output Examples

Valid File

================================================================================
MTH5 Validation Report: data.mth5
================================================================================
✓ VALID - File passed all validation checks

Summary:
  Errors:   0
  Warnings: 0
  Info:     8

Invalid File

================================================================================
MTH5 Validation Report: data.mth5
================================================================================
✗ INVALID - File has 2 error(s)

Summary:
  Errors:   2
  Warnings: 1
  Info:     5

Details:
--------------------------------------------------------------------------------
  [ERROR] File Format: Missing 'file.version' attribute in root
  [ERROR] Structure: Missing required group 'Experiment'
  [WARNING] Structure: Missing 'channel_summary' dataset

JSON Output

mth5-cli validate data.mth5 --json

{
  "file_path": "data.mth5",
  "is_valid": true,
  "error_count": 0,
  "warning_count": 0,
  "info_count": 8,
  "messages": [
    {
      "level": "INFO",
      "category": "File Format",
      "message": "File type: MTH5",
      "path": null
    }
  ]
}

Advanced Usage

Full Validation (with data checks)

from mth5.utils.mth5_validator import MTH5Validator

validator = MTH5Validator(
    'data.mth5',
    verbose=True,
    validate_metadata=True,
    check_data=True  # Checks channel data
)

results = validator.validate()
results.print_report(include_info=True)

Structure Only (fast)

validator = MTH5Validator(
    'data.mth5',
    validate_metadata=False,  # Skip metadata checks
    check_data=False          # Skip data checks
)
results = validator.validate()

Help

# CLI help
mth5-cli --help
mth5-cli validate --help

# Python help
python -c "from mth5.utils.mth5_validator import MTH5Validator; help(MTH5Validator)"

Documentation

Troubleshooting

Import Error

# Correct import (avoid circular import)
from mth5.utils.mth5_validator import MTH5Validator, validate_mth5_file

File Access Error

Ensure file is not open elsewhere:

import h5py
h5py.File.close_open_files()

Validation Too Strict

Skip optional checks:

validator = MTH5Validator('data.mth5', validate_metadata=False)

Support