136 lines
3.0 KiB
Markdown
136 lines
3.0 KiB
Markdown
# Home Assistant Data Analysis
|
|
|
|
Data analysis notebooks for investigating power consumption and other smart home metrics collected by Home Assistant.
|
|
|
|
## Project Structure
|
|
|
|
```bash
|
|
.
|
|
├── .gitea/
|
|
│ └── workflows/
|
|
│ └── setup_database.yml # CI workflow to setup PostgreSQL database
|
|
├── notebooks/
|
|
│ └── boiler_warning.ipynb # Power consumption analysis notebook
|
|
├── utils/
|
|
│ ├── __init__.py
|
|
│ └── db_connection.py # Shared database connection utilities
|
|
├── .env.example # Example environment variables
|
|
├── .gitignore
|
|
├── pyproject.toml # Project dependencies and configuration
|
|
└── README.md
|
|
```
|
|
|
|
## Setup
|
|
|
|
### 1. Install UV (Python Package Manager)
|
|
|
|
```bash
|
|
# macOS/Linux
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
|
|
# Or via Homebrew
|
|
brew install uv
|
|
```
|
|
|
|
### 2. Create Virtual Environment and Install Dependencies
|
|
|
|
```bash
|
|
# Create and activate virtual environment with UV
|
|
uv venv
|
|
source .venv/bin/activate # On macOS/Linux
|
|
|
|
# Install dependencies
|
|
uv pip install -e .
|
|
```
|
|
|
|
### 3. Configure Database Connection
|
|
|
|
```bash
|
|
# Copy example environment file
|
|
cp .env.example .env
|
|
|
|
# Edit .env with your PostgreSQL credentials
|
|
nano .env # or use your preferred editor
|
|
```
|
|
|
|
### 4. Run Jupyter Notebooks
|
|
|
|
```bash
|
|
# Start Jupyter Lab
|
|
jupyter lab
|
|
|
|
# Or Jupyter Notebook
|
|
jupyter notebook
|
|
```
|
|
|
|
## Database Setup
|
|
|
|
The repository includes a CI workflow (`.gitea/workflows/setup_database.yml`) that can be manually triggered to initialize the PostgreSQL database. Ensure the following secrets are configured in your Gitea repository:
|
|
|
|
- `POSTGRES_HOST`
|
|
- `POSTGRES_PORT`
|
|
- `POSTGRES_ROOT_PASSWORD`
|
|
- `DB_NAME`
|
|
- `DB_USER`
|
|
- `DB_PASSWORD`
|
|
|
|
## Notebooks
|
|
|
|
### Current Notebooks
|
|
|
|
- **boiler_warning.ipynb**: Analysis of power consumption data from Home Assistant
|
|
|
|
### Adding New Notebooks
|
|
|
|
1. Create new notebook in the `notebooks/` directory
|
|
2. Use descriptive names (e.g., `temperature_trends.ipynb`, `energy_efficiency.ipynb`)
|
|
3. Import shared utilities: `from utils import get_db_connection, get_db_engine`
|
|
|
|
## Shared Utilities
|
|
|
|
The `utils/` module provides common functions for database connections:
|
|
|
|
```python
|
|
from utils import get_db_connection, get_db_engine
|
|
|
|
# Using psycopg2 (for raw SQL)
|
|
conn = get_db_connection()
|
|
cursor = conn.cursor()
|
|
cursor.execute("SELECT * FROM states LIMIT 10")
|
|
|
|
# Using SQLAlchemy (for pandas integration)
|
|
engine = get_db_engine()
|
|
import pandas as pd
|
|
df = pd.read_sql("SELECT * FROM states LIMIT 10", engine)
|
|
```
|
|
|
|
## Development
|
|
|
|
### Optional Development Tools
|
|
|
|
Install development dependencies for code formatting and linting:
|
|
|
|
```bash
|
|
uv pip install -e ".[dev]"
|
|
```
|
|
|
|
Format code with Black:
|
|
|
|
```bash
|
|
black utils/
|
|
```
|
|
|
|
Lint code with Ruff:
|
|
|
|
```bash
|
|
ruff check utils/
|
|
```
|
|
|
|
## Contributing
|
|
|
|
When adding new analysis notebooks:
|
|
|
|
1. Document the purpose and findings in the notebook
|
|
2. Add any new dependencies to `pyproject.toml`
|
|
3. Update this README if adding significant new functionality
|