feat(solar_activity): Add ICMECAT class for HELIO4CAST ICME catalog access

[blalterman]

Summary

Add new solarwindpy.solar_activity.icme module providing class-based access to the HELIO4CAST Interplanetary Coronal Mass Ejection Catalog.

Features

• ICMECAT class with properties: data, intervals, strict_intervals, spacecraft
• Methods: filter(), contains(), summary(), get_events_in_range()
• Case-insensitive spacecraft filtering (handles ULYSSES vs Ulysses)
• Interval fallback logic: mo_end_time → mo_start_time + 24h → icme_start_time + 24h
• Optional caching with 30-day staleness check
• Proper HELIO4CAST Rules of the Road in docstrings

Usage

from solarwindpy.solar_activity.icme import ICMECAT

# Load and filter catalog
cat = ICMECAT(spacecraft="Ulysses")
print(f"Found {len(cat)} Ulysses ICMEs")

# Check if timestamps fall within ICME intervals
in_icme = cat.contains(observations.index)

# Get summary statistics
cat.summary()

Citation

If this catalog is used for published results, please cite:

Möstl et al. (2020), DOI: 10.6084/m9.figshare.6356420

Test plan

• 43 unit tests (mocked, no network required)
• 17 smoke tests (imports, docstrings, structure)
• 8 integration tests (live network)
• All 68 ICMECAT tests pass
• Exported from solarwindpy.solar_activity

🤖 Generated with Claude Code

[claude]

Claude finished @blalterman's task —— View job

---

Code Review Complete ✅

Reviewing PR #425: ICMECAT class for HELIO4CAST ICME catalog access

Review Checklist:

• Read main implementation files
• Analyze code quality and best practices
• Check for potential bugs and issues
• Review performance considerations
• Examine security concerns
• Assess test coverage and quality
• Provide comprehensive feedback

---

🎉 Overall Assessment: Excellent Implementation

This is a high-quality addition to SolarWindPy. The ICMECAT class is well-designed, thoroughly tested, and follows good software engineering practices.

✅ Strengths

Architecture & Design

• Clean, well-structured class with clear separation of concerns
• Proper use of properties for read-only access (data, intervals, strict_intervals)
• Sensible fallback logic for missing interval endpoints
• Good logging integration using instance-specific loggers

Error Handling

• Graceful handling of edge cases (empty catalogs, missing data)
• Case-insensitive spacecraft filtering with clear error messages
• Robust fallback strategies for missing mo_end_time values

Performance

• Smart caching with 30-day staleness check using Parquet format
• Efficient vectorized containment checking with numpy searchsorted
• Minimal data copying with proper use of .copy() when needed

Documentation

• Comprehensive docstrings with proper citation and Rules of the Road
• Clear examples and parameter descriptions
• Good class-level documentation explaining the fallback logic

Testing - Exceptional coverage (704 lines across 3 test files)

• 43 unit tests covering all functionality with mocked data
• 17 smoke tests for imports and structure validation
• 8 integration tests with real network data
• Edge case testing (empty catalogs, all NaT values, etc.)
• Proper test isolation using fixtures and mocking

🔍 Code Quality Observations

Type Hints & Modern Python

# Good use of Optional and proper typing
def __init__(self, spacecraft: Optional[str] = None, cache_dir: Optional[Path] = None):

# Modern union syntax could be used (Python 3.10+)
def contains(self, times: pd.DatetimeIndex | pd.Series) -> pd.Series:

Memory Efficiency

• Proper use of frozenset for SPACECRAFT_NAMES (immutable, efficient lookups)
• Strategic use of .copy() to prevent accidental mutation
• Efficient Parquet caching instead of CSV

Robust Interval Logic

# Well-designed 3-level fallback for interval endpoints:
# 1. mo_end_time (preferred)
# 2. mo_start_time + 24h (reasonable fallback) 
# 3. icme_start_time + 24h (last resort)

🛡️ Security & Safety

✅ No Security Concerns Found

• HTTPS URL for data source
• No user input validation issues (pandas handles malformed timestamps)
• No file path injection risks (uses pathlib properly)
• No secrets or credentials exposed

Input Validation

• Case-insensitive spacecraft filtering prevents user errors
• Proper handling of malformed datetime inputs via pandas
• Graceful degradation for network failures

🚀 Performance Considerations

Efficient Operations

• np.searchsorted() for O(log n) interval searches vs O(n²) naive approach
• Smart caching reduces repeated downloads
• Vectorized operations throughout

Potential Optimizations (minor)

# Current O(n) containment check could use interval trees for O(log n)
# But given typical ICME catalog size (~1000s events), current approach is fine

📊 Test Coverage Analysis

Comprehensive Coverage Validated

• Unit tests (503 lines): All methods, properties, edge cases
• Integration tests (87 lines): Real data validation, multi-spacecraft
• Smoke tests (114 lines): Import validation, docstring presence
• Total: 704 test lines for 397-line implementation = 177% test-to-code ratio

Well-Structured Test Organization

# Clear test class organization by functionality:
TestICMECATInitialization     # Constructor behavior
TestICMECATDataProperty       # Data access and validation
TestICMECATIntervals          # Interval computation logic  
TestICMECATContains          # Containment checking algorithm
TestICMECATSummary           # Statistical methods

🐛 No Significant Issues Found

Minor Suggestions (not required for merge)

1. Type annotation consistency: Mix of | and Optional syntax
2. Potential async support: Future enhancement for concurrent downloads
3. Interval tree optimization: For very large catalogs (not needed now)

📋 Integration Verification

✅ Proper Module Integration

• Correctly exported from solarwindpy.solar_activity.__init__.py
• Follows project naming conventions
• Compatible with existing SolarWindPy patterns

🎯 Recommendation: APPROVE

This PR represents excellent software engineering with:

• Robust implementation handling real-world data complexities
• Exceptional test coverage (177% test-to-code ratio)
• Clear documentation with proper scientific attribution
• No security or performance concerns
• Clean integration with existing codebase

The implementation is production-ready and follows SolarWindPy quality standards.

[github-actions]

SolarWindPy Documentation Validation - Python 3.11

✅ Status: PASSED

Essential Metrics:

• Files: 44
• Tests: 20
• Failed: 0
• Success Rate: 100.0%
• Approach: Targeted validation (core physics modules)

🎉 All essential documentation examples working!

[claude]

Claude finished @blalterman's task —— View job

---

Code Review Complete ✅

Reviewing PR #425: ICMECAT class for HELIO4CAST ICME catalog access

Review Checklist:

• Read main implementation files
• Analyze code quality and best practices
• Check for potential bugs and issues
• Review performance considerations
• Examine security concerns
• Assess test coverage and quality
• Provide comprehensive feedback

---

🎉 Overall Assessment: Excellent Implementation

This is a high-quality addition to SolarWindPy. The ICMECAT class is well-designed, thoroughly tested, and follows good software engineering practices.

✅ Strengths

Architecture & Design

• Clean, well-structured class with clear separation of concerns
• Proper use of properties for read-only access (data, intervals, strict_intervals)
• Sensible fallback logic for missing interval endpoints
• Good logging integration using instance-specific loggers

Error Handling

• Graceful handling of edge cases (empty catalogs, missing data)
• Case-insensitive spacecraft filtering with clear error messages
• Robust fallback strategies for missing mo_end_time values

Performance

• Smart caching with 30-day staleness check using Parquet format
• Efficient vectorized containment checking with numpy searchsorted
• Minimal data copying with proper use of .copy() when needed

Documentation

• Comprehensive docstrings with proper citation and Rules of the Road
• Clear examples and parameter descriptions
• Good class-level documentation explaining the fallback logic

Testing - Exceptional coverage (704 lines across 3 test files)

• 43 unit tests covering all functionality with mocked data
• 17 smoke tests for imports and structure validation
• 8 integration tests with real network data
• Edge case testing (empty catalogs, all NaT values, etc.)
• Proper test isolation using fixtures and mocking

🔍 Code Quality Observations

Type Hints & Modern Python

# Good use of Optional and proper typing
def __init__(self, spacecraft: Optional[str] = None, cache_dir: Optional[Path] = None):

# Modern union syntax could be used (Python 3.10+)
def contains(self, times: pd.DatetimeIndex | pd.Series) -> pd.Series:

Memory Efficiency

• Proper use of frozenset for SPACECRAFT_NAMES (immutable, efficient lookups)
• Strategic use of .copy() to prevent accidental mutation
• Efficient Parquet caching instead of CSV

Robust Interval Logic

# Well-designed 3-level fallback for interval endpoints:
# 1. mo_end_time (preferred)
# 2. mo_start_time + 24h (reasonable fallback) 
# 3. icme_start_time + 24h (last resort)

🛡️ Security & Safety

✅ No Security Concerns Found

• HTTPS URL for data source
• No user input validation issues (pandas handles malformed timestamps)
• No file path injection risks (uses pathlib properly)
• No secrets or credentials exposed

Input Validation

• Case-insensitive spacecraft filtering prevents user errors
• Proper handling of malformed datetime inputs via pandas
• Graceful degradation for network failures

🚀 Performance Considerations

Efficient Operations

• np.searchsorted() for O(log n) interval searches vs O(n²) naive approach
• Smart caching reduces repeated downloads
• Vectorized operations throughout

Potential Optimizations (minor)

# Current O(n) containment check could use interval trees for O(log n)
# But given typical ICME catalog size (~1000s events), current approach is fine

📊 Test Coverage Analysis

Comprehensive Coverage Validated

• Unit tests (503 lines): All methods, properties, edge cases
• Integration tests (87 lines): Real data validation, multi-spacecraft
• Smoke tests (114 lines): Import validation, docstring presence
• Total: 704 test lines for 397-line implementation = 177% test-to-code ratio

Well-Structured Test Organization

# Clear test class organization by functionality:
TestICMECATInitialization     # Constructor behavior
TestICMECATDataProperty       # Data access and validation
TestICMECATIntervals          # Interval computation logic  
TestICMECATContains          # Containment checking algorithm
TestICMECATSummary           # Statistical methods

🐛 No Significant Issues Found

Minor Suggestions (not required for merge)

1. Type annotation consistency: Mix of | and Optional syntax
2. Potential async support: Future enhancement for concurrent downloads
3. Interval tree optimization: For very large catalogs (not needed now)

📋 Integration Verification

✅ Proper Module Integration

• Correctly exported from solarwindpy.solar_activity.__init__.py
• Follows project naming conventions
• Compatible with existing SolarWindPy patterns

🎯 Recommendation: APPROVE

This PR represents excellent software engineering with:

• Robust implementation handling real-world data complexities
• Exceptional test coverage (177% test-to-code ratio)
• Clear documentation with proper scientific attribution
• No security or performance concerns
• Clean integration with existing codebase

The implementation is production-ready and follows SolarWindPy quality standards.

---

[github-actions]

SolarWindPy Documentation Validation - Python 3.11

✅ Status: PASSED

Essential Metrics:

• Files: 44
• Tests: 20
• Failed: 0
• Success Rate: 100.0%
• Approach: Targeted validation (core physics modules)

🎉 All essential documentation examples working!

[claude]

Claude finished @blalterman's task —— View job

---

Code Review Complete ✅

Reviewing PR #425: ICMECAT class for HELIO4CAST ICME catalog access

Review Checklist:

• Read main implementation files
• Analyze code quality and best practices
• Check for potential bugs and issues
• Review performance considerations
• Examine security concerns
• Assess test coverage and quality
• Provide comprehensive feedback

---

🎉 Overall Assessment: Excellent Implementation

This is a high-quality addition to SolarWindPy. The ICMECAT class is well-designed, thoroughly tested, and follows good software engineering practices.

✅ Strengths

Architecture & Design

• Clean, well-structured class with clear separation of concerns
• Proper use of properties for read-only access (data, intervals, strict_intervals)
• Sensible fallback logic for missing interval endpoints
• Good logging integration using instance-specific loggers

Error Handling

• Graceful handling of edge cases (empty catalogs, missing data)
• Case-insensitive spacecraft filtering with clear error messages
• Robust fallback strategies for missing mo_end_time values

Performance

• Smart caching with 30-day staleness check using Parquet format
• Efficient vectorized containment checking with numpy searchsorted
• Minimal data copying with proper use of .copy() when needed

Documentation

• Comprehensive docstrings with proper citation and Rules of the Road
• Clear examples and parameter descriptions
• Good class-level documentation explaining the fallback logic

Testing - Exceptional coverage (704 lines across 3 test files)

• 43 unit tests covering all functionality with mocked data
• 17 smoke tests for imports and structure validation
• 8 integration tests with real network data
• Edge case testing (empty catalogs, all NaT values, etc.)
• Proper test isolation using fixtures and mocking

🔍 Code Quality Observations

Type Hints & Modern Python

# Good use of Optional and proper typing
def __init__(self, spacecraft: Optional[str] = None, cache_dir: Optional[Path] = None):

# Modern union syntax could be used (Python 3.10+)
def contains(self, times: pd.DatetimeIndex | pd.Series) -> pd.Series:

Memory Efficiency

• Proper use of frozenset for SPACECRAFT_NAMES (immutable, efficient lookups)
• Strategic use of .copy() to prevent accidental mutation
• Efficient Parquet caching instead of CSV

Robust Interval Logic

# Well-designed 3-level fallback for interval endpoints:
# 1. mo_end_time (preferred)
# 2. mo_start_time + 24h (reasonable fallback) 
# 3. icme_start_time + 24h (last resort)

🛡️ Security & Safety

✅ No Security Concerns Found

• HTTPS URL for data source
• No user input validation issues (pandas handles malformed timestamps)
• No file path injection risks (uses pathlib properly)
• No secrets or credentials exposed

Input Validation

• Case-insensitive spacecraft filtering prevents user errors
• Proper handling of malformed datetime inputs via pandas
• Graceful degradation for network failures

🚀 Performance Considerations

Efficient Operations

• np.searchsorted() for O(log n) interval searches vs O(n²) naive approach
• Smart caching reduces repeated downloads
• Vectorized operations throughout

Potential Optimizations (minor)

# Current O(n) containment check could use interval trees for O(log n)
# But given typical ICME catalog size (~1000s events), current approach is fine

📊 Test Coverage Analysis

Comprehensive Coverage Validated

• Unit tests (503 lines): All methods, properties, edge cases
• Integration tests (87 lines): Real data validation, multi-spacecraft
• Smoke tests (114 lines): Import validation, docstring presence
• Total: 704 test lines for 397-line implementation = 177% test-to-code ratio

Well-Structured Test Organization

# Clear test class organization by functionality:
TestICMECATInitialization     # Constructor behavior
TestICMECATDataProperty       # Data access and validation
TestICMECATIntervals          # Interval computation logic  
TestICMECATContains          # Containment checking algorithm
TestICMECATSummary           # Statistical methods

🐛 No Significant Issues Found

Minor Suggestions (not required for merge)

1. Type annotation consistency: Mix of | and Optional syntax
2. Potential async support: Future enhancement for concurrent downloads
3. Interval tree optimization: For very large catalogs (not needed now)

📋 Integration Verification

✅ Proper Module Integration

• Correctly exported from solarwindpy.solar_activity.__init__.py
• Follows project naming conventions
• Compatible with existing SolarWindPy patterns

🎯 Recommendation: APPROVE

This PR represents excellent software engineering with:

• Robust implementation handling real-world data complexities
• Exceptional test coverage (177% test-to-code ratio)
• Clear documentation with proper scientific attribution
• No security or performance concerns
• Clean integration with existing codebase

The implementation is production-ready and follows SolarWindPy quality standards.

---

[github-actions]

SolarWindPy Documentation Validation - Python 3.11

✅ Status: PASSED

Essential Metrics:

• Files: 44
• Tests: 20
• Failed: 0
• Success Rate: 100.0%
• Approach: Targeted validation (core physics modules)

🎉 All essential documentation examples working!