# Aquifer Intelligence Quickstart

This quickstart distills the workflow patterns we extracted from ElePath Sabah
into the aquifer context.  Use it as a checklist when onboarding new analysts.

## 1. Environment Setup

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Optional extras:

- `pip install -e .` for editable package development.
- `pip install -e .[dev]` after `pip install -e .` for formatting and tests.

## 2. Configure Data Paths

The `src.utils.config_loader` helper reads `config/data_config.yaml`.  Update
that file to point at your local HTEM data directories, then run:

```python
from src.utils import config_loader

config_loader.refresh_config()
paths = config_loader.get_core_data_directories()
print(paths["raw"])
print(paths["processed"])
```

## 3. Process / Organize Data

Use `PartitionedParquetStorage` when you need to persist derived datasets with
fast subsetting:

```python
import pandas as pd
from src.utils.partition_storage import PartitionedParquetStorage

df = pd.read_csv("data/htem_data/Unit_A_Preferred_MT.csv")
storage = PartitionedParquetStorage(partition_cols=["Unit", "Month"])
storage.write(df)

monthly = storage.read_partition(Unit="A", Month="2024-01")
```

## 4. Render the Book

```bash
cd aquifer-book
quarto render
```

Run `quarto preview` to iterate on notebooks and pages interactively.  When
changes look good, push to `main` and let the GitHub Actions workflow publish.

## 5. Validate

```bash
pytest
```

The test suite includes configuration and storage round-trips modelled on the
ElePath checks so regressions are caught quickly.