# main

`main`

Solar Systems Energy Community Analysis Pipeline

A complete pipeline that orchestrates: 1. Data retrieval from databases 2. Geocoding with ArcGIS 3. Energy community analysis 4. Result generation and documentation

Author: Sunnova Energy

## Classes

| Name                                       | Description           |
|--------------------------------------------|-----------------------|
| [ReportFormat](#nova_ec.main.ReportFormat) | Report output formats |
| [StageType](#nova_ec.main.StageType)       | Pipeline stage types  |

### ReportFormat

``` python
main.ReportFormat()
```

Report output formats

### StageType

``` python
main.StageType()
```

Pipeline stage types

## Functions

| Name | Description |
|----|----|
| [analyze_command](#nova_ec.main.analyze_command) | Run only the energy community analysis stage. |
| [callback](#nova_ec.main.callback) | Solar Systems Energy Community Analysis Pipeline. |
| [ensure_input_files_exist](#nova_ec.main.ensure_input_files_exist) | Ensure that input files specified in the configuration exist. |
| [find_most_recent_analysis](#nova_ec.main.find_most_recent_analysis) | Find the most recent analysis file in the output directory. |
| [geocode_command](#nova_ec.main.geocode_command) | Run only the geocoding stage. |
| [init_command](#nova_ec.main.init_command) | Initialize a new configuration file with default values. |
| [load_config](#nova_ec.main.load_config) | Load configuration from a YAML file. |
| [main](#nova_ec.main.main) | Main entry point for the command-line application. |
| [report_command](#nova_ec.main.report_command) | Run only the report generation stage. |
| [retrieve_command](#nova_ec.main.retrieve_command) | Run only the data retrieval stage. |
| [run_data_retrieval](#nova_ec.main.run_data_retrieval) | Run the data retrieval process. |
| [run_ec_analysis](#nova_ec.main.run_ec_analysis) | Run the energy community analysis process. |
| [run_geocoding](#nova_ec.main.run_geocoding) | Run the geocoding process. |
| [run_pipeline](#nova_ec.main.run_pipeline) | Run the complete pipeline or selected stages. |
| [run_report_generation](#nova_ec.main.run_report_generation) | Run the report generation stage of the pipeline. |
| [setup_logger](#nova_ec.main.setup_logger) | Set up the logger for the application. |
| [version_command](#nova_ec.main.version_command) | Display the version information for the package. |

### analyze_command

``` python
main.analyze_command(
    config=typer.Option(..., '--config', '-c', help='Path to configuration YAML file'),
    solar_systems_file=typer.Option(None, '--solar-systems-file', help='Path to solar systems file (optional)'),
    force_refresh=typer.Option(False, '--force-refresh', '-f', help='Force refreshing of cached data'),
    skip_validation=typer.Option(False, '--skip-validation', help='Skip validation of energy community data'),
    debug_paths=typer.Option(False, '--debug-paths', help='Print detailed debug information about file paths'),
)
```

Run only the energy community analysis stage.

### callback

``` python
main.callback()
```

Solar Systems Energy Community Analysis Pipeline.

This tool analyzes solar systems for energy community eligibility under the Inflation Reduction Act.

### ensure_input_files_exist

``` python
main.ensure_input_files_exist(config)
```

Ensure that input files specified in the configuration exist. Creates dummy files if needed to prevent pipeline failures.

Args: config: Configuration dictionary

Returns: bool: True if required input files exist or were created

### find_most_recent_analysis

``` python
main.find_most_recent_analysis(
    output_dir,
    pattern='energy_community_analysis_*.csv',
)
```

Find the most recent analysis file in the output directory.

Args: output_dir: Directory to search pattern: Glob pattern to match

Returns: Path to the most recent file

### geocode_command

``` python
main.geocode_command(
    config=typer.Option(..., '--config', '-c', help='Path to configuration YAML file'),
)
```

Run only the geocoding stage.

### init_command

``` python
main.init_command(
    output_dir=typer.Option('.', '--output-dir', help='Directory to create the configuration file in'),
    template=typer.Option('default', '--template', help='Configuration template to use (default or full)'),
)
```

Initialize a new configuration file with default values.

### load_config

``` python
main.load_config(config_path)
```

Load configuration from a YAML file.

Args: config_path: Path to configuration YAML file

Returns: dict: Loaded configuration

### main

``` python
main.main()
```

Main entry point for the command-line application.

### report_command

``` python
main.report_command(
    config=typer.Option(..., '--config', '-c', help='Path to configuration YAML file'),
    analysis_file=typer.Option(None, '--analysis-file', help='Path to analysis file (optional, uses most recent if not specified)'),
    previous_report=typer.Option(None, '--previous-report', help='Path to a specific previous report file for comparison'),
    lookback_weeks=typer.Option(4, '--lookback-weeks', help='Number of weeks to include in trend analysis'),
    report_format=typer.Option(ReportFormat.HTML, '--report-format', help='Output format for the report'),
    auto_render_report=typer.Option(False, '--auto-render-report', help='Automatically render the Quarto report to HTML'),
    report_template=typer.Option('nova_ec/utils/quarto_template_final.qmd', '--report-template', help='Path to a custom report template file'),
    use_typst=typer.Option(False, '--use-typst', help='Use Typst instead of Quarto for report generation'),
)
```

Run only the report generation stage.

### retrieve_command

``` python
main.retrieve_command(
    config=typer.Option(..., '--config', '-c', help='Path to configuration YAML file'),
    project_root=typer.Option(None, '--project-root', help='Path to project root directory'),
    force_refresh=typer.Option(False, '--force-refresh', '-f', help='Force refreshing of cached data'),
)
```

Run only the data retrieval stage.

### run_data_retrieval

``` python
main.run_data_retrieval(project_root=None, force_refresh=False)
```

Run the data retrieval process.

Args: project_root: Path to the project root directory force_refresh: Force refresh cached data

Returns: bool: True if successful, False otherwise

### run_ec_analysis

``` python
main.run_ec_analysis(
    config,
    solar_systems_file=None,
    force_refresh=False,
    skip_validation=False,
    debug_paths=False,
)
```

Run the energy community analysis process.

Args: config: Loaded configuration dictionary solar_systems_file: Path to solar systems file (optional) force_refresh: Force refreshing of cached data skip_validation: Skip validation of energy community data debug_paths: Print detailed debug information about file paths

Returns: Tuple containing: - bool: True if successful, False otherwise - Optional\[Path\]: Path to the output file if successful, None otherwise

### run_geocoding

``` python
main.run_geocoding(config)
```

Run the geocoding process.

Args: config: Loaded configuration dictionary

Returns: bool: True if successful, False otherwise

### run_pipeline

``` python
main.run_pipeline(
    config=typer.Option(..., '--config', '-c', help='Path to configuration YAML file'),
    stages=typer.Option([StageType.ALL], '--stages', '-s', help='Pipeline stages to run'),
    solar_systems_file=typer.Option(None, '--solar-systems-file', help='Path to solar systems file (only used for analysis stage)'),
    force_refresh=typer.Option(False, '--force-refresh', '-f', help='Force refreshing of cached data'),
    skip_validation=typer.Option(False, '--skip-validation', help='Skip validation of energy community data'),
    debug_paths=typer.Option(False, '--debug-paths', help='Print detailed debug information about file paths'),
    project_root=typer.Option(None, '--project-root', help='Path to project root directory (used for retrieve stage)'),
    generate_report=typer.Option(False, '--generate-report', '-r', help='Generate a comparison report after analysis'),
    previous_report=typer.Option(None, '--previous-report', help='Path to a specific previous report file for comparison'),
    lookback_weeks=typer.Option(4, '--lookback-weeks', help='Number of weeks to include in trend analysis'),
    report_format=typer.Option(ReportFormat.HTML, '--report-format', help='Output format for the report'),
    auto_render_report=typer.Option(False, '--auto-render-report', help='Automatically render the Quarto report to HTML'),
    report_template=typer.Option('nova_ec/utils/quarto_template_final.qmd', '--report-template', help='Path to a custom report template file'),
    use_typst=typer.Option(False, '--use-typst', help='Use Typst instead of Quarto for report generation'),
)
```

Run the complete pipeline or selected stages.

### run_report_generation

``` python
main.run_report_generation(
    config,
    output_file,
    previous_report_path=None,
    lookback_weeks=4,
    report_format='html',
    report_template=None,
    auto_render=False,
    use_typst=False,
)
```

Run the report generation stage of the pipeline.

Args: config: The loaded configuration dictionary output_file: Path to the analysis output file previous_report_path: Path to previous analysis for comparison lookback_weeks: Number of weeks to include in trend analysis report_format: Output format for the report report_template: Path to a custom report template auto_render: Whether to automatically render the report use_typst: Whether to use Typst instead of Quarto

Returns: Tuple of (success, report_path)

### setup_logger

``` python
main.setup_logger(log_path)
```

Set up the logger for the application.

Args: log_path: Path to log file

Returns: Tuple of logger and console instances

### version_command

``` python
main.version_command()
```

Display the version information for the package.