feat(core): Update ReferenceAbundances to Asplund 2021 with year selection

[blalterman]

Summary

• Update ReferenceAbundances from Asplund 2009 to Asplund 2021 (A&A, 653, A141)
• Add year parameter to select between 2009 and 2021 data (default: 2021)
• Use importlib.resources for PEP 302/451 compliant package data loading
• Export ReferenceAbundances at top-level package for discoverability
• Remove orphaned duplicate implementation in solarwindpy/data/reference/

Key Changes

Element	2009	2021	Change
Fe	7.50	7.46	-0.04 dex
C	8.43	8.46	+0.03 dex
He	10.93	10.914	-0.016 dex

New Features

from solarwindpy import ReferenceAbundances

# Default uses 2021 data
ref = ReferenceAbundances()
print(ref.get_element("Fe"))  # Ab: 7.46

# Explicitly use 2009 data
ref_2009 = ReferenceAbundances(year=2009)

# Get source comment for 2021 data
ref.get_comment("H")  # 'definition'
ref.get_comment("Ne")  # 'solar wind'

Test plan

• All 168 abundance tests pass
• Full test suite passes (2205 passed)
• Doctests pass with +SKIP directives
• Top-level export works: from solarwindpy import ReferenceAbundances

🤖 Generated with Claude Code

[claude]

Claude finished @blalterman's task —— View job

---

Code Review Complete ✅

Comprehensive review of PR #424: feat(core): Update ReferenceAbundances to Asplund 2021 with year selection

Summary

This is a high-quality implementation that successfully updates the reference abundances from Asplund 2009 to 2021 while maintaining backward compatibility. The code follows excellent software engineering practices with proper error handling, comprehensive testing, and clear documentation.

Code Quality Assessment

✅ Excellent Code Quality

• Clean Architecture: Well-structured class with clear separation of concerns
• Proper Error Handling: Type checking, value validation with descriptive error messages
• Resource Management: Correct use of importlib.resources for PEP 302/451 compliance
• Documentation: Comprehensive docstrings with examples, references, and clear parameter descriptions
• Backward Compatibility: Maintains 2009 data access and "Meteorites" alias

✅ No Security Concerns

• Safe file operations using importlib.resources context manager
• Input validation prevents injection attacks
• No user-controlled file paths or dynamic imports

Technical Analysis

Implementation Highlights

• Smart Data Loading (abundances.py:109-129): Robust CSV parsing with MultiIndex handling
• Flexible Access (abundances.py:130-182): Support for both symbol and atomic number lookups
• Comment System (abundances.py:184-233): Clean handling of 2021 source methodology metadata
• Uncertainty Propagation (abundances.py:255-299): Mathematically correct uncertainty calculations

Minor Issues Found

🔍 Performance Consideration

# abundances.py:181 - Unnecessary assertion
assert out.shape[0] == 1  # Could use direct iloc[0] with try/catch

Impact: Minimal performance hit, but assertion on expected single-row result is redundant given the xs() operation should guarantee this.

🔍 Code Style

# abundances.py:225-227 - Redundant length check
if len(comment) == 1:
    comment = comment.iloc[0]  # xs() already returns single value for unique key

Testing Excellence

• Comprehensive Coverage: 168 abundance-specific tests covering both years
• Edge Cases: NaN handling, missing data, uncertainty propagation
• Data Validation: Direct verification against published Asplund tables
• Integration Tests: Top-level import functionality verified

Security & Performance

✅ Security: No vulnerabilities detected

• File access properly sandboxed through package resources
• Input validation prevents malicious keys
• No eval/exec or unsafe operations

✅ Performance: Efficient implementation

• Lazy loading with property caching
• Efficient pandas operations using xs() for MultiIndex
• O(1) element lookup performance

Data Integrity

✅ Scientific Accuracy

• Values match published Asplund 2021 Table 2 exactly
• Proper abundance scale: log ε_X = log(N_X/N_H) + 12
• Uncertainty propagation follows standard error analysis
• Comment metadata properly captures non-spectroscopic sources

Recommendations

Minor Enhancements (Optional)

1. Performance: Remove redundant assertion at line 181
2. Robustness: Add validation that CSV structure matches expected MultiIndex format
3. Documentation: Consider adding usage examples in module docstring

Architecture Praise

• Excellent use of namedtuple for Abundance return type
• Clean separation between data loading and business logic
• Proper resource management with context managers

Overall Assessment

Rating: Excellent ⭐⭐⭐⭐⭐

This PR represents exemplary scientific software development:

• ✅ Maintains scientific accuracy and references
• ✅ Preserves backward compatibility
• ✅ Implements comprehensive testing
• ✅ Uses modern Python packaging standards
• ✅ Provides clear migration path (year parameter)

Recommendation: Approve - This is production-ready code that enhances the package while maintaining reliability.

[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!