cal_heatmap: Yearly Calendar Heatmaps

This project generates interactive yearly activity heatmaps using calendar data from a specified URL. It utilizes Streamlit for the web interface, Plotly for creating heatmaps, and other supporting libraries for data handling and visualization.

Features

• Load calendar data from a given URL.
• Save and load different configurations for calendar URL and number of years to display.
• Generate interactive yearly heatmaps of events.
• Customize the number of years to visualize.

Prerequisites

• Python 3.9+
• Required Python packages (listed in requirements.txt)

Installation

1. Clone the repository:

git clone https://github.com/yourusername/yearly-activity-heatmaps.git
cd yearly-activity-heatmaps

2. Install the required packages:

pip install -r requirements.txt

3. Run the Streamlit app:

streamlit run app.py

Usage

1. Configure Settings:

   • Enter the calendar export link.
   • Set the number of years to visualize.
   • Save your configuration.

2. Generate Heatmaps:

   • The app will download the calendar data.
   • It will parse the data and count events for each day.
   • Interactive heatmaps will be generated for the specified years.

File Structure

• app.py: Main script for running the Streamlit app.
• settings.json: JSON file to store user configurations.
• requirements.txt: List of required Python packages.

Project Dependencies

Make sure you have the following Python libraries installed:

• pandas
• vobject
• requests
• datetime
• matplotlib
• calmap
• streamlit
• plotly

You can install all dependencies using the following command:

pip install -r requirements.txt

Docker Deployment

1. Build Docker Image:

docker build -t yearly-activity-heatmaps .

2. Run Docker Container:

docker run -p 8501:8501 yearly-activity-heatmaps

This will build and run your Streamlit app inside a Docker container, exposing it on port 8501.

Example Code

Below is a snippet of the core functionality in app.py:

import pandas as pd 
import vobject
import requests
from datetime import datetime, date
import matplotlib.pyplot as plt
import calmap
import streamlit as st 
import plotly.express as px
import plotly.graph_objects as go
import json
import os

# Functions to load and save data, create heatmaps, and update session state...

# Set webpage title
st.title("Yearly Activity Heatmaps")

# Main logic for loading configurations, downloading calendar data, and generating heatmaps...

# Plot each year's data
for year in years_to_plot:
    fig = create_calendar_heatmap(event_series, year)
    st.plotly_chart(fig)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Streamlit for providing a fantastic framework for building web apps.
• Plotly for interactive data visualization capabilities.
• All contributors and users for their support.