Spaces:
Runtime error
Runtime error
Download app.py from Valuebell/Report-Generator: direct link, hf CLI and curl.
- Browser
- Download file 38.5 kB
-
https://huggingface.co/spaces/Valuebell/Report-Generator/resolve/main/app.py
- Command line
-
hf download hf://spaces/Valuebell/Report-Generator/app.py
-
curl -L -o app.py https://huggingface.co/spaces/Valuebell/Report-Generator/resolve/main/app.py
38.5 kB
| import pandas as pd | |
| import numpy as np | |
| import matplotlib.pyplot as plt | |
| import seaborn as sns | |
| from datetime import datetime, timedelta | |
| from sklearn.linear_model import LinearRegression | |
| import warnings | |
| import re | |
| import io | |
| import time | |
| from difflib import SequenceMatcher | |
| import gradio as gr | |
| import os | |
| import tempfile | |
| import json | |
| # Suppress warnings for a cleaner output | |
| warnings.filterwarnings('ignore') | |
| # Attempt to import Google Generative AI | |
| try: | |
| import google.generativeai as genai | |
| IS_GENAI_AVAILABLE = True | |
| except ImportError: | |
| IS_GENAI_AVAILABLE = False | |
| print("Warning: google-generativeai library not found. Title translation will be disabled.") | |
| def get_now(): | |
| """A simple function to get the current time.""" | |
| return datetime.now() | |
| # ============================================================================== | |
| # ComprehensivePodcastReport Class | |
| # ============================================================================== | |
| class ComprehensivePodcastReport: | |
| """ | |
| Generates a complete podcast performance report, combining overall analytics | |
| with detailed daily and cumulative analysis of episodes within a specified period. | |
| """ | |
| def __init__(self, client_name): | |
| """Initialize the report generator.""" | |
| self.client_name = client_name | |
| self.all_time_data = {} | |
| self.period_data = {} | |
| self.episode_specific_data = {} | |
| self.unmatched_episode_csvs = [] | |
| self.title_translation_cache = {} | |
| self.report_date = get_now().strftime("%B %d, %Y") | |
| self.date_range_str = "All Time" | |
| self.start_date = None | |
| self.end_date = None | |
| self.gemini_configured = False | |
| def configure_gemini(self, api_key): | |
| """Configure Gemini API with the provided key.""" | |
| if IS_GENAI_AVAILABLE and api_key: | |
| try: | |
| genai.configure(api_key=api_key) | |
| self.gemini_configured = True | |
| print("✅ Gemini API Key configured.") | |
| return True | |
| except Exception as e: | |
| print(f"❌ Error configuring Gemini API: {e}") | |
| return False | |
| return False | |
| def _fix_spotify_timestamps(self, timestamp_series): | |
| """Fix Spotify's invalid '24:00:00' timestamps.""" | |
| return timestamp_series.astype(str).str.replace('24:00:00', '23:59:59') | |
| def load_general_data(self, file_paths): | |
| """Load all general CSV files (OnSpotify, EpisodeRankings, etc.).""" | |
| print("📊 Loading and processing general data files...") | |
| try: | |
| self.all_time_data['time_series'] = pd.read_csv(file_paths['time_series']) | |
| self.all_time_data['time_series']['Date'] = pd.to_datetime(self._fix_spotify_timestamps(self.all_time_data['time_series']['Time (UTC)'])) | |
| self.all_time_data['episodes'] = pd.read_csv(file_paths['episodes']) | |
| self.all_time_data['episodes']['Publish Date'] = pd.to_datetime(self._fix_spotify_timestamps(self.all_time_data['episodes']['Publish Time (UTC)'])).dt.normalize() | |
| except KeyError as e: | |
| raise Exception(f"❌ Missing a required file: {e}. Please include OnSpotify and EpisodeRankings files.") | |
| except Exception as e: | |
| raise Exception(f"❌ Error loading required files: {e}") | |
| # Load optional files | |
| optional_files = ['streams', 'geo', 'apps', 'devices'] | |
| for file_type in optional_files: | |
| if file_type in file_paths: | |
| try: | |
| self.all_time_data[file_type] = pd.read_csv(file_paths[file_type]) | |
| if file_type == 'streams': | |
| self.all_time_data['streams']['Date'] = pd.to_datetime(self._fix_spotify_timestamps(self.all_time_data['streams']['Time (UTC)'])) | |
| streams_df = self.all_time_data['streams'] | |
| first_nonzero_idx = streams_df[streams_df['Streams & Downloads'] > 0].index.min() | |
| if pd.notna(first_nonzero_idx): | |
| self.all_time_data['streams'] = streams_df.loc[first_nonzero_idx:].reset_index(drop=True) | |
| print(f"✅ Loaded optional file: {file_type}") | |
| except Exception as e: | |
| print(f"⚠️ Warning: Could not load {file_type} file: {e}") | |
| self.period_data = {key: df.copy() for key, df in self.all_time_data.items()} | |
| print(f"✅ General data loaded successfully for {self.client_name}") | |
| def filter_data_by_date(self, start_date, end_date): | |
| """Filter the loaded data to a specific date range.""" | |
| self.start_date = pd.to_datetime(start_date).normalize() | |
| self.end_date = pd.to_datetime(end_date).normalize() | |
| self.date_range_str = f"{self.start_date.strftime('%Y-%m-%d')} to {self.end_date.strftime('%Y-%m-%d')}" | |
| print(f"🔎 Filtering data for period: {self.date_range_str}") | |
| for key in ['time_series', 'streams']: | |
| if key in self.period_data: | |
| df = self.period_data[key] | |
| self.period_data[key] = df[(df['Date'] >= self.start_date) & (df['Date'] <= self.end_date)] | |
| def _normalize_text(self, text): | |
| """Normalizes text for fuzzy string matching.""" | |
| return re.sub(r'[^\u0590-\u05FFa-zA-Z0-9\-]', '', str(text).replace(':', '').replace(' ', '')).lower() | |
| def identify_episodes_in_period(self): | |
| """Identifies episodes in the period and returns a formatted string and the dataframe.""" | |
| episodes_df = self.all_time_data.get('episodes') | |
| if episodes_df is None: | |
| return "⚠️ EpisodeRankings data is missing.", pd.DataFrame() | |
| episodes_in_period = episodes_df[ | |
| (episodes_df['Publish Date'] >= self.start_date) & | |
| (episodes_df['Publish Date'] <= self.end_date) | |
| ].sort_values('Publish Date', ascending=False).reset_index(drop=True) | |
| if episodes_in_period.empty: | |
| return ("✅ No episodes were published in the selected period. " | |
| "You can proceed to generate the report for general stats."), episodes_in_period | |
| output_str = f"📺 Found **{len(episodes_in_period)}** episodes published in the period. Please upload their individual CSVs below:\n\n" | |
| for _, row in episodes_in_period.iterrows(): | |
| output_str += f"- **{row['Episode Title']}** (Published: {row['Publish Date']:%Y-%m-%d})\n" | |
| return output_str, episodes_in_period | |
| def load_and_match_episode_csvs(self, uploaded_files, episodes_in_period): | |
| """Matches and loads individual episode CSVs from uploaded files.""" | |
| if not uploaded_files or episodes_in_period.empty: | |
| return | |
| print("\n🔍 Matching and loading individual episode CSVs...") | |
| episodes_in_period['normalized_title'] = episodes_in_period['Episode Title'].apply(self._normalize_text) | |
| for file_obj in uploaded_files: | |
| if file_obj is None: | |
| continue | |
| filename = os.path.basename(file_obj.name) | |
| file_type = 'spotify' if 'OnSpotify' in filename else 'all_platforms' if 'StreamsAndDownloads' in filename else None | |
| if not file_type: | |
| continue | |
| clean_filename = re.sub(r'\s*\(\d+\)|\s+\d+(?=\.csv)', '', filename) | |
| normalized_filename = self._normalize_text(clean_filename) | |
| episodes_in_period['similarity'] = episodes_in_period['normalized_title'].apply( | |
| lambda title: SequenceMatcher(None, normalized_filename, title).ratio() | |
| ) | |
| best_match = episodes_in_period.loc[episodes_in_period['similarity'].idxmax()] | |
| if best_match['similarity'] > 0.5: | |
| episode_title = best_match['Episode Title'] | |
| print(f" ✅ Matched: {filename[:40]}... -> {episode_title[:40]}...") | |
| try: | |
| # Read the file content | |
| df = pd.read_csv(file_obj.name) | |
| df['Date'] = pd.to_datetime(df['Time (UTC)'].str.split(',').str[0], errors='coerce').dt.normalize() | |
| value_col = next((col for col in ['Plays', 'Streams & Downloads'] if col in df.columns), None) | |
| if not value_col: | |
| continue | |
| episode_df = df[['Date', value_col]].rename(columns={value_col: 'value'}).groupby('Date')['value'].sum().reset_index() | |
| if episode_title not in self.episode_specific_data: | |
| self.episode_specific_data[episode_title] = {} | |
| self.episode_specific_data[episode_title][file_type] = episode_df | |
| except Exception as e: | |
| print(f" -> Error processing file {filename}: {e}") | |
| else: | |
| self.unmatched_episode_csvs.append(filename) | |
| def calculate_key_metrics(self, use_all_time=False): | |
| """Calculate core performance metrics.""" | |
| data_scope = self.all_time_data if use_all_time else self.period_data | |
| ts_data = data_scope.get('time_series', pd.DataFrame()) | |
| if ts_data.empty: | |
| return {} | |
| ts_followers_cleaned = ts_data.dropna(subset=['Followers']) | |
| current_followers = int(ts_followers_cleaned['Followers'].iloc[-1]) if not ts_followers_cleaned.empty else 0 | |
| total_plays = ts_data['Plays'].sum() | |
| total_streams = ts_data['Streams'].sum() | |
| metrics = { | |
| 'total_plays': int(total_plays), | |
| 'total_streams': int(total_streams), | |
| 'avg_daily_plays': ts_data['Plays'].mean(), | |
| 'engagement_percentage': (total_streams / max(total_plays, 1)) * 100, | |
| 'current_followers': current_followers | |
| } | |
| if use_all_time: | |
| ep_data = self.all_time_data.get('episodes', pd.DataFrame()) | |
| metrics.update({ | |
| 'total_episodes': len(ep_data), | |
| 'median_streams_per_episode': ep_data['Streams & Downloads'].median() if not ep_data.empty else 0, | |
| 'performance_benchmark': ep_data['Streams & Downloads'].quantile(0.75) if not ep_data.empty else 0 | |
| }) | |
| else: | |
| ep_data_all = self.all_time_data.get('episodes', pd.DataFrame()) | |
| episodes_in_period = ep_data_all[ | |
| (ep_data_all['Publish Date'] >= self.start_date) & | |
| (ep_data_all['Publish Date'] <= self.end_date) | |
| ] | |
| metrics['performance_benchmark_period'] = episodes_in_period['Streams & Downloads'].quantile(0.75) if not episodes_in_period.empty else 0 | |
| return metrics | |
| def analyze_growth_trends(self, period_days=30): | |
| """Analyze growth trends for the selected period.""" | |
| ts_data = self.period_data['time_series'].dropna(subset=['Plays', 'Followers']).sort_values('Date') | |
| if len(ts_data) < period_days * 2: | |
| return {} | |
| recent_period = ts_data.tail(period_days) | |
| previous_period = ts_data.iloc[-(period_days*2):-period_days] | |
| if recent_period.empty or previous_period.empty: | |
| return {} | |
| recent_gain = recent_period['Followers'].iloc[-1] - recent_period['Followers'].iloc[0] | |
| previous_gain = previous_period['Followers'].iloc[-1] - previous_period['Followers'].iloc[0] | |
| return { | |
| 'plays_growth_rate_median': ((recent_period['Plays'].median() - previous_period['Plays'].median()) / max(previous_period['Plays'].median(), 1)) * 100, | |
| 'followers_gained': int(recent_gain), | |
| 'follower_growth_rate': ((recent_gain - previous_gain) / max(abs(previous_gain), 1)) * 100 if previous_gain != 0 else float('inf') | |
| } | |
| def analyze_seasonal_patterns(self): | |
| """Analyze weekly listening patterns.""" | |
| ts_data = self.period_data['time_series'].dropna(subset=['Plays']) | |
| if len(ts_data) < 7: | |
| return {} | |
| ts_data['DayOfWeek'] = ts_data['Date'].dt.day_name() | |
| weekly_avg = ts_data.groupby('DayOfWeek')['Plays'].mean() | |
| return { | |
| 'best_day': weekly_avg.idxmax(), | |
| 'worst_day': weekly_avg.idxmin(), | |
| 'weekly_consistency': (1 - (weekly_avg.std() / weekly_avg.mean())) * 100 if weekly_avg.mean() > 0 else 0 | |
| } | |
| def _get_platform_share(self, platform_name): | |
| """Helper to get platform share from all-time data.""" | |
| apps_df = self.all_time_data.get('apps') | |
| if apps_df is None: | |
| return 0.0 | |
| platform_row = apps_df[apps_df['App'] == platform_name] | |
| return platform_row['Percent of Plays'].iloc[0] * 100 if not platform_row.empty else 0.0 | |
| def _add_regression_line(self, ax, x_values, y_values, label_prefix="Trend"): | |
| """Helper to add a linear regression trendline to a plot.""" | |
| if len(x_values) < 2: | |
| return | |
| x_numeric = np.arange(len(x_values)) | |
| model = LinearRegression().fit(x_numeric.reshape(-1, 1), y_values) | |
| y_pred = model.predict(x_numeric.reshape(-1, 1)) | |
| label = f"{label_prefix} (Slope: {model.coef_[0]:.2f})" | |
| ax.plot(x_values, y_pred, '--', color='red', alpha=0.7, label=label) | |
| def generate_all_visualizations(self): | |
| """Generates a comprehensive set of all overview plots.""" | |
| print("🎨 Generating all performance visualizations...") | |
| plots = [] | |
| ts_data = self.period_data['time_series'].sort_values('Date') | |
| # Daily Plays | |
| if not ts_data.empty: | |
| fig, ax = plt.subplots(figsize=(12, 6)) | |
| ax.plot(ts_data['Date'], ts_data['Plays'], label='Daily Plays (Spotify)', color='blue') | |
| self._add_regression_line(ax, ts_data['Date'], ts_data['Plays']) | |
| ax.set_title(f'{self.client_name} - Daily Plays (OnSpotify)', fontsize=14) | |
| ax.grid(True, alpha=0.3) | |
| ax.legend() | |
| plt.tight_layout() | |
| plots.append(fig) | |
| # Daily Streams | |
| if 'streams' in self.period_data and not self.period_data['streams'].empty: | |
| streams_data = self.period_data['streams'].sort_values('Date') | |
| fig, ax = plt.subplots(figsize=(12, 6)) | |
| ax.plot(streams_data['Date'], streams_data['Streams & Downloads'], label='Daily Streams & Downloads', color='green') | |
| self._add_regression_line(ax, streams_data['Date'], streams_data['Streams & Downloads']) | |
| ax.set_title(f'{self.client_name} - Daily Streams & Downloads (All Platforms)', fontsize=14) | |
| ax.grid(True, alpha=0.3) | |
| ax.legend() | |
| plt.tight_layout() | |
| plots.append(fig) | |
| # Monthly Plots | |
| graph_start = self.start_date.replace(day=1) if self.start_date.day != 1 else self.start_date | |
| for key, col, color in [('time_series', 'Plays', 'skyblue'), ('streams', 'Streams & Downloads', 'lightgreen')]: | |
| if key in self.all_time_data: | |
| monthly_data = self.all_time_data[key] | |
| monthly_data = monthly_data[ | |
| (monthly_data['Date'] >= graph_start) & | |
| (monthly_data['Date'] <= self.end_date) | |
| ] | |
| if not monthly_data.empty: | |
| monthly_data['YearMonth'] = monthly_data['Date'].dt.to_period('M') | |
| monthly_values = monthly_data.groupby('YearMonth')[col].sum() | |
| fig, ax = plt.subplots(figsize=(12, 6)) | |
| bars = ax.bar(np.arange(len(monthly_values)), monthly_values.values, color=color, edgecolor='navy') | |
| self._add_regression_line(ax, np.arange(len(monthly_values)), monthly_values.values) | |
| ax.set_xticks(np.arange(len(monthly_values))) | |
| ax.set_xticklabels([str(p) for p in monthly_values.index], rotation=45) | |
| ax.set_title(f'{self.client_name} - Monthly {col}', fontsize=14) | |
| ax.legend() | |
| plt.tight_layout() | |
| current_month = pd.Period(get_now(), 'M') | |
| if current_month in monthly_values.index: | |
| bars[monthly_values.index.get_loc(current_month)].set_color('orange') | |
| plots.append(fig) | |
| # Follower Growth | |
| follower_data = ts_data.dropna(subset=['Followers']) | |
| if not follower_data.empty: | |
| fig, ax = plt.subplots(figsize=(12, 6)) | |
| ax.plot(follower_data['Date'], follower_data['Followers'], label='Followers', color='purple') | |
| self._add_regression_line(ax, follower_data['Date'], follower_data['Followers'], label_prefix="Follower Trend") | |
| ax.set_title(f'{self.client_name} - Follower Growth', fontsize=14) | |
| ax.grid(True, alpha=0.3) | |
| ax.legend() | |
| plt.tight_layout() | |
| plots.append(fig) | |
| # Consumption Hours | |
| consump_data = ts_data.dropna(subset=['Consumption Hours']) | |
| if not consump_data.empty and consump_data['Consumption Hours'].sum() > 0: | |
| fig, ax = plt.subplots(figsize=(12, 6)) | |
| ax.plot(consump_data['Date'], consump_data['Consumption Hours'], label='Hours', color='teal') | |
| self._add_regression_line(ax, consump_data['Date'], consump_data['Consumption Hours'], label_prefix="Consumption Trend") | |
| ax.set_title(f'{self.client_name} - Daily Consumption Hours', fontsize=14) | |
| ax.grid(True, alpha=0.3) | |
| ax.legend() | |
| plt.tight_layout() | |
| plots.append(fig) | |
| # Stream/Play Ratio | |
| ratio_df = ts_data[['Date', 'Streams', 'Plays']].copy() | |
| ratio_df['ratio'] = ratio_df['Streams'] / ratio_df['Plays'].replace(0, np.nan) | |
| ratio_df['ratio_30d_avg'] = ratio_df['ratio'].rolling(30, min_periods=1).mean() | |
| ratio_df.dropna(subset=['ratio_30d_avg'], inplace=True) | |
| if not ratio_df.empty: | |
| fig, ax = plt.subplots(figsize=(12, 6)) | |
| ax.plot(ratio_df['Date'], ratio_df['ratio_30d_avg'], label='30-Day Avg Stream/Play Ratio', color='orange') | |
| self._add_regression_line(ax, ratio_df['Date'], ratio_df['ratio_30d_avg'], label_prefix="Ratio Trend") | |
| ax.set_title(f'{self.client_name} - Stream/Play Ratio (30-Day Average)', fontsize=14) | |
| ax.grid(True, alpha=0.3) | |
| ax.legend() | |
| plt.tight_layout() | |
| plots.append(fig) | |
| # Platform Distribution | |
| if 'apps' in self.all_time_data: | |
| fig, ax = plt.subplots(figsize=(8, 8)) | |
| self.all_time_data['apps'].head(5).plot.pie( | |
| y='Percent of Plays', | |
| labels=self.all_time_data['apps']['App'].head(5), | |
| autopct='%1.1f%%', | |
| ax=ax, | |
| legend=False | |
| ) | |
| ax.set_title(f'{self.client_name} - Platform Distribution', fontsize=14) | |
| ax.set_ylabel('') | |
| plt.tight_layout() | |
| plots.append(fig) | |
| # Device Distribution | |
| if 'devices' in self.all_time_data: | |
| fig, ax = plt.subplots(figsize=(8, 8)) | |
| self.all_time_data['devices'].head(5).plot.pie( | |
| y='Percent of Plays', | |
| labels=self.all_time_data['devices']['Device'].head(5), | |
| autopct='%1.1f%%', | |
| ax=ax, | |
| legend=False | |
| ) | |
| ax.set_title(f'{self.client_name} - Device Distribution', fontsize=14) | |
| ax.set_ylabel('') | |
| plt.tight_layout() | |
| plots.append(fig) | |
| # Geographic Markets | |
| if 'geo' in self.all_time_data: | |
| fig, ax = plt.subplots(figsize=(10, 6)) | |
| top_geo = self.all_time_data['geo'].head(10) | |
| ax.barh(top_geo['Geo'], top_geo['Percent of Plays'] * 100, color='coral') | |
| ax.set_title(f'{self.client_name} - Top 10 Geographic Markets', fontsize=14) | |
| ax.invert_yaxis() | |
| ax.grid(True, alpha=0.3, axis='x') | |
| plt.tight_layout() | |
| plots.append(fig) | |
| # Episode Performance Distribution | |
| ep_data_all = self.all_time_data.get('episodes') | |
| if ep_data_all is not None: | |
| fig, ax = plt.subplots(figsize=(10, 6)) | |
| ax.hist(ep_data_all['Streams & Downloads'], bins=30, color='skyblue', edgecolor='navy') | |
| ax.axvline(ep_data_all['Streams & Downloads'].mean(), color='red', linestyle='--', label='Mean') | |
| ax.set_title(f'{self.client_name} - Episode Performance Distribution (All Time)', fontsize=14) | |
| ax.legend() | |
| plt.tight_layout() | |
| plots.append(fig) | |
| episodes_in_period = ep_data_all[ | |
| (ep_data_all['Publish Date'] >= self.start_date) & | |
| (ep_data_all['Publish Date'] <= self.end_date) | |
| ] | |
| if not episodes_in_period.empty: | |
| fig, ax = plt.subplots(figsize=(10, 6)) | |
| ax.hist(episodes_in_period['Streams & Downloads'], bins=15, color='teal', edgecolor='darkslategray') | |
| ax.axvline(episodes_in_period['Streams & Downloads'].mean(), color='red', linestyle='--', label='Mean') | |
| ax.set_title(f'{self.client_name} - Episode Performance (Published in Period)', fontsize=14) | |
| ax.legend() | |
| plt.tight_layout() | |
| plots.append(fig) | |
| return plots | |
| def _translate_title(self, hebrew_title): | |
| """Translates a Hebrew title to a short English legend title using Gemini.""" | |
| if hebrew_title in self.title_translation_cache: | |
| return self.title_translation_cache[hebrew_title] | |
| if not self.gemini_configured: | |
| return hebrew_title[:40] + '...' | |
| try: | |
| model = genai.GenerativeModel('gemini-2.5-flash') | |
| prompt = f"""Analyze the Hebrew podcast title "{hebrew_title}". Generate a short, readable English legend title formatted as "[Guest Name] - #[Episode Number]". Transliterate the name. If there is no episode number, use only the name. If there is no name, create a concise English summary of the topic. If you recognize מהדורת מוסף in the title, then the output would be: "Investors Panel - #[Episode Number]".The final title must be under 5 words.""" | |
| response = model.generate_content(prompt) | |
| time.sleep(1.5) | |
| translated = response.text.strip() | |
| self.title_translation_cache[hebrew_title] = translated | |
| return translated | |
| except Exception as e: | |
| print(f" -> Gemini API Error: {e}") | |
| return hebrew_title[:40] + '...' | |
| def generate_episode_specific_plots(self, max_episodes=10): | |
| """Generates the cumulative performance plots for individual episodes.""" | |
| print("🚀 Generating episode-specific cumulative plots...") | |
| plots = [] | |
| if not self.episode_specific_data: | |
| return plots | |
| for data_source in ['spotify', 'all_platforms']: | |
| ep_data_source = {t: d[data_source] for t, d in self.episode_specific_data.items() if data_source in d} | |
| if not ep_data_source: | |
| continue | |
| ep_totals = {title: df['value'].sum() for title, df in ep_data_source.items()} | |
| top_episodes = sorted(ep_totals, key=ep_totals.get, reverse=True)[:max_episodes] | |
| date_index = pd.date_range(start=self.start_date, end=self.end_date, freq='D') | |
| plot_df = pd.DataFrame(index=date_index) | |
| for title in top_episodes: | |
| plot_df = plot_df.join(ep_data_source[title].set_index('Date').rename(columns={'value': title})) | |
| cumulative_df = plot_df.fillna(0).cumsum() | |
| fig, ax = plt.subplots(figsize=(15, 8)) | |
| for h_title in cumulative_df.columns: | |
| ax.plot(cumulative_df.index, cumulative_df[h_title], label=self._translate_title(h_title), linewidth=2.5) | |
| ax.set_title(f'Cumulative Performance by Date ({data_source.replace("_", " ").title()})', fontsize=16) | |
| ax.legend(bbox_to_anchor=(1.02, 1), loc='upper left') | |
| plt.tight_layout() | |
| plots.append(fig) | |
| # Air day analysis | |
| airday_df = pd.DataFrame() | |
| for title in top_episodes: | |
| df = ep_data_source[title] | |
| first_play = df[df['value'] > 0]['Date'].min() | |
| if pd.isna(first_play): | |
| continue | |
| df_after = df[df['Date'] >= first_play].copy() | |
| airday_df[title] = df_after['value'].cumsum().reset_index(drop=True) | |
| if not airday_df.empty: | |
| airday_df['Average'] = airday_df.mean(axis=1) | |
| fig, ax = plt.subplots(figsize=(15, 8)) | |
| for h_title in top_episodes: | |
| if h_title in airday_df.columns: | |
| ax.plot(airday_df.index + 1, airday_df[h_title], label=self._translate_title(h_title), alpha=0.8) | |
| ax.plot(airday_df.index + 1, airday_df['Average'], 'k--', label='Average', linewidth=2.5) | |
| ax.set_title(f'Cumulative Performance by Air Day ({data_source.replace("_", " ").title()})', fontsize=16) | |
| ax.set_xlabel('Days Since Release') | |
| ax.legend(bbox_to_anchor=(1.02, 1), loc='upper left') | |
| plt.tight_layout() | |
| plots.append(fig) | |
| return plots | |
| def generate_executive_summary(self, all_time_metrics, period_metrics, trends, seasonal): | |
| """Generates the final executive summary text.""" | |
| summary = f"""# {self.client_name} - Podcast Performance Report | |
| *Generated on {self.report_date}* | |
| --- | |
| ## 📈 All-Time Performance Summary | |
| *A high-level overview of the podcast's entire history.* | |
| - **Total Plays**: {all_time_metrics.get('total_plays', 0):,} | |
| - **Total Streams**: {all_time_metrics.get('total_streams', 0):,} | |
| - **Total Episodes**: {all_time_metrics.get('total_episodes', 0)} | |
| - **Most Recent Follower Count**: {all_time_metrics.get('current_followers', 0):,} | |
| - **Median Streams per Episode**: {all_time_metrics.get('median_streams_per_episode', 0):,.0f} | |
| - **Performance Benchmark (Top 25% of Episodes)**: > {all_time_metrics.get('performance_benchmark', 0):,.0f} streams | |
| --- | |
| ## 📊 Performance for Selected Period: {self.date_range_str} | |
| *A detailed analysis of performance within the specified date range.* | |
| ### Key Performance Indicators (Period) | |
| - **Total Plays in Period**: {period_metrics.get('total_plays', 0):,} | |
| - **Total Streams in Period**: {period_metrics.get('total_streams', 0):,} | |
| - **Average Daily Plays**: {period_metrics.get('avg_daily_plays', 0):,.0f} | |
| - **Engagement Rate (Streams/Plays)**: {period_metrics.get('engagement_percentage', 0):.1f}% | |
| - **Performance Benchmark (Top 25% of Episodes in Period)**: > {period_metrics.get('performance_benchmark_period', 0):,.0f} streams | |
| """ | |
| if trends: | |
| summary += f""" | |
| ### Growth Trends (Comparison of 30-Day Sub-periods) | |
| - **Plays Growth (Median)**: {trends.get('plays_growth_rate_median', 0):+.1f}% | |
| - **Followers Gained**: {trends.get('followers_gained', 0):+,} | |
| - **Follower Growth Rate**: {trends.get('follower_growth_rate', 0):+.1f}% (vs. prior period) | |
| """ | |
| if seasonal: | |
| summary += f""" | |
| ### Listening Patterns (Period) | |
| - **Best Day for Plays**: {seasonal.get('best_day')} | |
| - **Worst Day for Plays**: {seasonal.get('worst_day')} | |
| - **Weekly Listening Consistency**: {seasonal.get('weekly_consistency', 0):.1f}% | |
| """ | |
| summary += "\n### Audience Insights (All-Time)\n" | |
| if 'geo' in self.all_time_data: | |
| summary += f"- **Primary Market**: {self.all_time_data['geo'].loc[0, 'Geo']} ({self.all_time_data['geo'].loc[0, 'Percent of Plays'] * 100:.1f}% of plays)\n" | |
| if 'apps' in self.all_time_data: | |
| summary += f"- **Platform Mix**: {self._get_platform_share('Spotify'):.1f}% Spotify, {self._get_platform_share('Apple Podcasts'):.1f}% Apple Podcasts\n" | |
| summary += "\n## 🏆 Top 5 Performing Episodes (All-Time)\n" | |
| ep_data = self.all_time_data.get('episodes') | |
| if ep_data is not None: | |
| for i, (_, row) in enumerate(ep_data.nlargest(5, 'Streams & Downloads').iterrows(), 1): | |
| summary += f"{i}. **{row['Episode Title'][:60]}...**\n {row['Streams & Downloads']:,} streams | {row['Publish Date']:%B %Y}\n\n" | |
| return summary | |
| # ============================================================================== | |
| # Gradio specific functions | |
| # ============================================================================== | |
| def process_step_1(api_key, client_name, date_from_str, date_to_str, general_files): | |
| """Handles the first step of the analysis.""" | |
| try: | |
| if not client_name or not date_from_str or not general_files: | |
| return None, "❌ Please fill in all required fields and upload files.", None, gr.update(visible=False) | |
| # Initialize analyzer | |
| analyzer = ComprehensivePodcastReport(client_name) | |
| # Configure Gemini if API key provided | |
| if api_key: | |
| analyzer.configure_gemini(api_key) | |
| # Process uploaded files | |
| file_patterns = { | |
| 'time_series': 'OnSpotify', | |
| 'episodes': 'EpisodeRankings', | |
| 'geo': 'GeoLocation', | |
| 'apps': 'PlaysByApp', | |
| 'devices': 'PlaysByDevice', | |
| 'streams': 'StreamsAndDownloads' | |
| } | |
| detected_files = {} | |
| for f in general_files: | |
| if f is None: | |
| continue | |
| fname = os.path.basename(f.name) | |
| for ftype, pattern in file_patterns.items(): | |
| if pattern in fname: | |
| detected_files[ftype] = f.name | |
| break | |
| if 'time_series' not in detected_files or 'episodes' not in detected_files: | |
| return None, "❌ Required files not found. Please upload at least OnSpotify and EpisodeRankings CSVs.", None, gr.update(visible=False) | |
| # Load data | |
| analyzer.load_general_data(detected_files) | |
| # Set date range | |
| end_date = pd.to_datetime(date_to_str) if date_to_str else get_now() | |
| try: | |
| date_from = int(date_from_str) | |
| start_date = end_date - timedelta(days=date_from) | |
| except ValueError: | |
| start_date = pd.to_datetime(date_from_str) | |
| analyzer.filter_data_by_date(start_date, end_date) | |
| # Identify episodes in period | |
| episode_list_md, episodes_in_period_df = analyzer.identify_episodes_in_period() | |
| # Convert episodes dataframe to JSON for state management | |
| episodes_json = episodes_in_period_df.to_json(orient='records', date_format='iso') | |
| return analyzer, episode_list_md, episodes_json, gr.update(visible=True) | |
| except Exception as e: | |
| error_msg = f"❌ Error during initial processing: {str(e)}" | |
| print(error_msg) | |
| return None, error_msg, None, gr.update(visible=False) | |
| def process_step_2(analyzer, episodes_json, episode_files): | |
| """Handles the final report generation, returning a summary and a list of plots.""" | |
| try: | |
| if analyzer is None: | |
| return "❌ Error: Initial processing step was not completed.", [] | |
| # Reconstruct episodes dataframe from JSON | |
| episodes_data = json.loads(episodes_json) if episodes_json else [] | |
| episodes_in_period_df = pd.DataFrame(episodes_data) | |
| if not episodes_in_period_df.empty and 'Publish Date' in episodes_in_period_df.columns: | |
| episodes_in_period_df['Publish Date'] = pd.to_datetime(episodes_in_period_df['Publish Date']) | |
| # Load episode-specific data | |
| analyzer.load_and_match_episode_csvs(episode_files or [], episodes_in_period_df) | |
| # Calculate metrics | |
| all_time_metrics = analyzer.calculate_key_metrics(use_all_time=True) | |
| period_metrics = analyzer.calculate_key_metrics(use_all_time=False) | |
| trends = analyzer.analyze_growth_trends() | |
| seasonal = analyzer.analyze_seasonal_patterns() | |
| # Generate summary | |
| summary = analyzer.generate_executive_summary(all_time_metrics, period_metrics, trends, seasonal) | |
| # Generate plots | |
| general_plots = analyzer.generate_all_visualizations() | |
| episode_plots = analyzer.generate_episode_specific_plots() | |
| all_plots = general_plots + episode_plots | |
| # Convert matplotlib figures to images for Gradio | |
| plot_images = [] | |
| for fig in all_plots: | |
| temp_file = tempfile.NamedTemporaryFile(delete=False, suffix='.png') | |
| fig.savefig(temp_file.name, dpi=150, bbox_inches='tight') | |
| plt.close(fig) # Important: close figure to free memory | |
| plot_images.append(temp_file.name) | |
| return summary, plot_images | |
| except Exception as e: | |
| error_msg = f"❌ Error during report generation: {str(e)}" | |
| print(error_msg) | |
| return error_msg, [] | |
| # ============================================================================== | |
| # Gradio UI Layout | |
| # ============================================================================== | |
| with gr.Blocks(theme=gr.themes.Soft(), title="Valuebell Podcast Analytics") as demo: | |
| gr.HTML(""" | |
| <div style="text-align: center; margin-bottom: 30px;"> | |
| <h1>🎙️ Valuebell Podcast Analytics Dashboard</h1> | |
| <p style="font-size: 18px; color: #666;"> | |
| Professional podcast performance reports from Spotify for Creators CSV exports | |
| </p> | |
| </div> | |
| """) | |
| # State variables | |
| analyzer_state = gr.State(None) | |
| episodes_df_state = gr.State(None) | |
| with gr.Row(): | |
| with gr.Column(scale=1): | |
| gr.Markdown("## 📋 Step 1: Initial Setup") | |
| with gr.Group(): | |
| api_key_input = gr.Textbox( | |
| label="🔑 Gemini API Key (Optional)", | |
| type="password", | |
| placeholder="For Hebrew title translation...", | |
| info="Leave empty if not using Hebrew content" | |
| ) | |
| client_name_input = gr.Textbox( | |
| label="🎙️ Client / Podcast Name", | |
| placeholder="e.g., The Co-Pilot Podcast", | |
| value="My Podcast" | |
| ) | |
| with gr.Row(): | |
| date_from_input = gr.Textbox( | |
| label="📅 Start Date or Period", | |
| placeholder="e.g., 60 (last 60 days) or 2025-07-01", | |
| value="60" | |
| ) | |
| date_to_input = gr.Textbox( | |
| label="📅 End Date (Optional)", | |
| placeholder="e.g., 2025-08-18 (defaults to today)" | |
| ) | |
| general_files_input = gr.File( | |
| label="📁 Upload General CSVs", | |
| file_count="multiple", | |
| file_types=[".csv"] | |
| ) | |
| gr.HTML(""" | |
| <div style="background-color: #f0f8ff; padding: 10px; border-radius: 5px; margin: 10px 0;"> | |
| <small><strong>Required:</strong> OnSpotify, EpisodeRankings<br> | |
| <strong>Optional:</strong> StreamsAndDownloads, GeoLocation, PlaysByApp, PlaysByDevice</small> | |
| </div> | |
| """) | |
| step1_button = gr.Button("🚀 1. Process General Files", variant="primary", size="lg") | |
| with gr.Column(scale=2): | |
| with gr.Group(visible=False) as step2_box: | |
| gr.Markdown("## 📊 Step 2: Episode Details & Report Generation") | |
| episode_list_output = gr.Markdown("Processing...") | |
| episode_files_input = gr.File( | |
| label="📁 Upload Individual Episode CSVs (Optional)", | |
| file_count="multiple", | |
| file_types=[".csv"] | |
| ) | |
| step2_button = gr.Button("📈 2. Generate Full Report", variant="primary", size="lg") | |
| gr.Markdown("---") | |
| with gr.Column(): | |
| gr.Markdown("## 📋 Executive Summary") | |
| summary_output = gr.Markdown("Upload files and process to see your comprehensive report...") | |
| gr.Markdown("## 📊 Performance Visualizations") | |
| gallery_output = gr.Gallery( | |
| label="Generated Charts", | |
| columns=2, | |
| object_fit="contain", | |
| height="auto", | |
| show_label=False | |
| ) | |
| # Event handlers | |
| step1_button.click( | |
| fn=process_step_1, | |
| inputs=[api_key_input, client_name_input, date_from_input, date_to_input, general_files_input], | |
| outputs=[analyzer_state, episode_list_output, episodes_df_state, step2_box], | |
| show_progress=True | |
| ) | |
| step2_button.click( | |
| fn=process_step_2, | |
| inputs=[analyzer_state, episodes_df_state, episode_files_input], | |
| outputs=[summary_output, gallery_output], | |
| show_progress=True | |
| ) | |
| gr.HTML(""" | |
| <div style="text-align: center; margin-top: 30px; padding: 20px; background-color: #f8f9fa; border-radius: 8px;"> | |
| <h4>💡 Tips for Best Results:</h4> | |
| <ul style="text-align: left; display: inline-block; max-width: 600px;"> | |
| <li>Ensure CSV files contain the expected keywords in their names</li> | |
| <li>For Hebrew podcasts, add your Gemini API key for title translation</li> | |
| <li>Include episode-specific CSV files for detailed performance tracking</li> | |
| <li>Use date ranges that cover complete weeks for better trend analysis</li> | |
| </ul> | |
| </div> | |
| """) | |
| if __name__ == "__main__": | |
| demo.launch(share=True, debug=True) |