source venv/bin/activate # On Windows use: .\venv\Scripts\activate
```
3. Install the required packages:
```sh
pip install -r requirements.txt
```
4. Start Redis server locally:
```sh
redis-server
```
5. Set up your configuration:
Create a `config.ini` file in the root directory by copying `example_config.ini`:
```sh
cp example_config.ini config.ini
```
Then edit `config.ini` with your settings:
```ini
[DEFAULT]
SECRET_KEY = your_secret_key
API_KEY = your_api_key
# ...rest of the config settings...
```
6. Start the Celery worker:
```sh
celery -A app.celery_worker worker --loglevel=info
```
7. Run the Flask application:
```sh
flask run
```
The application will be available at `http://127.0.0.1:5000/`
## Adding an Analysis Module
This guide explains how to add a new analysis module using the provided base classes: `BasePlotlyAnalysis` and `BasePlotAnalysis`. These base classes ensure a structured workflow for data preparation, transformation, and visualization.
### 1. Choosing the Right Base Class
Before implementing an analysis module, decide on the appropriate base class:
- **`BasePlotlyAnalysis`**: Use this for interactive plots with **Plotly** that generate **HTML** outputs.
- **`BasePlotAnalysis`**: Use this for static plots with **Matplotlib/Seaborn** that generate **PNG** image files.
- **`BaseAnalysis`**: Use this for any other type of analysis with **text** or **HTML** output for max flexibility.
### 2. Naming Convention
Follow a structured naming convention for consistency:
- **File name:** `plotly_<analysis_name>.py` for Plotly analyses, `plot_<analysis_name>.py` for Matplotlib-based analyses.
- **Class name:** Use PascalCase and a descriptive suffix:
- Example for Plotly: `PlotlyActivityHeatmap`
- Example for Matplotlib: `PlotUserSessionDuration`
### 3. Data Structure
The following DataFrame structure is passed to analysis classes:
| user_id | name | last_action | status | timestamp | prev_timestamp | was_active | hour |
Note that the first X rows, depending on the number of the members, will always contain empty values in prev_timestamp as there has to be a previous timestamp ....
### 4. Implementing an Analysis Module
Each analysis module should define two key methods:
-`transform_data(self, df: pd.DataFrame) -> pd.DataFrame`: Processes the input data for plotting.
-`plot_data(self, df: pd.DataFrame)`: Generates and saves the plot.
#### Example: Adding a Plotly Heatmap
Below is an example of how to create a new analysis module using `BasePlotlyAnalysis`.
```python
import pandas as pd
import plotly.graph_objects as go
from .basePlotlyAnalysis import BasePlotlyAnalysis
class PlotlyActivityHeatmap(BasePlotlyAnalysis):
"""
Displays user activity trends over multiple days using an interactive heatmap.
"""
name = "Activity Heatmap (Interactive)"
description = "Displays user activity trends over multiple days."
All assets and code are under the [CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/) LICENSE and in the public domain unless specified otherwise.
