Create formulas.py

formulas.py

@@ -0,0 +1,257 @@
+# formulas.py
+
+PLOT_FORMULAS = {
+    "posts_activity": {
+        "title": "Posts Activity Over Time",
+        "description": (
+            "This chart displays the number of posts made each day over the selected period. "
+            "It helps in understanding posting consistency and identifying trends in content output."
+        ),
+        "calculation_steps": [
+            "1. Takes the posts dataset and a date column (default: 'published_at').",
+            "2. Converts the date column to a proper datetime format.",
+            "3. Removes any entries where the date is invalid.",
+            "4. Groups the posts by day.",
+            "5. Counts the number of posts for each day.",
+            "6. Displays the daily post count as a line graph over time."
+        ]
+    },
+    "mentions_activity": {
+        "title": "Mentions Activity Over Time",
+        "description": (
+            "This chart shows the number of mentions received each day over the selected period. "
+            "It's useful for tracking brand presence and engagement spikes related to mentions."
+        ),
+        "calculation_steps": [
+            "1. Takes the mentions dataset and a date column (default: 'date').",
+            "2. Converts the date column to a proper datetime format.",
+            "3. Removes any entries where the date is invalid.",
+            "4. Groups the mentions by day.",
+            "5. Counts the number of mentions for each day.",
+            "6. Displays the daily mention count as a line graph over time."
+        ]
+    },
+    "mention_sentiment": {
+        "title": "Mention Sentiment Distribution",
+        "description": (
+            "This pie chart illustrates the proportion of mentions categorized by sentiment (e.g., positive, negative, neutral). "
+            "It provides a quick overview of the overall tone surrounding your brand mentions."
+        ),
+        "calculation_steps": [
+            "1. Takes the mentions dataset and a sentiment column (default: 'sentiment_label').",
+            "2. Counts the occurrences of each unique sentiment value (e.g., 'Positive', 'Negative', 'Neutral').",
+            "3. Displays these counts as a pie chart, with each slice representing the percentage of a sentiment category."
+        ]
+    },
+    "followers_count_over_time": {
+        "title": "Followers Count Over Time",
+        "description": (
+            "This chart tracks the cumulative number of organic and paid followers over time for a specific follower metric (e.g., 'follower_gains_monthly'). "
+            "It helps visualize audience growth from different sources."
+            "The specific metric (e.g., monthly gains, total followers) is determined by the 'type_value' parameter used when generating the plot."
+        ),
+        "calculation_steps": [
+            "1. Takes the follower statistics dataset.",
+            "2. Filters the data based on a 'type_filter_column' (default: 'follower_count_type') and a specific 'type_value' (e.g., 'follower_gains_monthly').",
+            "3. Uses a date information column (default: 'category_name', expected to contain date strings) and converts it to datetime objects.",
+            "4. Extracts organic follower counts (default: 'follower_count_organic') and paid follower counts (default: 'follower_count_paid').",
+            "5. Ensures follower counts are numeric, replacing missing values with 0.",
+            "6. Removes entries with invalid dates or follower counts.",
+            "7. Sorts the data by date.",
+            "8. Plots the organic and paid follower counts as separate lines on a graph over time."
+        ]
+    },
+    "followers_growth_rate": {
+        "title": "Follower Growth Rate",
+        "description": (
+            "This chart displays the percentage change in organic and paid followers over time for a specific follower metric. "
+            "It highlights the speed of audience growth or decline. "
+            "The specific metric is determined by the 'type_value' parameter."
+        ),
+        "calculation_steps": [
+            "1. Similar to 'Followers Count Over Time', data is filtered and prepared based on 'type_value'.",
+            "2. The date column is set as the index.",
+            "3. Calculates the period-over-period percentage change for both organic and paid follower counts (e.g., ((current_period_followers - previous_period_followers) / previous_period_followers) * 100).",
+            "4. Handles any infinite values resulting from division by zero (e.g., if previous count was 0).",
+            "5. Plots the calculated organic and paid growth rates as separate lines on a graph over time. The Y-axis is formatted as a percentage."
+        ]
+    },
+    "followers_by_demographics": {
+        "title": "Followers by Demographics",
+        "description": (
+            "This bar chart breaks down the number of organic and paid followers by a chosen demographic category (e.g., country, industry, seniority). "
+            "It shows the top N categories, helping to understand audience composition. The specific demographic breakdown is determined by the 'type_value' (e.g., 'followers_by_country') and 'category_col' parameters."
+        ),
+        "calculation_steps": [
+            "1. Takes the follower statistics dataset.",
+            "2. Filters data based on 'type_filter_column' and a specific 'type_value' that defines the demographic type (e.g., 'followers_by_country').",
+            "3. Extracts organic and paid follower counts, ensuring they are numeric.",
+            "4. Groups the data by the specified 'category_col' (e.g., 'country_name') and sums the organic and paid followers for each category.",
+            "5. Sorts the demographic categories by the total number of followers (organic + paid) in descending order.",
+            "6. Displays the top N (default: 10) demographic categories.",
+            "7. For each top category, plots the number of organic and paid followers as a grouped bar chart."
+        ]
+    },
+    "engagement_rate_over_time": {
+        "title": "Engagement Rate Over Time",
+        "description": (
+            "This chart visualizes the average engagement rate of your posts on a daily basis. "
+            "Engagement rate is typically calculated as (Total Engagements / Total Impressions or Reach or Followers) * 100. "
+            "The specific formula for 'engagement' column should be predefined in your data."
+        ),
+        "calculation_steps": [
+            "1. Takes the posts dataset with a date column (default: 'published_at') and an engagement rate column (default: 'engagement').",
+            "2. Converts the date column to datetime and the engagement rate column to numeric.",
+            "3. Removes entries with invalid dates or engagement rates.",
+            "4. Groups the data by day.",
+            "5. Calculates the average engagement rate for each day.",
+            "6. Plots this daily average engagement rate as a line graph. The Y-axis is formatted as a percentage."
+        ]
+    },
+    "reach_over_time": {
+        "title": "Reach Over Time (Clicks)",
+        "description": (
+            "This chart shows the total number of clicks (often used as a proxy for reach for certain post types or if 'reach' data isn't directly available) on your posts, aggregated daily. "
+            "It helps track how many unique users potentially saw your content, based on click interactions."
+        ),
+        "calculation_steps": [
+            "1. Takes the posts dataset with a date column (default: 'published_at') and a clicks column (default: 'clickCount').",
+            "2. Converts the date column to datetime and the clicks column to numeric.",
+            "3. Removes entries with invalid dates or click counts.",
+            "4. Groups the data by day.",
+            "5. Calculates the sum of clicks for each day.",
+            "6. Plots the daily total clicks as a line graph over time."
+        ]
+    },
+    "impressions_over_time": {
+        "title": "Impressions Over Time",
+        "description": (
+            "This chart displays the total number of impressions your posts received, aggregated daily. "
+            "Impressions represent the total number of times your content was displayed, regardless of whether it was clicked."
+        ),
+        "calculation_steps": [
+            "1. Takes the posts dataset with a date column (default: 'published_at') and an impressions column (default: 'impressionCount').",
+            "2. Converts the date column to datetime and the impressions column to numeric.",
+            "3. Removes entries with invalid dates or impression counts.",
+            "4. Groups the data by day.",
+            "5. Calculates the sum of impressions for each day.",
+            "6. Plots the daily total impressions as a line graph over time."
+        ]
+    },
+    "likes_over_time": {
+        "title": "Reactions (Likes) Over Time",
+        "description": (
+            "This chart tracks the total number of likes (or reactions) your posts received, aggregated daily. "
+            "It's a key indicator of content resonance and audience appreciation."
+        ),
+        "calculation_steps": [
+            "1. Takes the posts dataset with a date column (default: 'published_at') and a likes column (default: 'likeCount').",
+            "2. Converts the date column to datetime and the likes column to numeric.",
+            "3. Removes entries with invalid dates or like counts.",
+            "4. Groups the data by day.",
+            "5. Calculates the sum of likes for each day.",
+            "6. Plots the daily total likes as a line graph over time."
+        ]
+    },
+    "clicks_over_time": { # Note: This reuses the reach_over_time logic
+        "title": "Clicks Over Time",
+        "description": (
+            "This chart shows the total number of clicks on your posts, aggregated daily. "
+            "It directly measures user interaction involving clicks on your content or links within it."
+        ),
+        "calculation_steps": [
+            "1. Takes the posts dataset with a date column (default: 'published_at') and a clicks column (default: 'clickCount').",
+            "2. Converts the date column to datetime and the clicks column to numeric.",
+            "3. Removes entries with invalid dates or click counts.",
+            "4. Groups the data by day.",
+            "5. Calculates the sum of clicks for each day.",
+            "6. Plots the daily total clicks as a line graph over time. (This plot uses the same calculation logic as 'Reach Over Time (Clicks)')."
+        ]
+    },
+    "shares_over_time": {
+        "title": "Shares Over Time",
+        "description": (
+            "This chart displays the total number of times your posts were shared, aggregated daily. "
+            "Shares are a strong indicator of content value and audience advocacy."
+        ),
+        "calculation_steps": [
+            "1. Takes the posts dataset with a date column (default: 'published_at') and a shares column (default: 'shareCount').",
+            "2. Converts the date column to datetime and the shares column to numeric.",
+            "3. Removes entries with invalid dates or share counts.",
+            "4. Groups the data by day.",
+            "5. Calculates the sum of shares for each day.",
+            "6. Plots the daily total shares as a line graph over time."
+        ]
+    },
+    "comments_over_time": {
+        "title": "Comments Over Time",
+        "description": (
+            "This chart tracks the total number of comments on your posts, aggregated daily. "
+            "Comments reflect audience engagement and conversation around your content."
+        ),
+        "calculation_steps": [
+            "1. Takes the posts dataset with a date column (default: 'published_at') and a comments column (default: 'commentCount').",
+            "2. Converts the date column to datetime and the comments column to numeric.",
+            "3. Removes entries with invalid dates or comment counts.",
+            "4. Groups the data by day.",
+            "5. Calculates the sum of comments for each day.",
+            "6. Plots the daily total comments as a line graph over time."
+        ]
+    },
+    "comments_sentiment_breakdown": {
+        "title": "Breakdown of Comments by Sentiment",
+        "description": (
+            "This pie chart shows the distribution of sentiments (e.g., positive, negative, neutral) expressed in the comments on your posts. "
+            "It helps in understanding audience reactions at a deeper level."
+        ),
+        "calculation_steps": [
+            "1. Takes the comments dataset (or posts dataset if comments have sentiment labels) and a sentiment column (default: 'comment_sentiment', with 'sentiment' as a fallback).",
+            "2. Ensures the sentiment column is treated as string data.",
+            "3. Counts the occurrences of each unique sentiment value.",
+            "4. Displays these counts as a pie chart, with each slice representing the percentage of a sentiment category in comments."
+        ]
+    },
+    "post_frequency": {
+        "title": "Post Frequency Over Time",
+        "description": (
+            "This chart visualizes how frequently posts are made, aggregated by a chosen period (Daily 'D', Weekly 'W', or Monthly 'M'). "
+            "It helps assess content scheduling and output rhythm. The aggregation period is determined by the 'resample_period' parameter."
+        ),
+        "calculation_steps": [
+            "1. Takes the posts dataset with a date column (default: 'published_at').",
+            "2. Converts the date column to datetime format.",
+            "3. Removes entries with invalid dates.",
+            "4. Groups posts by the specified 'resample_period' (e.g., 'D' for day, 'W' for week, 'M' for month).",
+            "5. Counts the number of posts within each period.",
+            "6. Displays the result as a line chart for daily frequency or a bar chart for weekly/monthly frequency."
+        ]
+    },
+    "content_format_breakdown": {
+        "title": "Breakdown of Content by Format",
+        "description": (
+            "This bar chart shows the distribution of your posts based on their media type or format (e.g., article, image, video). "
+            "It helps identify which content formats are most commonly used."
+        ),
+        "calculation_steps": [
+            "1. Takes the posts dataset and a format column (default: 'media_type').",
+            "2. Counts the occurrences of each unique media type.",
+            "3. Displays these counts as a bar chart, with each bar representing a media type and its height representing the number of posts."
+        ]
+    },
+    "content_topic_breakdown": {
+        "title": "Breakdown of Content by Topics",
+        "description": (
+            "This horizontal bar chart displays the most frequent topics associated with your posts, based on assigned labels (e.g., from 'li_eb_labels' column). "
+            "It shows the top N topics (default: 15) to highlight key themes in your content strategy."
+        ),
+        "calculation_steps": [
+            "1. Takes the posts dataset and a topics column (default: 'li_eb_labels') which may contain single labels or lists of labels.",
+            "2. Parses the topics column: if an entry is a string representation of a list, it's converted to a list; otherwise, it's treated as a single-item list. Empty or invalid entries are handled.",
+            "3. 'Explodes' the data so that each individual topic label from a post gets its own row.",
+            "4. Filters out any empty string labels that might have resulted from parsing.",
+            "5. Counts the occurrences of each unique topic.",
+            "6. Selects the top N most frequent topics (default N=15).",
+            "7. Displays these top topics and their counts as a horizontal bar chart."
+        ]
+    }
+}