Help & Documentation

1. Quick Start Guide

1. Upload File: Upload a CSV, Excel (.xlsx), TXT or PDF file.
2. Select Column: Choose the column containing your text data.
3. Configure Preprocessing: Set stopword removal, minimum word length, etc.
4. Run Analysis: Click the "Start Analysis" button.
5. View Results: Review TF, TF-IDF, network centrality, topic modeling, and sentiment analysis results.
6. Download: Download results as an Excel file.

2. Supported File Formats

3. Preprocessing Pipeline

EmoFEAT transforms raw text into analysis-ready form through an 8-step preprocessing pipeline. Token count changes at each step are recorded in the preprocessing report, ensuring research reproducibility.

3.1 Text Cleaning

Removes noise such as URLs, HTML tags, email addresses, special characters, and numbers using regex-based filtering.

3.2 Tokenization

Splits text into meaningful units (tokens).

• Korean: KoNLPy morphological analyzer (Okt or Komoran)
• English: NLTK word_tokenize

3.3 PMI Collocation Detection

Uses Pointwise Mutual Information (PMI) to detect strongly associated word pairs (collocations). Word pairs whose PMI exceeds the configured threshold (default 5.0) are treated as strong collocational associations and combined as compound terms. Note that PMI is an association-strength measure, not a statistical significance test.

3.4 Stopword Removal — a four-tier system

Instead of applying one flat list, EmoFEAT separates stopwords into four tiers by the reason they are removed, and each tier can be switched on or off independently. Different justifications should lead to different decisions depending on the research question. The results page reports what each tier removed, so the choice can be stated precisely in a methods section.

Keep-negation option. The default list places not/never/no in T1, following information-retrieval practice — but this is risky for emotion work. In “I do not like this,” removing not leaves like and flips the polarity. Enabling this option preserves negation. Recommended whenever emotion or stance is being measured. (Pang & Lee 2008)

Doesn't TF-IDF handle this automatically? Only partly. IDF lowers the weight of high-df terms but never zeroes them — when df(t)=N, idf(t) still equals 1. And because each document vector is L2-normalized, function words contributing to the vector length dilute the weights of the genuine topic terms.

3.5 Lemmatization

Extracts base forms (lemmas) using WordNet to unify different morphological forms of the same concept.

Example: running, ran, runs -> run

3.6 Search Keyword Removal

Automatically detects and removes search query keywords used during data collection, improving the validity of TF results.

3.7 Final Filtering

Applies final filtering based on minimum word length, minimum frequency, and other criteria.

3.8 Report Generation

Records token count changes at each step and generates a preprocessing report.

4. BERT & GoEmotions Theory

This section explains the architecture of BERT and RoBERTa (the foundation models for RoBERTa GoEmotions analysis) and the GoEmotions dataset used for fine-tuning.

4.1 BERT (Bidirectional Encoder Representations from Transformers)

BERT (Devlin et al., 2019) is a pre-trained language model developed by Google that uses only the Transformer encoder architecture. Its key innovation is bidirectional context learning. Unlike previous language models that captured context only left-to-right (or right-to-left), BERT uses Masked Language Modeling (MLM) to learn context from all directions simultaneously.

4.2 RoBERTa (Robustly Optimized BERT Approach)

RoBERTa (Liu et al., 2019) is a model optimized by Facebook AI Research through systematic re-examination of BERT's training strategies. While the architecture is identical to BERT, significant performance improvements were achieved through the following training methodology enhancements.

4.3 RoBERTa GoEmotions & GoEmotions Dataset

The RoBERTa GoEmotions classifier fine-tunes the RoBERTa-base model on Google Research's GoEmotions dataset (Demszky et al., 2020). GoEmotions is a large-scale emotion dataset with 58,009 Reddit comments labeled across 28 emotion categories by 82 annotators.

The 28 emotion categories in the GoEmotions dataset go beyond Ekman's (1992) six basic emotions, designed to capture fine-grained emotional expressions in modern communication. They consist of 12 positive emotions (admiration, amusement, approval, etc.), 11 negative emotions (anger, annoyance, disappointment, etc.), and 5 ambiguous emotions (confusion, curiosity, surprise, etc.).

4.4 Deep Learning vs Lexicon-Based Sentiment Analysis

EmoFEAT provides two sentiment analysis methodologies: lexicon-based analysis using the NRC Emotion Lexicon (Mohammad & Turney, 2013) and deep learning-based analysis using RoBERTa GoEmotions. The characteristics of each are compared below.

4.5 Limitations and Considerations

• English-Only Model: The RoBERTa GoEmotions model was trained on English Reddit data, so accuracy may be significantly lower for non-English text.
• Domain Bias: Optimized for informal Reddit expressions; sensitivity may differ for formal texts such as academic papers or news articles.
• Token Length Limit: Maximum 512 BPE tokens can be processed; longer texts will be truncated.
• Multi-label vs Single-label: The GoEmotions dataset is originally a multi-label dataset, but EmoFEAT uses Softmax-based single-label (highest probability emotion) classification.
• Need for Statistical Verification: Emotion classification results alone cannot infer causality. Advanced analyses (correlation, ANOVA, logistic regression) are recommended for statistical validation.

5. RoBERTa GoEmotions Analysis

RoBERTa GoEmotions analysis uses a RoBERTa model fine-tuned on Google Research's GoEmotions dataset (58,000 Reddit comments), classifying text into 28 fine-grained emotions beyond Ekman's 6 basic emotions.

5.1 Model Overview

5.2 28 Emotion Taxonomy

The 28 emotions are classified into 3 high-level categories based on the GoEmotions taxonomy:

5.3 Analysis Process

1. Text Input: Upload CSV/Excel file and select the text column for analysis
2. BPE Tokenization: RoBERTa tokenizer splits text into subword tokens
3. Contextual Embedding: 12-layer Transformer encoder generates bidirectional context vectors (768-dim)
4. Emotion Classification: Softmax classifier produces probability distribution over 28 emotions
5. Category Analysis: Aggregate probabilities by positive/negative/ambiguous categories
6. Correlation Analysis: Pearson correlation-based 28x28 emotion correlation matrix
7. Statistics: Mean, standard deviation, median, min/max per emotion
8. Visualization Report: 7 interactive Plotly.js charts and Excel report generation

5.4 Results Page Structure

5.5 How to Use

1. Click "GoEmotions Analysis" from the homepage or navigation bar.
2. Drag and drop a CSV or Excel file, or click the upload button.
3. Select the text column and click "Start Analysis".
4. Once analysis is complete, you will be redirected to the results page.
5. Download chart images using the download buttons, or download the Excel report.

6. Advanced SCIE Analysis

After the base RoBERTa GoEmotions analysis is complete, advanced statistical analyses (rating-emotion correlation, clustering, entropy, emotion transitions, predictors, temporal trends) plus a PPMI-based emotion co-occurrence network analysis are performed. Each provides SCIE publication-level statistical validation.

6.1 Rating-Emotion Correlation

When the data includes a rating column, this analysis examines the statistical relationship between ratings and 28 emotion probabilities.

6.2 Emotion Clustering

Uses K-Means algorithm to classify documents into groups (clusters) with similar emotion patterns based on 28 emotion probability vectors.

• Optimal K Search: Automatically selects optimal K from 2-10 clusters based on Silhouette Score.
• t-SNE Visualization: Reduces high-dimensional (28-dim) emotion vectors to 2D for visual cluster representation.
• Cluster Profiles: Provides representative emotions and document counts for each cluster.

6.3 Model-Human Validation (Cohen's κ / Krippendorff's α)

On the dedicated Validate page (/en/validate), you can evaluate the reliability and validity of RoBERTa GoEmotions classifications against a human-coded sample.

• Cohen's Kappa (κ): Measures agreement between model classifications and human coder judgments, correcting for chance agreement.
• Krippendorff's Alpha (α): Assesses inter-coder reliability on a nominal scale; applicable to multiple coders and missing data.
• Input Format: Upload a sample file containing the model's analysis results with added human-coded emotion label columns.

For the detailed input format, bootstrap confidence intervals, confusion matrix, and the built-in human coding tool (Annotate), see Section 8: Measurement Validation & Human Coding.

6.4 Emotion Entropy Analysis

Uses Shannon Entropy to measure how uncertain (diverse) the emotion distribution is for each document.

• High Entropy: Emotions are evenly distributed -- complex or ambiguous text
• Low Entropy: One emotion is dominant -- clear emotional expression
• Mann-Whitney U Test: Tests whether entropy differences between rating groups are statistically significant.

6.5 Emotion Transition Analysis

Analyzes emotion change patterns by document order (time or index).

• Stacked Area Chart: Visualizes time-series changes in positive/negative/ambiguous emotion ratios.
• Trend Lines: Displays emotion trends using Moving Average.
• Segment Analysis: Divides the data into segments to identify directional emotion changes.

6.6 Emotion Predictor Analysis

Uses Binary Logistic Regression to identify key factors that predict dominant emotions.

• Dependent Variable: Dominant emotion presence (positive vs non-positive, or specific emotion vs others)
• Independent Variables: 28 emotion probability values
• Odds Ratio: The change in probability of dominant emotion per unit increase in each emotion probability
• 95% Confidence Interval: Statistical confidence range of the Odds Ratio

6.7 Requirements Summary

7. Emotion Trajectory & Event Analysis

If a date column was selected when uploading a GoEmotions analysis, the results page offers emotion trajectory and event analysis. Documents are automatically binned by day, week, or month depending on the time span of the data, and per-emotion time-series trajectories are visualized.

7.1 Interrupted Time Series (ITS)

When you enter an event date (e.g., a policy announcement or incident date), segmented regression estimates the change in emotion level and slope before vs. after the event. Estimation uses WLS weighted by per-bin document counts with Newey-West HAC standard errors (autocorrelation-robust), and per-emotion p-values are Benjamini-Hochberg FDR-corrected for multiple comparisons.

7.2 Changepoint Detection

Even without a known event date, the PELT algorithm (via the ruptures library, when installed) automatically detects statistically meaningful changepoints in the emotion trajectory. When ruptures is not installed, a built-in binary segmentation fallback is used.

8. Measurement Validation & Human Coding

Journal reviewers often ask for evidence that automated classifications agree with human judgment. EmoFEAT includes a built-in human coding tool (Annotate) and a model-human agreement validation tool (Validate) that support this workflow end to end.

8.1 Measurement Validation (Validate — /en/validate)

Upload the Document Results export of a GoEmotions analysis with added human coder label column(s) (human_label; a second coder uses human_label_2) to compute:

• Cohen's Kappa (κ): Model-human agreement corrected for chance, reported with a bootstrap 95% confidence interval (B=1,000, seed=42).
• Krippendorff's Alpha (α): Nominal-scale reliability; when two or more coders are present, intercoder α is also computed separately.
• Per-Emotion Confusion Matrix: Visualizes which emotions the model and human coders disagree on.
• Landis & Koch (1977) Bands: κ is automatically interpreted as Slight/Fair/Moderate/Substantial/Almost Perfect (see the table in Section 6.3).

All results can be downloaded as an Excel report that includes the reproducibility manifest.

8.2 Human Coding Tool (Annotate — /en/annotate)

You can build the human-coded validation sample directly inside EmoFEAT. To prevent coder bias, the labeling screen shows text only — the model's emotion scores are hidden (coder blinding). Sampling is seeded random selection (default N=200, seed=42), so a second coder using the same file and seed reproduces the identical sample and labels it as human_label_2.

After labeling, export a CSV containing the human_label column, or hand it off to the Validate page with one click to run the agreement analysis immediately.

9. Reproducibility & Methods Draft

9.1 Reproducibility Manifest

Every analysis task (GoEmotions, Compare Groups, Validation, NLP) automatically records a JSON manifest of its run configuration and environment: EmoFEAT version, model name, thresholds, bootstrap iterations (B), random seed, preprocessing options, key package versions, platform, and git commit hash.

Download the JSON via the button on the results page; it is also embedded in the Excel report as a "Reproducibility Manifest" sheet. When reviewers ask "which model, which version, which settings produced these numbers," the manifest answers exactly — enabling precise reproduction and verification of the computational environment and settings.

9.2 Methods Draft Generator

The GoEmotions and NLP results pages auto-assemble a draft Methods section for your manuscript. The draft describes only the analyses that were actually run (omitting sentences for analyses that were not), accurately frames emotion scores as model confidence scores, and includes a placeholder paragraph for human-coder validation results plus software version details.

Both English and Korean drafts are provided, with a copy button for pasting directly into your manuscript. The draft is a starting point — always review and adapt it to your research context.

10. Compare Groups & Power Diagnostics

The Compare Groups page (/en/compare) statistically compares the 28 emotion intensities between GoEmotions result files (or by a grouping column). It reports Hedges' g effect sizes (small-sample-adjusted Cohen's d), bootstrap 95% confidence intervals of mean differences, and FDR-corrected p-values.

10.1 Power & Sample-Size Diagnostics

The Compare results page includes a design-sensitivity card for the achieved sample sizes: the minimum detectable effect size (MDES) at 80% and 90% power, plus power curves for conventional effect sizes (g = 0.1/0.2/0.35/0.5/0.8).

11. Network Compare (QAP/MRQAP)

The Network Compare page (/en/netcompare) compares discourse network structures across corpora — testing similarity in structure (what co-occurs with what), not distribution (how much of each word or emotion appears). It implements the four-stage protocol of Suh (2026, Systems).

11.1 How to use

① Upload 2–5 corpora (CSV/XLSX/TXT/PDF, ≥30 documents each — 300+ recommended). The first is the baseline (Y); the others are predictors (X). A research-model diagram draws itself as you configure. ② Parameter defaults match the paper's design (top-K, top-L, permutations). ③ One run produces QAP correlations → Cohen's q → MRQAP (with 2+ predictors) → jackknife, node bootstrap and residual analysis.

11.2 Reading the results

QAP r: structural similarity under node-permutation testing. With thousands of dyads p-values become trivially small, so the magnitude of change between alignments is judged with Cohen's q (|q| < 0.1 negligible / 0.1–0.3 small / 0.3–0.5 medium / ≥ 0.5 large; Cohen, 1988). MRQAP β is each predictor's unique contribution after removing overlap — a negative β may be a suppression effect rather than opposition; check the jackknife table first. Arrows in the model diagram denote predictive association, not causation.

11.3 Outputs

Research-model path diagram, QAP heatmap, bootstrap forest plot and pruning-sensitivity chart (300 DPI PNG/SVG); an EN/KO Methods draft describing only the analyses actually run (tokenizer, permutations and seeds recorded); and a multi-sheet Excel report with the reproducibility manifest. Korean corpora are analyzed directly with Kiwi (kiwipiepy) morphological analysis — no translation involved.

12. Analysis Features

11.1 TF (Term Frequency)

Calculates the total number of times a word appears in the entire corpus. High-frequency words may represent central topics of the text collection.

11.2 TF-IDF (Term Frequency-Inverse Document Frequency)

Multiplies term frequency (TF) by inverse document frequency (IDF) to reduce the weight of common words across all documents and increase the importance of words that appear frequently in specific documents.

11.3 Co-occurrence Matrix

Represents the frequency of word pairs that appear together within the same document (or window) as a matrix. This serves as the foundation for semantic network analysis.

11.4 Network Centrality

Measures the structural importance of each word in the co-occurrence network.

11.5 Semantic Network Communities (Louvain)

The Louvain algorithm (Blondel et al., 2008) detects word communities (semantic clusters) in the co-occurrence network and reports the modularity (Q) score. This is the standard community-detection counterpart to the CONCOR clustering widely used in Korean media/communication research. Results are also included in the "Word Communities" Excel sheet.

11.6 Topic Modeling (LDA)

Uses Latent Dirichlet Allocation (LDA) to automatically extract latent topics from a document collection. You can set the number of topics (k) manually, or enable the auto-optimize option to scan candidate k values by c_v coherence, automatically select the best k, and display a per-k coherence scan chart. An interactive pyLDAvis visualization (when installed) lets you explore inter-topic distances and top terms per topic.

11.7 Sentiment Analysis (NRC)

Classifies text emotions using the 8 Plutchik emotion categories of the NRC Emotion Lexicon (Mohammad & Turney, 2013) — Joy, Sadness, Anger, Fear, Disgust, Surprise, Trust, and Anticipation — plus positive/negative polarity. By default a built-in NRC-style keyword lexicon (~1,400 entries) is used; the full NRC Emotion Lexicon is used automatically when installed at modules/data/NRC-Emotion-Lexicon.txt.

11.8 Topic × Emotion Cross Profile

Computes a per-topic emotion profile showing which emotions each topic is associated with. If the uploaded file contains the 28 GoEmotions emotion columns (i.e., an EmoFEAT GoEmotions results export), a topic-proportion (θ)-weighted GoEmotions 28-emotion profile is computed; otherwise the analysis falls back to the NRC 8-emotion lexicon. Results are included in the "Topic-Emotion Profile" Excel sheet.

11.9 Topic Trends Over Time (Date Column)

When a date column is selected in the analysis options, per-topic share over time (topic trends) is visualized. Results are included in the "Topic Trends" Excel sheet.

11.10 Mixed-Language Corpora & Korean Tokenization

For corpora mixing Korean and English, the language of each document is detected individually and routed to its own language pipeline, so minority-language documents are preserved rather than dropped. For Korean, single-character nouns (e.g., "물", "돈", "집") are preserved: unless you explicitly set a minimum word length, the Korean default is automatically 1 (English default: 2).

13. Results Interpretation

12.1 TF/TF-IDF Interpretation

12.2 Centrality Interpretation

The bands below apply to Degree Centrality only (normalized to 0-1). Compare Closeness, Betweenness, and PageRank by rank rather than absolute value. Shortest-path metrics (closeness, betweenness) are computed on distance = 1 / co-occurrence count (Opsahl et al., 2010).

12.3 Topic Coherence Interpretation

14. YouTube Comments Collector

The Comments Collector allows you to gather YouTube video comments at scale for use in GoEmotions emotion analysis or NLP text analysis. Two collection engines are available depending on your dataset size.

Overview

Simply enter a YouTube video URL, choose your collection engine and options, and export the results to CSV, Excel, or PDF. Collected data can be directly used as input for GoEmotions or NLP Text Analysis.

How to Use (Step-by-Step)

Step 1. Enter YouTube URL
Paste any valid YouTube video URL or video ID into the input field. Click "Fetch Video Info" to preview the video title, total comment count, and view count before starting collection.

Step 2. Select Collection Engine
• YouTube Data API v3 — Recommended for datasets under 10,000 comments. Fast, stable, and uses the official Google API.
• yt-dlp Engine — For datasets over 10,000 comments. Slower but can access the full comment dataset without API limits.

Step 3. Configure Options
• Max Comments: Set the maximum number of comments to collect. Leave blank to collect all available comments.
• Language Filter: Filter by language (All / English only / Korean only).
• Include Replies: Toggle to include or exclude reply comments.
• Sort Order: Collect by Relevance (most liked first) or Time (newest first).

Step 4. Start Collection
Click "Start Collection" and monitor progress in the log window. You can stop collection at any time with the "Stop Collection" button. Partial results collected before stopping can still be downloaded.

Step 5. Download Results
Choose your export format:
• CSV (.csv) — Recommended for Python/R analysis and data archiving
• Excel (.xlsx) — For manual inspection and filtering
• PDF (.pdf) — Summary report with collection metadata

One-Stop Analysis Pipeline (Collect → Clean → GoEmotions)

From the analysis card on the completion screen, you can hand collected comments directly to GoEmotions emotion analysis — no file download/re-upload needed. An optional preprocessing step cleans the comments first:

• Deduplication: Removes exact duplicates and normalized near-duplicates (ignoring whitespace/punctuation/case)
• Bot/Spam Filter: Heuristics for URL+promotional keywords, phone numbers, messenger-ID solicitation, and repeated identical text from the same author (3+ times)
• Emoji Cleanup: Strips emoji and collapses whitespace (emoji-only comments are filtered out)
• Reply Exclusion: Option to exclude short, context-dependent replies (is_reply)

Counts removed at each step are shown in a preprocessing report you can reuse verbatim when describing data cleaning in a paper. If the cleaned sample is Korean-dominant (roughly 30%+ Korean documents), a warning is shown — the GoEmotions model is optimized for English.

Known Limitations

Reply comments (is_reply: true) contain short, context-dependent text (e.g., "same", "lol") and may reduce analysis quality. For emotion analysis, filtering to top-level comments only is recommended.

For Academic Research

15. Academic Citation

When using EmoFEAT in your research, please cite as follows:

Software Citation (APA 7th)

Software Citation (Chicago Style)

Methodology Description Example

16. FAQ

Q: How do I use the results in UCINET/Netdraw?

A: Import the "Co-occurrence Matrix" sheet from the Excel results file into UCINET. The format is compatible with DL format.

Q: Korean analysis is not working.

A: Korean is handled differently per feature. ① NLP Text Analysis uses KoNLPy (Okt/Komoran) morphological analysis, which requires a Java runtime (KoNLPy documentation) — without Java it falls back to a built-in basic extractor, so analysis still runs but with lower morphological quality. ② Network Compare (QAP) uses Kiwi (kiwipiepy) and needs no Java — if it is missing you get an explicit error, resolved with pip install kiwipiepy. ③ GoEmotions emotion analysis translates Korean documents locally (opus-mt-ko-en) before analysis — make sure the "Translate Korean" option is enabled.

Q: How do I determine the number of topics?

A: The number of topics (k) is user-configurable in the analysis options (2-20, default 5). Alternatively, enable the auto-optimize option to scan candidate k values by c_v coherence and select the best k automatically, with a per-k coherence chart. When setting k manually, start with the square root of the document count or 5-10 topics, then adjust based on the c_v Coherence Score.

Q: The server freezes during analysis.

A: This may be due to insufficient memory. Try reducing the number of documents or increasing server memory.

Q: What is the difference between RoBERTa GoEmotions and NRC sentiment analysis?

A: NRC sentiment analysis uses a lexicon-based approach to classify the 8 Plutchik emotion categories of the NRC Emotion Lexicon (Mohammad & Turney) plus positive/negative polarity, while RoBERTa GoEmotions uses deep learning (Transformer) to classify 28 fine-grained emotions. RoBERTa GoEmotions is more sophisticated but optimized for English text.

Q: How long does RoBERTa GoEmotions analysis take?

A: On CPU (without GPU), approximately 0.5-1 second per document. For 1,000 documents, expect about 8-15 minutes. GPU significantly reduces processing time.

Q: Can I analyze Korean text with RoBERTa GoEmotions?

A: The model was trained on English data and is optimized for English text. Korean text can be input but accuracy may be lower. English text is recommended when possible.