solarwindpy 0.0.1.dev0__py3-none-any.whl → 0.1.1__py3-none-any.whl

plans/completed/combined_test_plan_with_checklist_plotting/13-labels-datetime.py.md

@@ -0,0 +1,247 @@
+---
+name: 'Combined Plan and Checklist: DateTime Labels'
+about: Unified documentation and checklist for validating datetime-related plotting labels.
+labels: [sweep, plotting, labels, datetime, Timedelta, ArbitraryLabel]
+---
+
+> Phase 14 of Enhanced Plotting Test Plan
+
+## 🧠 Context
+
+The `solarwindpy.plotting.labels.datetime` module provides specialized labels for time-related quantities, particularly time intervals and durations commonly used in time series analysis and plasma physics data visualization. The module focuses on the `Timedelta` class that provides proper formatting for time intervals with LaTeX rendering support.
+
+### Key Components
+- **Timedelta Class**: Represents time intervals with proper formatting
+- **Pandas Integration**: Uses `pandas.tseries.frequencies.to_offset` for time parsing
+- **LaTeX Formatting**: Automatic LaTeX generation with units
+- **ArbitraryLabel Inheritance**: Builds on special label infrastructure
+
+### Scientific Context
+- Time series analysis for plasma physics data
+- Duration labeling for event analysis
+- Standardized time interval notation
+- Integration with pandas time offset functionality
+
+## 📋 Comprehensive Test Checklist
+
+### 14.1 Module Structure and Imports
+
+- [ ] **Import verification**: All required imports load correctly
+- [ ] **Path integration**: `from pathlib import Path` works properly
+- [ ] **Pandas integration**: `from pandas.tseries.frequencies import to_offset` functions
+- [ ] **Base imports**: `from . import base` and `from . import special` work
+- [ ] **Debug import**: `import pdb` present for development (noqa handled)
+
+### 14.2 Timedelta Class Structure
+
+#### Inheritance and initialization
+- [ ] **ArbitraryLabel inheritance**: `Timedelta` inherits from `special.ArbitraryLabel`
+- [ ] **Initialization**: `__init__(offset)` works correctly
+- [ ] **Super call**: `super().__init__()` called appropriately
+- [ ] **Offset setting**: `set_offset(offset)` called in initialization
+
+### 14.3 Timedelta Class Methods
+
+#### String representation
+- [ ] **`__str__` method**: Returns `self.with_units` correctly
+- [ ] **String conversion**: Timedelta converts to string appropriately
+- [ ] **Consistency**: String representation consistent with display format
+- [ ] **Encoding**: Handles special characters in string conversion
+
+#### `with_units` property
+- [ ] **LaTeX formatting**: Returns properly formatted LaTeX string
+- [ ] **Format structure**: Uses `f"${self.tex} \; [{self.units}]$"` format
+- [ ] **LaTeX delimiters**: Dollar signs properly delimit LaTeX expression
+- [ ] **Unit formatting**: Units enclosed in square brackets
+- [ ] **Spacing**: Proper spacing (`\;`) between tex and units
+- [ ] **Escape handling**: Backslash escape handled correctly (noqa comment)
+
+### 14.4 Offset Handling and Validation
+
+#### `set_offset()` method (inherited/implemented)
+- [ ] **Pandas offset conversion**: Uses `to_offset()` for parsing
+- [ ] **String offsets**: Handles string offset specifications (e.g., "1H", "30T")
+- [ ] **Pandas offset objects**: Accepts existing pandas offset objects
+- [ ] **Offset validation**: Invalid offsets handled appropriately
+- [ ] **Offset storage**: Parsed offsets stored correctly
+
+#### Supported offset types
+- [ ] **Common frequencies**: Handles common time frequencies
+  - [ ] Minutes: "T", "min"
+  - [ ] Hours: "H", "h" 
+  - [ ] Days: "D"
+  - [ ] Seconds: "S", "s"
+- [ ] **Complex offsets**: Handles composite offsets (e.g., "1H30T")
+- [ ] **Custom offsets**: Handles custom time specifications
+
+### 14.5 LaTeX Generation and Properties
+
+#### LaTeX (`tex`) property
+- [ ] **LaTeX generation**: Generates appropriate LaTeX for time intervals
+- [ ] **Mathematical notation**: Uses proper mathematical symbols
+- [ ] **Time notation**: Follows standard time interval notation
+- [ ] **Readability**: Generated LaTeX clear and readable
+
+#### Units property
+- [ ] **Unit specification**: Provides appropriate units for time intervals
+- [ ] **Unit consistency**: Units consistent with offset specification
+- [ ] **Standard units**: Uses standard time unit abbreviations
+- [ ] **Unit accuracy**: Units accurately represent time intervals
+
+### 14.6 Integration with Pandas
+
+#### Pandas offset compatibility
+- [ ] **Offset parsing**: `to_offset()` integration works correctly
+- [ ] **Error handling**: Pandas parsing errors handled appropriately
+- [ ] **Frequency aliases**: Standard pandas frequency aliases supported
+- [ ] **Custom frequencies**: Custom frequency specifications work
+
+#### Time series integration
+- [ ] **DataFrame compatibility**: Works with pandas DataFrame time indices
+- [ ] **Time operations**: Compatible with pandas time operations
+- [ ] **Resampling**: Works with pandas resampling operations
+- [ ] **Period handling**: Handles time period specifications
+
+### 14.7 Error Handling and Validation
+
+#### Invalid offset handling
+- [ ] **Invalid strings**: Proper error handling for invalid offset strings
+- [ ] **Type errors**: Handles incorrect parameter types gracefully
+- [ ] **Empty offsets**: Behavior with empty or None offset parameters
+- [ ] **Error messages**: Clear error messages for invalid inputs
+
+#### Edge cases
+- [ ] **Zero offsets**: Handles zero-duration time intervals
+- [ ] **Negative offsets**: Behavior with negative time intervals
+- [ ] **Very large offsets**: Handles extremely large time intervals
+- [ ] **Very small offsets**: Handles very small time intervals (microseconds, etc.)
+
+### 14.8 Display and Formatting
+
+#### Visual representation
+- [ ] **Plot integration**: Labels display correctly in matplotlib plots
+- [ ] **Font rendering**: LaTeX fonts render appropriately
+- [ ] **Size scaling**: Labels scale properly with plot size
+- [ ] **Readability**: Labels remain readable at different plot sizes
+
+#### Format consistency
+- [ ] **Standard formatting**: Follows standard time interval notation
+- [ ] **Mathematical style**: Consistent with other mathematical labels
+- [ ] **Unit placement**: Units placed consistently relative to values
+- [ ] **Bracket usage**: Square brackets used consistently for units
+
+### 14.9 Integration with ArbitraryLabel
+
+#### Inherited functionality
+- [ ] **Base methods**: ArbitraryLabel methods accessible and functional
+- [ ] **Property inheritance**: Base properties work correctly
+- [ ] **Method overrides**: Overridden methods work as expected
+- [ ] **Polymorphism**: Works correctly as ArbitraryLabel instance
+
+#### Label system integration
+- [ ] **Label collections**: Works in label collection contexts
+- [ ] **Label management**: Integrates with label management systems
+- [ ] **Serialization**: Serializes/deserializes if supported
+- [ ] **Comparison**: Comparison operations work appropriately
+
+### 14.10 Path and File Integration
+
+#### Path generation (if implemented)
+- [ ] **File paths**: Generates valid file paths from time intervals
+- [ ] **Path safety**: Generated paths safe for file systems
+- [ ] **Path uniqueness**: Different intervals generate unique paths
+- [ ] **Cross-platform**: Paths work across operating systems
+
+### 14.11 Performance and Memory
+
+#### Memory efficiency
+- [ ] **Object size**: Timedelta objects use memory efficiently
+- [ ] **String caching**: LaTeX strings cached appropriately
+- [ ] **Offset storage**: Time offsets stored efficiently
+- [ ] **Cleanup**: No memory leaks with repeated creation
+
+#### Performance characteristics
+- [ ] **Creation speed**: Timedelta objects created quickly
+- [ ] **String generation**: String representation generated efficiently
+- [ ] **LaTeX rendering**: LaTeX generation reasonably fast
+- [ ] **Pandas integration**: Pandas operations don't slow significantly
+
+### 14.12 Scientific Accuracy and Standards
+
+#### Time notation standards
+- [ ] **Scientific notation**: Follows scientific time notation standards
+- [ ] **Unit abbreviations**: Uses standard time unit abbreviations
+- [ ] **Mathematical notation**: Mathematical symbols used correctly
+- [ ] **Consistency**: Notation consistent across different time scales
+
+#### Domain relevance
+- [ ] **Plasma physics**: Relevant for plasma physics time scales
+- [ ] **Space science**: Appropriate for space science applications
+- [ ] **Data analysis**: Suitable for time series data analysis
+- [ ] **Research context**: Fits research workflow requirements
+
+### 14.13 Documentation and Examples
+
+#### Documentation quality
+- [ ] **Class docstring**: Clear documentation for Timedelta class
+- [ ] **Method documentation**: All methods properly documented
+- [ ] **Parameter documentation**: Parameters clearly described with types
+- [ ] **Usage examples**: Working code examples provided
+
+#### Examples and use cases
+- [ ] **Common intervals**: Examples of common time intervals
+- [ ] **Complex offsets**: Examples of complex time specifications
+- [ ] **Plot integration**: Examples of usage in plotting contexts
+- [ ] **Real-world usage**: Realistic usage scenarios documented
+
+### 14.14 Test Infrastructure
+
+#### Test framework
+- [ ] **Unit tests**: Tests for individual Timedelta methods
+- [ ] **Integration tests**: Tests with pandas and matplotlib
+- [ ] **Property testing**: All properties tested independently
+- [ ] **Error condition testing**: Invalid inputs tested appropriately
+
+#### Test data
+- [ ] **Representative intervals**: Test data covers common time intervals
+- [ ] **Edge cases**: Unusual time specifications tested
+- [ ] **Invalid cases**: Invalid inputs tested for error handling
+- [ ] **Scientific cases**: Time intervals relevant to scientific data
+
+## 🎯 Testing Strategy
+
+### Unit Testing Approach
+- Test Timedelta initialization with various offset types
+- Verify LaTeX generation for different time intervals
+- Test string representation and formatting
+- Validate pandas integration and error handling
+
+### Integration Testing
+- Test Timedelta labels in actual plotting scenarios
+- Verify LaTeX rendering in matplotlib contexts
+- Test integration with pandas time series operations
+- Validate time interval accuracy in scientific contexts
+
+### Edge Case Coverage
+- Invalid time specifications
+- Extreme time intervals (very large/small)
+- Complex pandas offset expressions
+- Error conditions and recovery
+
+### Scientific Validation
+- Verify time notation follows scientific standards
+- Test relevance for plasma physics time scales
+- Validate integration with time series analysis workflows
+- Test accuracy of time interval representations
+
+---
+
+**Estimated Time**: 1.5 hours  
+**Dependencies**: ArbitraryLabel, pandas time series, LaTeX rendering  
+**Priority**: MEDIUM (Time series analysis functionality)
+
+**Status**: ✅ COMPLETED
+**Commit**: 5b47880  
+**Tests Added**: 50 comprehensive test cases
+**Time Invested**: 1.5 hours
+**Test Results**: 50/50 passing (100% success rate)

plans/completed/combined_test_plan_with_checklist_plotting/14-labels-elemental_abundance.py.md

@@ -0,0 +1,274 @@
+---
+name: 'Combined Plan and Checklist: Elemental Abundance Labels'
+about: Unified documentation and checklist for validating elemental abundance plotting labels.
+labels: [sweep, plotting, labels, elemental_abundance, ElementalAbundance]
+---
+
+> Phase 15 of Enhanced Plotting Test Plan
+
+## 🧠 Context
+
+The `solarwindpy.plotting.labels.elemental_abundance` module provides specialized labels for elemental abundance ratios, a critical component in solar wind and plasma composition analysis. The `ElementalAbundance` class handles the creation of properly formatted labels for abundance ratios relative to reference species (typically hydrogen) with optional photospheric normalization.
+
+### Key Components
+- **ElementalAbundance Class**: Handles elemental abundance ratio labeling
+- **Species Management**: Supports known plasma species with validation
+- **Reference Species**: Normalization relative to reference elements
+- **Photospheric Scaling**: Optional photospheric abundance normalization
+- **Unit Options**: Percentage or fractional abundance units
+
+### Scientific Context
+- Solar wind elemental composition analysis
+- Abundance ratios relative to hydrogen or other reference species
+- Photospheric vs. solar wind abundance comparisons
+- Standardized abundance notation for scientific publications
+
+## 📋 Comprehensive Test Checklist
+
+### 15.1 Module Structure and Exports
+
+- [ ] **Export validation**: `__all__` contains `["ElementalAbundance"]`
+- [ ] **Import verification**: All required imports load correctly
+- [ ] **Logging integration**: `import logging` works for debugging
+- [ ] **Path integration**: `from pathlib import Path` functions properly
+- [ ] **Base integration**: `from . import base` import works correctly
+
+### 15.2 Known Species Management
+
+#### Species tuple definition
+- [ ] **Species source**: `known_species` derived from `base._trans_species.keys()`
+- [ ] **Additional species**: Includes "X" for unknown/placeholder species
+- [ ] **Tuple immutability**: Species tuple immutable after definition
+- [ ] **Species completeness**: Covers relevant plasma species
+
+#### Species validation
+- [ ] **Known species coverage**: Includes common solar wind elements
+- [ ] **Species format**: Species names in appropriate format
+- [ ] **Extension capability**: System handles additional species appropriately
+- [ ] **Placeholder handling**: "X" species handled correctly
+
+### 15.3 ElementalAbundance Class Structure
+
+#### Inheritance and initialization
+- [ ] **Base inheritance**: `ElementalAbundance` inherits from `base.Base`
+- [ ] **Initialization parameters**: `__init__(species, reference_species, pct_unit, photospheric)`
+- [ ] **Parameter handling**: All parameters processed correctly
+- [ ] **Default values**: Default values applied appropriately
+
+#### Initialization logic
+- [ ] **Species setting**: `set_species(species, reference_species)` called
+- [ ] **Boolean conversion**: `pct_unit` and `photospheric` converted to bool
+- [ ] **State storage**: Internal state stored correctly
+- [ ] **Validation**: Parameters validated during initialization
+
+### 15.4 Core Properties
+
+#### Species property
+- [ ] **Species getter**: `@property species` returns stored species
+- [ ] **Species storage**: `_species` attribute contains correct value
+- [ ] **Species immutability**: Species cannot be modified after creation
+- [ ] **Species type**: Species stored as appropriate type
+
+#### Reference species property
+- [ ] **Reference getter**: `@property reference_species` returns reference
+- [ ] **Reference storage**: `_reference_species` stored correctly
+- [ ] **Reference immutability**: Reference species protected from modification
+- [ ] **Reference validation**: Reference species validated appropriately
+
+#### Photospheric property
+- [ ] **Photospheric getter**: `@property photospheric` returns boolean
+- [ ] **Boolean storage**: `_photospheric` stored as boolean
+- [ ] **Default handling**: Default photospheric value handled correctly
+- [ ] **Type consistency**: Always returns boolean type
+
+### 15.5 Species Validation and Setting
+
+#### `set_species()` method
+- [ ] **Species validation**: Both species and reference validated
+- [ ] **Known species check**: Unknown species handled appropriately
+- [ ] **Species storage**: Valid species stored in instance attributes
+- [ ] **Error handling**: Invalid species combinations handled gracefully
+
+#### Species compatibility
+- [ ] **Self-reference check**: Prevents species being its own reference
+- [ ] **Species existence**: Validates species exist in known list
+- [ ] **Case handling**: Proper case handling for species names
+- [ ] **Special species**: "X" placeholder species handled correctly
+
+### 15.6 Label Generation and Formatting
+
+#### LaTeX generation (if implemented)
+- [ ] **Abundance notation**: Generates proper abundance ratio notation
+- [ ] **Species formatting**: Species names formatted correctly in LaTeX
+- [ ] **Reference notation**: Reference species notation appropriate
+- [ ] **Mathematical formatting**: Ratio notation mathematically correct
+
+#### Units handling
+- [ ] **Percentage units**: `pct_unit=True` generates percentage notation
+- [ ] **Fractional units**: `pct_unit=False` generates fractional notation
+- [ ] **Unit consistency**: Units consistent with abundance type
+- [ ] **Scientific notation**: Follows standard abundance notation
+
+### 15.7 Photospheric Normalization
+
+#### Normalization logic
+- [ ] **Photospheric flag**: `photospheric=True` enables normalization
+- [ ] **Non-photospheric**: `photospheric=False` uses raw abundances
+- [ ] **Normalization indication**: Labels indicate normalization status
+- [ ] **Scientific accuracy**: Normalization scientifically appropriate
+
+#### Reference scaling
+- [ ] **Photospheric values**: Access to photospheric abundance values
+- [ ] **Scaling factors**: Correct scaling factors applied
+- [ ] **Reference consistency**: Consistent reference across normalizations
+- [ ] **Unit preservation**: Units maintained through normalization
+
+### 15.8 Path and File Integration
+
+#### Path generation (if implemented)
+- [ ] **Path creation**: Generates valid Path objects for file naming
+- [ ] **Species encoding**: Species names encoded safely for file systems
+- [ ] **Reference encoding**: Reference species encoded in paths
+- [ ] **Uniqueness**: Different abundance ratios generate unique paths
+
+#### File system compatibility
+- [ ] **Cross-platform paths**: Paths work across operating systems
+- [ ] **Special character handling**: Handles special characters safely
+- [ ] **Path length**: Generated paths reasonable length
+- [ ] **Collision avoidance**: Avoids path collisions
+
+### 15.9 Integration with Base Classes
+
+#### Base class integration
+- [ ] **Logger access**: Inherits logging functionality from base
+- [ ] **Base methods**: Base class methods accessible and functional
+- [ ] **Property inheritance**: Base properties work correctly
+- [ ] **Initialization chain**: Base initialization called appropriately
+
+#### Method inheritance
+- [ ] **Inherited functionality**: Base class functionality preserved
+- [ ] **Method overrides**: Overridden methods work correctly
+- [ ] **Polymorphism**: Works as Base instance where expected
+- [ ] **Interface compatibility**: Compatible with base class interface
+
+### 15.10 Error Handling and Validation
+
+#### Parameter validation
+- [ ] **Invalid species**: Handles unknown species gracefully
+- [ ] **Invalid reference**: Handles invalid reference species
+- [ ] **Type validation**: Validates parameter types appropriately
+- [ ] **Value validation**: Validates parameter values
+
+#### Error conditions
+- [ ] **Self-reference error**: Prevents species referencing itself
+- [ ] **Missing species error**: Handles missing species appropriately
+- [ ] **Invalid combinations**: Prevents invalid species combinations
+- [ ] **Clear error messages**: Provides informative error messages
+
+### 15.11 Scientific Accuracy and Standards
+
+#### Abundance notation standards
+- [ ] **Scientific notation**: Follows standard abundance notation
+- [ ] **Ratio representation**: Ratios represented correctly
+- [ ] **Unit standards**: Units follow scientific conventions
+- [ ] **Reference standards**: Reference species choices appropriate
+
+#### Domain relevance
+- [ ] **Solar wind context**: Relevant for solar wind composition
+- [ ] **Plasma physics**: Appropriate for plasma composition analysis
+- [ ] **Comparative studies**: Suitable for abundance comparisons
+- [ ] **Publication quality**: Labels suitable for scientific publications
+
+### 15.12 Performance and Memory
+
+#### Memory efficiency
+- [ ] **Object size**: ElementalAbundance objects use memory efficiently
+- [ ] **Species storage**: Species names stored without duplication
+- [ ] **Reference caching**: Reference values cached appropriately
+- [ ] **Cleanup**: No memory leaks with repeated creation
+
+#### Performance characteristics
+- [ ] **Creation speed**: Objects created quickly
+- [ ] **Property access**: Properties accessed efficiently
+- [ ] **Label generation**: Label generation reasonably fast
+- [ ] **Validation speed**: Species validation doesn't slow operations
+
+### 15.13 Integration with Plotting Systems
+
+#### Label system integration
+- [ ] **Plot labeling**: Works correctly in plot axis labeling
+- [ ] **Legend integration**: Functions in plot legends
+- [ ] **Colorbar labeling**: Works for colorbar labels if applicable
+- [ ] **Title generation**: Can be used in plot titles
+
+#### Matplotlib compatibility
+- [ ] **Rendering**: Labels render correctly in matplotlib
+- [ ] **Font handling**: Fonts render appropriately
+- [ ] **Mathematical notation**: Mathematical elements display correctly
+- [ ] **Size scaling**: Labels scale appropriately with plot size
+
+### 15.14 Documentation and Examples
+
+#### Documentation quality
+- [ ] **Class docstring**: Clear documentation for ElementalAbundance
+- [ ] **Method documentation**: All methods properly documented
+- [ ] **Parameter documentation**: Parameters clearly described
+- [ ] **Usage examples**: Working code examples provided
+
+#### Scientific documentation
+- [ ] **Abundance concepts**: Documentation explains abundance concepts
+- [ ] **Reference choice**: Guidance on reference species selection
+- [ ] **Normalization**: Photospheric normalization explained
+- [ ] **Use cases**: Common use cases documented
+
+### 15.15 Test Infrastructure
+
+#### Test framework
+- [ ] **Unit tests**: Tests for individual methods and properties
+- [ ] **Integration tests**: Tests with plotting systems
+- [ ] **Validation tests**: Tests for species and parameter validation
+- [ ] **Error condition tests**: Tests for error handling
+
+#### Test data
+- [ ] **Representative abundances**: Test data covers common abundance ratios
+- [ ] **Edge cases**: Unusual species combinations tested
+- [ ] **Invalid cases**: Invalid inputs tested for error handling
+- [ ] **Scientific cases**: Scientifically relevant abundance ratios tested
+
+## 🎯 Testing Strategy
+
+### Unit Testing Approach
+- Test ElementalAbundance initialization with various parameter combinations
+- Verify species validation and error handling
+- Test property access and immutability
+- Validate photospheric normalization logic
+
+### Scientific Validation
+- Verify abundance notation follows scientific standards
+- Test relevance for solar wind composition analysis
+- Validate reference species choices and ratios
+- Test photospheric normalization accuracy
+
+### Integration Testing
+- Test ElementalAbundance labels in plotting contexts
+- Verify integration with matplotlib rendering
+- Test file path generation and usage
+- Validate interaction with other label systems
+
+### Edge Case Coverage
+- Invalid species combinations
+- Self-referencing species
+- Extreme abundance values
+- Boundary conditions in normalization
+
+---
+
+**Estimated Time**: 2 hours  
+**Dependencies**: Base classes, species translation tables  
+**Priority**: MEDIUM (Scientific composition analysis functionality)
+
+**Status**: ✅ COMPLETED
+**Commit**: 5b47880  
+**Tests Added**: 38 comprehensive test cases
+**Time Invested**: 2 hours
+**Test Results**: 38/38 passing (100% success rate)