# Tutorial


This section shows how to use the nova_ec package.

## Basic Pipeline

The simplest way to use nova_ec is to run the full pipeline:

``` bash
nova-ec --config config.yaml --stages all
```

## Custom Solar Systems Data

If you have a custom solar systems dataset, you can specify it directly:

``` bash
nova-ec --config config.yaml --stages analyze --solar-systems-file path/to/your/data.csv
```

## Running Individual Stages

You can run individual stages of the pipeline:

``` bash
# Just run data retrieval
nova-ec --config config.yaml --stages retrieve

# Just run geocoding
nova-ec --config config.yaml --stages geocode

# Just run energy community analysis
nova-ec --config config.yaml --stages analyze
```

## Using the Python API

You can also use the nova_ec package as a Python library:

``` python
from nova_ec.config import load_config
from nova_ec.data import process_solar_systems
from nova_ec.matching import integrated_matching

# Load configuration
config = load_config("config.yaml")

# Process solar systems data
solar_systems_df = process_solar_systems("path/to/systems.csv", date_cols, systems_cols)

# Perform matching
results = integrated_matching(
    solar_systems_df, 
    ccec_2023=ccec_data_2023,
    ccec_2024=ccec_data_2024,
    ffsaec_2023=ffsaec_data_2023,
    ffsaec_2024=ffsaec_data_2024
)

# Export results
from nova_ec.matching import export_results
export_results(results, "path/to/output.csv")
```

## Advanced Configuration

You can use variable substitution in your configuration:

``` yaml
# User information
username: john.doe

# Base paths
base_paths:
  project_directory: "C:/Users/{username}/Projects"
  
# Paths using variable substitution
paths:
  project_path: "{project_directory}/energy_communities"
  output_dir: "{project_directory}/energy_communities/output"
  ec_path: "Z:/Shared/Risk/Projects/ITC Adders/main"
```