fvs-python 0.2.3__py3-none-any.whl

pyfvs/data_export.py

@@ -0,0 +1,356 @@
+"""
+Data export utilities for FVS-Python.
+Provides various formats for exporting simulation results.
+"""
+import json
+from pathlib import Path
+from typing import List, Dict, Any, Optional, Union
+import pandas as pd
+import numpy as np
+from datetime import datetime
+
+from .logging_config import get_logger
+
+
+class DataExporter:
+    """Handles export of simulation data to various formats."""
+    
+    def __init__(self, output_dir: Path):
+        """Initialize the data exporter.
+        
+        Args:
+            output_dir: Directory for output files
+        """
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(exist_ok=True, parents=True)
+        self.logger = get_logger(__name__)
+    
+    def export_to_csv(self, 
+                     data: Union[pd.DataFrame, List[Dict]], 
+                     filename: str,
+                     include_metadata: bool = True) -> Path:
+        """Export data to CSV format.
+        
+        Args:
+            data: Data to export (DataFrame or list of dicts)
+            filename: Output filename
+            include_metadata: Whether to include metadata header
+            
+        Returns:
+            Path to exported file
+        """
+        filepath = self.output_dir / f"{filename}.csv"
+        
+        if isinstance(data, list):
+            df = pd.DataFrame(data)
+        else:
+            df = data.copy()
+        
+        with open(filepath, 'w', newline='') as f:
+            if include_metadata:
+                # Write metadata header
+                f.write(f"# FVS-Python Export\n")
+                f.write(f"# Generated: {datetime.now().isoformat()}\n")
+                f.write(f"# Records: {len(df)}\n")
+                f.write(f"# Columns: {', '.join(df.columns)}\n")
+                f.write("#\n")
+            
+            # Write data
+            df.to_csv(f, index=False)
+        
+        self.logger.info(f"Exported {len(df)} records to {filepath}")
+        return filepath
+    
+    def export_to_json(self, 
+                      data: Union[pd.DataFrame, List[Dict], Dict], 
+                      filename: str,
+                      include_metadata: bool = True,
+                      format_style: str = 'records') -> Path:
+        """Export data to JSON format.
+        
+        Args:
+            data: Data to export
+            filename: Output filename
+            include_metadata: Whether to include metadata
+            format_style: JSON format ('records', 'values', 'index', 'split')
+            
+        Returns:
+            Path to exported file
+        """
+        filepath = self.output_dir / f"{filename}.json"
+        
+        # Prepare data
+        if isinstance(data, pd.DataFrame):
+            if format_style == 'records':
+                export_data = data.to_dict('records')
+            elif format_style == 'values':
+                export_data = data.values.tolist()
+            elif format_style == 'index':
+                export_data = data.to_dict('index')
+            elif format_style == 'split':
+                export_data = data.to_dict('split')
+            else:
+                export_data = data.to_dict('records')
+        elif isinstance(data, list):
+            export_data = data
+        else:
+            export_data = data
+        
+        # Create output structure
+        output = {}
+        if include_metadata:
+            output['metadata'] = {
+                'generator': 'FVS-Python',
+                'generated_at': datetime.now().isoformat(),
+                'format': format_style,
+                'record_count': len(export_data) if isinstance(export_data, list) else 1
+            }
+        
+        output['data'] = export_data
+        
+        with open(filepath, 'w') as f:
+            json.dump(output, f, indent=2, default=self._json_serializer)
+        
+        self.logger.info(f"Exported data to {filepath}")
+        return filepath
+
+    def export_to_excel(self,
+                       data: Union[pd.DataFrame, Dict[str, pd.DataFrame]],
+                       filename: str) -> Path:
+        """Export data to Excel format.
+
+        Args:
+            data: Data to export (single DataFrame or dict of DataFrames for multiple sheets)
+            filename: Output filename
+
+        Returns:
+            Path to exported file
+        """
+        filepath = self.output_dir / f"{filename}.xlsx"
+
+        try:
+            with pd.ExcelWriter(filepath, engine='openpyxl') as writer:
+                if isinstance(data, pd.DataFrame):
+                    data.to_excel(writer, sheet_name='Data', index=False)
+                else:
+                    for sheet_name, df in data.items():
+                        df.to_excel(writer, sheet_name=sheet_name, index=False)
+
+            self.logger.info(f"Exported data to Excel file {filepath}")
+            return filepath
+
+        except ImportError:
+            self.logger.warning("openpyxl not available, falling back to CSV export")
+            if isinstance(data, pd.DataFrame):
+                return self.export_to_csv(data, filename)
+            else:
+                first_sheet = next(iter(data.values()))
+                return self.export_to_csv(first_sheet, filename)
+    
+    def export_yield_table(self,
+                          yield_table: pd.DataFrame,
+                          format: str = 'csv',
+                          filename: Optional[str] = None) -> Path:
+        """Export yield table with proper formatting.
+
+        Args:
+            yield_table: Yield table DataFrame
+            format: Export format ('csv', 'json', 'excel')
+            filename: Custom filename (optional)
+
+        Returns:
+            Path to exported file
+        """
+        if filename is None:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            filename = f"yield_table_{timestamp}"
+
+        # Round numeric columns for better presentation
+        display_table = yield_table.copy()
+        numeric_columns = ['mean_dbh', 'mean_height', 'basal_area', 'volume']
+        for col in numeric_columns:
+            if col in display_table.columns:
+                display_table[col] = display_table[col].round(2)
+
+        # Sort by logical order
+        if all(col in display_table.columns for col in ['species', 'site_index', 'initial_tpa', 'age']):
+            display_table = display_table.sort_values(['species', 'site_index', 'initial_tpa', 'age'])
+
+        if format.lower() == 'csv':
+            # No metadata for CSV to allow easy reading back
+            return self.export_to_csv(display_table, filename, include_metadata=False)
+        elif format.lower() == 'json':
+            return self.export_to_json(display_table, filename)
+        elif format.lower() == 'excel':
+            return self.export_to_excel(display_table, filename)
+        else:
+            raise ValueError(f"Unsupported format: {format}")
+
+    def export_scenario_comparison(self,
+                                 comparison_df: pd.DataFrame,
+                                 format: str = 'csv',
+                                 filename: Optional[str] = None) -> Path:
+        """Export scenario comparison results.
+
+        Args:
+            comparison_df: Scenario comparison DataFrame
+            format: Export format
+            filename: Custom filename (optional)
+
+        Returns:
+            Path to exported file
+        """
+        if filename is None:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            filename = f"scenario_comparison_{timestamp}"
+
+        # Create summary statistics
+        if format.lower() == 'excel':
+            # Create multiple sheets for Excel
+            sheets = {
+                'Raw_Data': comparison_df,
+                'Summary': self._create_scenario_summary(comparison_df)
+            }
+            return self.export_to_excel(sheets, filename)
+        elif format.lower() == 'csv':
+            # No metadata for CSV to allow easy reading back
+            return self.export_to_csv(comparison_df, filename, include_metadata=False)
+        else:
+            return getattr(self, f'export_to_{format.lower()}')(comparison_df, filename)
+
+    def export_stand_metrics(self,
+                           metrics_over_time: List[Dict],
+                           format: str = 'csv',
+                           filename: Optional[str] = None) -> Path:
+        """Export stand metrics over time.
+
+        Args:
+            metrics_over_time: List of metric dictionaries
+            format: Export format ('csv', 'json', 'excel')
+            filename: Custom filename (optional)
+
+        Returns:
+            Path to exported file
+        """
+        if filename is None:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            filename = f"stand_metrics_{timestamp}"
+
+        df = pd.DataFrame(metrics_over_time)
+
+        # Round numeric columns
+        numeric_columns = df.select_dtypes(include=[np.number]).columns
+        df[numeric_columns] = df[numeric_columns].round(2)
+
+        if format.lower() == 'csv':
+            # No metadata for CSV to allow easy reading back
+            return self.export_to_csv(df, filename, include_metadata=False)
+        elif format.lower() == 'json':
+            return self.export_to_json(df, filename)
+        elif format.lower() == 'excel':
+            return self.export_to_excel(df, filename)
+        else:
+            raise ValueError(f"Unsupported format: {format}")
+
+    def create_summary_report(self,
+                            simulation_results: Dict[str, Any],
+                            filename: Optional[str] = None) -> Path:
+        """Create a comprehensive summary report.
+
+        Args:
+            simulation_results: Dictionary containing all simulation results
+            filename: Custom filename (optional)
+
+        Returns:
+            Path to summary report file
+        """
+        if filename is None:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            filename = f"simulation_summary_{timestamp}"
+
+        filepath = self.output_dir / f"{filename}.txt"
+
+        with open(filepath, 'w') as f:
+            f.write("FVS-Python Simulation Summary Report\n")
+            f.write("=" * 50 + "\n\n")
+
+            f.write(f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
+            f.write("Software: FVS-Python v1.0.0\n\n")
+
+            # Simulation parameters
+            if 'parameters' in simulation_results:
+                params = simulation_results['parameters']
+                f.write("Simulation Parameters:\n")
+                f.write("-" * 25 + "\n")
+                for key, value in params.items():
+                    f.write(f"{key}: {value}\n")
+                f.write("\n")
+
+            # Final metrics
+            if 'final_metrics' in simulation_results:
+                metrics = simulation_results['final_metrics']
+                f.write("Final Stand Metrics:\n")
+                f.write("-" * 25 + "\n")
+                f.write(f"Age: {metrics.get('age', 'N/A')} years\n")
+                f.write(f"Trees per Acre: {metrics.get('tpa', 'N/A'):.0f}\n")
+                f.write(f"Mean DBH: {metrics.get('mean_dbh', 'N/A'):.1f} inches\n")
+                f.write(f"Mean Height: {metrics.get('mean_height', 'N/A'):.1f} feet\n")
+                f.write(f"Basal Area: {metrics.get('basal_area', 'N/A'):.1f} sq ft/acre\n")
+                f.write(f"Volume: {metrics.get('volume', 'N/A'):.0f} cubic feet/acre\n")
+                f.write("\n")
+
+            # Growth summary
+            if 'growth_summary' in simulation_results:
+                f.write("Growth Summary:\n")
+                f.write("-" * 25 + "\n")
+                summary = simulation_results['growth_summary']
+                f.write(f"Total DBH Growth: {summary.get('total_dbh_growth', 'N/A'):.1f} inches\n")
+                f.write(f"Total Height Growth: {summary.get('total_height_growth', 'N/A'):.1f} feet\n")
+                f.write(f"Total Volume Growth: {summary.get('total_volume_growth', 'N/A'):.0f} cu ft/acre\n")
+                f.write(f"Survival Rate: {summary.get('survival_rate', 'N/A'):.1%}\n")
+                f.write("\n")
+
+            # File references
+            f.write("Associated Files:\n")
+            f.write("-" * 25 + "\n")
+            if 'output_files' in simulation_results:
+                for file_type, filepath_ref in simulation_results['output_files'].items():
+                    f.write(f"{file_type}: {filepath_ref}\n")
+
+        self.logger.info(f"Created summary report: {filepath}")
+        return filepath
+
+    def _json_serializer(self, obj):
+        """JSON serializer for numpy types."""
+        if isinstance(obj, np.integer):
+            return int(obj)
+        elif isinstance(obj, np.floating):
+            return float(obj)
+        elif isinstance(obj, np.ndarray):
+            return obj.tolist()
+        elif isinstance(obj, pd.Timestamp):
+            return obj.isoformat()
+        return str(obj)
+
+    def _create_scenario_summary(self, comparison_df: pd.DataFrame) -> pd.DataFrame:
+        """Create summary statistics for scenario comparison."""
+        if 'scenario' not in comparison_df.columns:
+            return pd.DataFrame()
+
+        # Get final metrics for each scenario
+        final_metrics = []
+        for scenario in comparison_df['scenario'].unique():
+            scenario_data = comparison_df[comparison_df['scenario'] == scenario]
+            final_row = scenario_data[scenario_data['age'] == scenario_data['age'].max()].iloc[0]
+
+            summary = {
+                'scenario': scenario,
+                'final_age': final_row['age'],
+                'final_tpa': final_row.get('tpa', 0),
+                'final_volume': final_row.get('volume', 0),
+                'final_mean_dbh': final_row.get('mean_dbh', 0),
+                'final_mean_height': final_row.get('mean_height', 0)
+            }
+            final_metrics.append(summary)
+
+        return pd.DataFrame(final_metrics)

pyfvs/ecological_unit.py

@@ -0,0 +1,272 @@
+"""
+Ecological unit classification system for FVS-Python.
+
+Implements the FVS Southern variant ecological unit (ECOUNIT) classification system
+for modifying growth predictions based on ecological subsection codes.
+
+The system uses two coefficient tables:
+- Table 4.7.1.5: For mountain/province-level ecounits (M221, M222, M231, 221, 222, 231T)
+- Table 4.7.1.6: For lowland ecounits (231L, 232, 234, 255, 411)
+"""
+import json
+from pathlib import Path
+from typing import Dict, Any, Optional, Set
+from .config_loader import get_config_loader
+from .exceptions import ConfigurationError
+
+
+# Define the ecological unit groups for each table
+MOUNTAIN_PROVINCE_ECOUNITS: Set[str] = {"M221", "M222", "M231", "221", "222", "231T"}
+LOWLAND_ECOUNITS: Set[str] = {"231L", "232", "234", "255", "411"}
+
+
+def select_ecounit_table(ecounit_group: str) -> str:
+    """Determine which coefficient table to use based on ecological unit group.
+
+    Table 4.7.1.5 is used for mountain/province-level ecounits:
+        M221, M222, M231, 221, 222, 231T
+
+    Table 4.7.1.6 is used for lowland ecounits:
+        231L, 232, 234, 255, 411
+
+    Args:
+        ecounit_group: Ecological unit group code (e.g., "M221", "232", "231L")
+
+    Returns:
+        Table identifier string: "table_4_7_1_5" or "table_4_7_1_6"
+    """
+    normalized_group = ecounit_group.upper().strip()
+
+    if normalized_group in MOUNTAIN_PROVINCE_ECOUNITS:
+        return "table_4_7_1_5"
+    elif normalized_group in LOWLAND_ECOUNITS:
+        return "table_4_7_1_6"
+    else:
+        # Unknown ecounit - default to table 4.7.1.5 as it has broader coverage
+        return "table_4_7_1_5"
+
+
+class EcologicalUnitClassifier:
+    """Classifier for mapping ecological subsection codes to ECOUNIT groups.
+
+    This class implements the FVS Southern variant ecological unit classification
+    system, handling both Table 4.7.1.5 (mountain/province-level regions) and
+    Table 4.7.1.6 (lowland regions).
+    """
+
+    # Class-level cache for coefficient tables
+    _coefficients_table_5: Optional[Dict[str, Any]] = None
+    _coefficients_table_6: Optional[Dict[str, Any]] = None
+    _tables_loaded: bool = False
+
+    def __init__(self):
+        """Initialize the ecological unit classifier."""
+        if not EcologicalUnitClassifier._tables_loaded:
+            self._load_coefficient_tables()
+
+    def _load_coefficient_tables(self) -> None:
+        """Load coefficient tables from JSON files in the cfg directory."""
+        try:
+            loader = get_config_loader()
+            cfg_dir = loader.cfg_dir
+
+            # Load Table 4.7.1.5 (mountain/province ecounits)
+            table_5_path = cfg_dir / "ecounit_coefficients_table_4_7_1_5.json"
+            if table_5_path.exists():
+                with open(table_5_path, 'r', encoding='utf-8') as f:
+                    EcologicalUnitClassifier._coefficients_table_5 = json.load(f)
+            else:
+                EcologicalUnitClassifier._coefficients_table_5 = self._get_empty_table()
+
+            # Load Table 4.7.1.6 (lowland ecounits)
+            table_6_path = cfg_dir / "ecounit_coefficients_table_4_7_1_6.json"
+            if table_6_path.exists():
+                with open(table_6_path, 'r', encoding='utf-8') as f:
+                    EcologicalUnitClassifier._coefficients_table_6 = json.load(f)
+            else:
+                EcologicalUnitClassifier._coefficients_table_6 = self._get_empty_table()
+
+            EcologicalUnitClassifier._tables_loaded = True
+
+        except json.JSONDecodeError as e:
+            raise ConfigurationError(
+                f"Failed to parse ecological unit coefficient files: {str(e)}"
+            ) from e
+        except Exception as e:
+            if isinstance(e, ConfigurationError):
+                raise
+            # Set empty tables to avoid repeated failures
+            EcologicalUnitClassifier._coefficients_table_5 = self._get_empty_table()
+            EcologicalUnitClassifier._coefficients_table_6 = self._get_empty_table()
+            EcologicalUnitClassifier._tables_loaded = True
+
+    @staticmethod
+    def _get_empty_table() -> Dict[str, Any]:
+        """Return an empty coefficient table structure."""
+        return {
+            "table_description": "Empty fallback table",
+            "ecological_unit_groups": {},
+            "species_coefficients": {}
+        }
+
+    def get_coefficient(self, species_code: str, ecounit_group: str) -> float:
+        """Get the ecological unit coefficient for a species and ecounit group.
+
+        Args:
+            species_code: FVS species code (e.g., "LP", "SP", "WO")
+            ecounit_group: Ecological unit group code (e.g., "M221", "232")
+
+        Returns:
+            The coefficient value to add to the growth equation.
+            Returns 0.0 if the species or ecounit is not found.
+        """
+        normalized_species = species_code.upper().strip()
+        normalized_ecounit = ecounit_group.upper().strip()
+
+        # Select the appropriate table
+        table_name = select_ecounit_table(normalized_ecounit)
+
+        if table_name == "table_4_7_1_5":
+            coefficients = self._coefficients_table_5
+        else:
+            coefficients = self._coefficients_table_6
+
+        if coefficients is None:
+            return 0.0
+
+        # Look up species coefficients
+        species_data = coefficients.get("species_coefficients", {}).get(normalized_species)
+        if species_data is None:
+            return 0.0
+
+        # Look up ecounit coefficient
+        ecounit_coefficients = species_data.get("coefficients", {})
+        return ecounit_coefficients.get(normalized_ecounit, 0.0)
+
+    def get_base_ecounit(self, species_code: str, table: str = "table_4_7_1_5") -> Optional[str]:
+        """Get the base ecological unit for a species."""
+        normalized_species = species_code.upper().strip()
+
+        if table == "table_4_7_1_5":
+            coefficients = self._coefficients_table_5
+        else:
+            coefficients = self._coefficients_table_6
+
+        if coefficients is None:
+            return None
+
+        species_data = coefficients.get("species_coefficients", {}).get(normalized_species)
+        if species_data is None:
+            return None
+
+        return species_data.get("base_ecounit")
+
+    def get_available_species(self, table: str = "table_4_7_1_5") -> list:
+        """Get list of species codes available in a coefficient table."""
+        if table == "table_4_7_1_5":
+            coefficients = self._coefficients_table_5
+        else:
+            coefficients = self._coefficients_table_6
+
+        if coefficients is None:
+            return []
+
+        return list(coefficients.get("species_coefficients", {}).keys())
+
+    def get_all_coefficients_for_species(self, species_code: str) -> Dict[str, float]:
+        """Get all ecological unit coefficients for a species across both tables."""
+        normalized_species = species_code.upper().strip()
+        all_coefficients = {}
+
+        # Get coefficients from Table 4.7.1.5
+        if self._coefficients_table_5:
+            species_data = self._coefficients_table_5.get(
+                "species_coefficients", {}
+            ).get(normalized_species, {})
+            all_coefficients.update(species_data.get("coefficients", {}))
+
+        # Get coefficients from Table 4.7.1.6
+        if self._coefficients_table_6:
+            species_data = self._coefficients_table_6.get(
+                "species_coefficients", {}
+            ).get(normalized_species, {})
+            all_coefficients.update(species_data.get("coefficients", {}))
+
+        return all_coefficients
+
+    def is_lowland_ecounit(self, ecounit_group: str) -> bool:
+        """Check if an ecological unit group is classified as lowland."""
+        normalized_ecounit = ecounit_group.upper().strip()
+        return normalized_ecounit in LOWLAND_ECOUNITS
+
+    def is_mountain_province_ecounit(self, ecounit_group: str) -> bool:
+        """Check if an ecological unit group is classified as mountain/province."""
+        normalized_ecounit = ecounit_group.upper().strip()
+        return normalized_ecounit in MOUNTAIN_PROVINCE_ECOUNITS
+
+    @classmethod
+    def reset_cache(cls) -> None:
+        """Reset the cached coefficient tables."""
+        cls._coefficients_table_5 = None
+        cls._coefficients_table_6 = None
+        cls._tables_loaded = False
+
+
+def get_ecounit_effect(species_code: str, ecounit_group: str) -> float:
+    """Get the ecological unit coefficient for a given species and ecounit group.
+
+    Loads the appropriate coefficient table based on whether the ecounit is
+    in a lowland or upland/mountain region, then returns the coefficient
+    that should be added to the base growth equation.
+
+    Args:
+        species_code: FVS species code (e.g., "LP", "SP", "WO")
+        ecounit_group: Ecological unit group code (e.g., "M221", "232")
+
+    Returns:
+        The ecological unit coefficient (effect) for the species/ecounit combination.
+        Returns 0.0 if the species or ecounit is not found in the table.
+    """
+    classifier = EcologicalUnitClassifier()
+    return classifier.get_coefficient(species_code, ecounit_group)
+
+
+def create_classifier() -> EcologicalUnitClassifier:
+    """Factory function to create an ecological unit classifier."""
+    return EcologicalUnitClassifier()
+
+
+def get_ecounit_summary(species_code: str) -> Dict[str, Any]:
+    """Get a summary of ecological unit effects for a species."""
+    classifier = EcologicalUnitClassifier()
+    normalized_species = species_code.upper().strip()
+
+    # Get effects from both tables
+    mountain_effects = {}
+    lowland_effects = {}
+
+    for ecounit in MOUNTAIN_PROVINCE_ECOUNITS:
+        coeff = classifier.get_coefficient(normalized_species, ecounit)
+        if coeff != 0.0 or ecounit == classifier.get_base_ecounit(
+            normalized_species, "table_4_7_1_5"
+        ):
+            mountain_effects[ecounit] = coeff
+
+    for ecounit in LOWLAND_ECOUNITS:
+        coeff = classifier.get_coefficient(normalized_species, ecounit)
+        if coeff != 0.0 or ecounit == classifier.get_base_ecounit(
+            normalized_species, "table_4_7_1_6"
+        ):
+            lowland_effects[ecounit] = coeff
+
+    return {
+        "species": normalized_species,
+        "mountain_province_effects": mountain_effects,
+        "lowland_effects": lowland_effects,
+        "base_ecounit_table_5": classifier.get_base_ecounit(
+            normalized_species, "table_4_7_1_5"
+        ),
+        "base_ecounit_table_6": classifier.get_base_ecounit(
+            normalized_species, "table_4_7_1_6"
+        )
+    }