formulas.py

# 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."
        ]
    }
}