Enhance user retention explorer API and page with new volume metrics

- Added new fields to the `RetentionExplorerItem` model in `user_retention_explorer_api.py` to track total initial selected and other market volumes over 7 days, as well as total volumes over 14 and 28 days.
- Updated the `calculate_retention_for_market` function to compute and return these new volume metrics, ensuring they are included in the response.
- Enhanced the user retention explorer page to display the new high-level volume metrics, providing users with better insights into market performance.

These changes improve the analytical capabilities of the user retention explorer, allowing for a more comprehensive understanding of trader behavior and market dynamics.

Author: goldhaxx

backend/api/user_retention_explorer_api.py

@@ -84,6 +84,10 @@ class RetentionExplorerItem(BaseModel):
     retention_ratio_14d: float
     retention_ratio_28d: float
     user_data: List[UserVolumeDetails]
+    total_initial_selected_market_volume_7d: float
+    total_initial_other_market_volume_7d: float
+    total_volume_14d: float
+    total_volume_28d: float
 
 UTC = tz.tzutc()
 
@@ -219,7 +223,11 @@ async def calculate_retention_for_market(market_name: str, start_date_str: str)
             return {
                 "market": market_name, "category": market_config.get("category", []), "start_date": start_date_str,
                 "new_traders_count": 0, "retained_14d_count": 0, "retained_28d_count": 0,
-                "retention_ratio_14d": 0.0, "retention_ratio_28d": 0.0, "user_data": []
+                "retention_ratio_14d": 0.0, "retention_ratio_28d": 0.0, "user_data": [],
+                "total_initial_selected_market_volume_7d": 0.0,
+                "total_initial_other_market_volume_7d": 0.0,
+                "total_volume_14d": 0.0,
+                "total_volume_28d": 0.0,
             }
 
         # --- Volume Calculation ---
@@ -240,6 +248,9 @@ def get_and_merge_volume(
 
             vol_df = pd.read_sql(vol_sql, conn)
             merged_df = base_df.merge(vol_df, on='user', how='left')
+            
+            # Explicitly convert to numeric to avoid FutureWarning on downcasting
+            merged_df['total_volume'] = pd.to_numeric(merged_df['total_volume'], errors='coerce')
             merged_df['total_volume'] = merged_df['total_volume'].fillna(0)
             return merged_df.rename(columns={'total_volume': column_name})
 
@@ -253,6 +264,12 @@ def get_and_merge_volume(
 
         traders_df = traders_df.rename(columns={'user': 'user_address'})
 
+        # --- Summary Volume Metrics ---
+        total_initial_selected_market_volume_7d = traders_df['initial_selected_market_volume'].sum()
+        total_initial_other_market_volume_7d = traders_df['initial_other_market_volume'].sum()
+        total_volume_14d = (traders_df['selected_market_volume_14d'] + traders_df['other_market_volume_14d']).sum()
+        total_volume_28d = (traders_df['selected_market_volume_28d'] + traders_df['other_market_volume_28d']).sum()
+
         # --- Summary Statistics ---
         retained_14d_count = int((traders_df['other_market_volume_14d'] > 0).sum())
         retained_28d_count = int((traders_df['other_market_volume_28d'] > 0).sum())
@@ -268,7 +285,11 @@ def get_and_merge_volume(
             "retained_28d_count": retained_28d_count,
             "retention_ratio_14d": round(retention_ratio_14d, 4),
             "retention_ratio_28d": round(retention_ratio_28d, 4),
-            "user_data": traders_df.to_dict('records')
+            "user_data": traders_df.to_dict('records'),
+            "total_initial_selected_market_volume_7d": float(total_initial_selected_market_volume_7d),
+            "total_initial_other_market_volume_7d": float(total_initial_other_market_volume_7d),
+            "total_volume_14d": float(total_volume_14d),
+            "total_volume_28d": float(total_volume_28d),
         }
 
         logger.info(f"Successfully calculated consolidated retention for {market_name}.")

src/page/user_retention_explorer_page.py

@@ -121,6 +121,31 @@ def user_retention_explorer_page():
         elif isinstance(result, dict) and "user_data" in result:
             st.header("Analysis Results")
 
+            # --- Display Summary Metrics ---
+            st.subheader("High-Level Volume Metrics")
+            metric_cols = st.columns(4)
+            metric_cols[0].metric(
+                "ISMV7d",
+                f"${result.get('total_initial_selected_market_volume_7d', 0):,.0f}",
+                help="Initial Selected Market Volume (7d): Total volume in the selected market from new traders during their first 7 days."
+            )
+            metric_cols[1].metric(
+                "IOMV7d",
+                f"${result.get('total_initial_other_market_volume_7d', 0):,.0f}",
+                help="Initial Other Market Volume (7d): Total volume in all other markets from new traders during their first 7 days."
+            )
+            metric_cols[2].metric(
+                "TV14d",
+                f"${result.get('total_volume_14d', 0):,.0f}",
+                help="Total Volume (14d): Total volume from the cohort during the 14-day retention period (Days 8-21)."
+            )
+            metric_cols[3].metric(
+                "TV28d",
+                f"${result.get('total_volume_28d', 0):,.0f}",
+                help="Total Volume (28d): Total volume from the cohort during the 28-day retention period (Days 8-35)."
+            )
+
+            st.subheader("Retention Summary")
             df_data = {
                 'Metric': [
                     "Market", "Category", "Analysis Start Date", "New Traders (Count)",