Skip to content

user.md

Latest commit

 

History

History
288 lines (225 loc) · 8.93 KB

user.md

File metadata and controls

288 lines (225 loc) · 8.93 KB

FIFA 2025 Gradio Interface - User Guide

🎯 Purpose

This interface validates social media data for the FIFA Club World Cup 2025 Canary FPP study, analyzing Coca-Cola's digital marketing presence across Brazil, Mexico, and United States.

🚀 Getting Started

Step 1: Access the Interface

  1. Open your web browser
  2. Navigate to the provided URL (local, network, or public)
  3. Enter login credentials:
    • Username: fifa_research
    • Password: CanaryFPP2025!

Step 2: Prepare Your Data

  • File Format: Excel (.xlsx or .xls)
  • Sheet Name: coded data (preferred) or use default first sheet
  • Data Structure: Must follow Canary FPP Data Template 2025 v1

📁 Data Requirements

Required Columns

Your Excel file should include these columns (snake_case format):

id, date, month, time, media_type, social_platform, url, profile_name, 
username, fifa_content, caption_title, english_caption, sentiment, 
country, language, likes, comments, shares, views, engagement, 
marketing_tactic, message_framing, product_type, account_type, 
company, product_brand

Expected Values

Countries:

  • Brazil, Mexico, United States

Social Platforms:

  • Facebook, Instagram, Twitter/X, YouTube, TikTok

Marketing Tactics (11 categories):

  • Direct product advertising
  • Price promotion
  • Contest and competition
  • Events, occasions, and sponsorships
  • General PR
  • Corporate social responsibility
  • Brand extension
  • Non-brand extended product
  • Surrogate marketing
  • Community-based marketing
  • Cobranding

Message Framing (12 types):

  • Community celebrations
  • Entertainment/Fun
  • Environment eco-awareness
  • Glamorization
  • Health claims
  • Informational
  • Personal care and wellness
  • Product features
  • Social welfare
  • Passion and emotion
  • Socialisation/community
  • Athletic performance and physicality, aspiration

🔄 Processing Workflow

Step 1: Upload File

  1. Click "Select Excel File"
  2. Choose your data file from your computer
  3. File will be validated for format and structure

Step 2: Start Validation

  1. Click "🚀 Start FIFA 2025 Validation"
  2. Watch the progress bar (typically 1-3 minutes)
  3. Processing includes:
    • Column structure verification
    • Data quality assessment
    • Auto-correction application
    • Validation against study protocol

Step 3: Review Results

Navigate through the result tabs:

📈 Executive Summary

  • Before/after quality scores
  • Total records processed
  • Auto-corrections applied
  • Overall processing status

🔍 Validation Summary

  • Detailed compliance metrics
  • Column-by-column analysis
  • Missing/extra columns report

🛠️ Auto-Corrections

  • Complete log of changes made
  • Row-by-row correction details
  • Fuzzy matching results

📊 Visual Analytics

  • Interactive overview dashboard
  • Timeline analysis by country
  • Company & brand performance charts

Step 4: Download Report

  1. Click "📥 Download Comprehensive Report"
  2. Receive Excel file with multiple sheets:
    • processed_data - Your cleaned dataset
    • original_raw_data - Unmodified input
    • executive_summary - Quality metrics
    • changes_made - Auto-correction log
    • Additional validation sheets

🔧 Auto-Correction Features

What Gets Fixed Automatically

Fuzzy String Matching (96% threshold):

  • Marketing tactics typos → Correct categories
  • Message framing errors → Valid types
  • Product type mistakes → Proper classifications
  • Platform name variations → Standard names

Date Standardization:

  • Various formats → YYYY-MM-DD standard
  • Invalid dates → Flagged for review

Engagement Calculation:

  • Recalculated as: likes + comments + shares + views
  • Corrects mathematical errors automatically

Language Correction:

  • Brazil → Portuguese/English only
  • Mexico → Spanish/English only
  • United States → English/Spanish only

Column Standardization:

  • Mixed case → snake_case format
  • Spaces/hyphens → underscores
  • Per Data Template specification

📊 Understanding Quality Scores

Quality Score Calculation

  • Before Score: Percentage of valid rows in original data
  • After Score: Percentage of valid rows after corrections
  • Improvement: Difference between before and after scores

Quality Thresholds

  • 85%+ Quality Score: Ready for analysis
  • 70-84% Quality Score: Manual review recommended
  • <70% Quality Score: Significant issues, contact research team

What Affects Quality

  • Missing required fields
  • Invalid categorical values
  • Country-language mismatches
  • Incorrect engagement calculations
  • Invalid URLs or usernames
  • Wrong date formats

🎯 Best Practices

Before Upload

  1. Check File Format: Ensure .xlsx or .xls format
  2. Verify Sheet Name: Use 'coded data' if possible
  3. Review Columns: Match expected column names
  4. Sample First: Test with small file (100-500 rows)

During Processing

  1. Wait for Completion: Don't refresh browser during processing
  2. Monitor Progress: Watch progress bar and status messages
  3. Check for Errors: Review any error messages carefully

After Processing

  1. Review All Tabs: Check executive summary, corrections, and charts
  2. Verify Changes: Review auto-corrections log
  3. Download Report: Save comprehensive Excel report
  4. Submit Clean Data: Use 'processed_data' sheet for analysis

🔍 Troubleshooting

Common Upload Issues

"File format not supported"

  • Solution: Ensure file is .xlsx or .xls format
  • Convert CSV files to Excel before upload

"Sheet 'coded data' not found"

  • Solution: Rename your data sheet to 'coded data' (lowercase)
  • Or ensure data is in the first sheet

"Column structure mismatch"

  • Solution: Review column names against expected list
  • Use snake_case format (e.g., 'social_platform' not 'Social Platform')

Processing Errors

"Processing failed"

  • Check: File isn't corrupted or password-protected
  • Verify: Data contains expected columns
  • Ensure: File size is reasonable (<100MB)

"Low quality score"

  • Review: Auto-corrections log for issues
  • Check: Country-language compatibility
  • Verify: Required fields aren't empty

Network Issues

"Can't reach interface"

  • Check: Correct URL and port (default 7860)
  • Verify: Network connection
  • Try: Different browser or incognito mode

"Login failed"

  • Username: fifa_research (lowercase)
  • Password: CanaryFPP2025! (exact case)

📈 Interpreting Charts

Overview Dashboard

  • Country Distribution: Pie chart of post distribution
  • Social Platforms: Bar chart of platform usage
  • Marketing Tactics: Distribution of promotional strategies
  • Message Framing: Types of content messaging
  • Product Types: Coca-Cola product categories
  • Account Types: Social media account classifications

Timeline Analysis

  • Daily Posts: Posting patterns during FIFA Club World Cup
  • Country Trends: Geographic posting behaviors
  • Interactive: Hover for details, zoom to specific periods

Company & Brand Analysis

  • Company Distribution: Brand presence analysis
  • Product Brands: Specific product marketing
  • Geographic Breakdown: Brand performance by country

💡 Tips for Success

Data Preparation

  1. Clean Column Names: Use standard naming before upload
  2. Check Required Fields: Ensure critical columns have data
  3. Validate Dates: Use consistent date format
  4. Review Categories: Match expected values where possible

Quality Improvement

  1. Start Small: Test with subset before processing full dataset
  2. Review Corrections: Understand what gets changed automatically
  3. Manual Review: Check high-impact corrections manually
  4. Iterative Process: Re-upload with fixes if needed

Team Collaboration

  1. Share URLs: Use network/public URL for team access
  2. Standard Process: Establish consistent workflow
  3. Documentation: Keep log of processing dates and versions
  4. Quality Control: Have multiple team members review results

📞 Getting Help

Technical Support

  • Interface issues, login problems, upload errors
  • Contact: [Your technical contact]

Data Validation Questions

  • Category classifications, auto-corrections, quality scores
  • Reference: Canary FPP Study Protocol documentation
  • Contact: [Your research team contact]

Study Protocol Questions

  • Methodology, validation standards, reporting requirements
  • Reference: Data Template and Codebook 2025 v1
  • Contact: [Principal investigator contact]

📚 Additional Resources

  • Canary FPP Study Protocol: [Link to documentation]
  • Data Template 2025 v1: [Link to template]
  • GitHub Repository: [Link to code repository]
  • Technical Documentation: [Link to detailed docs]

Remember: This tool is designed to improve data quality, not replace careful data collection. Always review auto-corrections and maintain awareness of your data's context and meaning.