validmind 2.5.24__py3-none-any.whl → 2.6.7__py3-none-any.whl

validmind/tests/data_validation/nlp/CommonWords.py

@@ -2,22 +2,19 @@
 # See the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
-"""
-Metrics functions for any Pandas-compatible datasets
-"""
-
 from collections import Counter
-from dataclasses import dataclass
 
-import matplotlib.pyplot as plt
 import nltk
+import plotly.graph_objects as go
 from nltk.corpus import stopwords
 
-from ....vm_models import Figure, Metric, VMDataset
+from validmind import tags, tasks
+from validmind.vm_models import VMDataset
 
 
-@dataclass
-class CommonWords(Metric):
+@tags("nlp", "text_data", "visualization", "frequency_analysis")
+@tasks("text_classification", "text_summarization")
+def CommonWords(dataset: VMDataset):
     """
     Assesses the most frequent non-stopwords in a text column for identifying prevalent language patterns.
 
@@ -31,8 +28,8 @@ class CommonWords(Metric):
 
     The test methodology involves splitting the specified text column's entries into words, collating them into a
     corpus, and then counting the frequency of each word using the Counter. The forty most frequently occurring
-    non-stopwords are then visualized in a bar chart, where the x-axis represents the words, and the y-axis indicates
-    their frequency of occurrence.
+    non-stopwords are then visualized in an interactive bar chart using Plotly, where the x-axis represents the words,
+    and the y-axis indicates their frequency of occurrence.
 
     ### Signs of High Risk
 
@@ -46,7 +43,7 @@ class CommonWords(Metric):
     - The metric provides clear insights into the language features – specifically word frequency – of unstructured
     text data.
     - It can reveal prominent vocabulary and language patterns, which prove vital for feature extraction in NLP tasks.
-    - The visualization helps in quickly capturing the patterns and understanding the data intuitively.
+    - The interactive visualization helps in quickly capturing the patterns and understanding the data intuitively.
 
     ### Limitations
 
@@ -58,48 +55,43 @@ class CommonWords(Metric):
     applicability.
     """
 
-    name = "common_words"
-    required_inputs = ["dataset"]
-    tasks = ["text_classification", "text_summarization"]
-    tags = ["nlp", "text_data", "visualization", "frequency_analysis"]
-
-    def run(self):
-        # Can only run this test if we have a Dataset object
-        if not isinstance(self.inputs.dataset, VMDataset):
-            raise ValueError("CommonWords requires a validmind Dataset object")
-
-        def create_corpus(df, text_column):
-            corpus = []
-            for x in df[text_column].str.split():
-                for i in x:
-                    corpus.append(i)
-            return corpus
-
-        text_column = self.inputs.dataset.text_column
-        corpus = create_corpus(self.inputs.dataset.df, text_column=text_column)
-
-        counter = Counter(corpus)
-        most = counter.most_common()
-        x = []
-        y = []
-        nltk.download("stopwords")
-        stop = set(stopwords.words("english"))
-        for word, count in most[:40]:
-            if word not in stop:
-                x.append(word)
-                y.append(count)
-        fig = plt.figure()
-        plt.bar(x, y, color="#17C37B")
-        plt.xticks(rotation=90)
-        # Do this if you want to prevent the figure from being displayed
-        plt.close("all")
-
-        return self.cache_results(
-            figures=[
-                Figure(
-                    for_object=self,
-                    key=self.key,
-                    figure=fig,
-                )
-            ]
-        )
+    # Check text column
+    if not dataset.text_column:
+        raise ValueError("Please set text_column name in the Validmind Dataset object")
+
+    nltk.download("stopwords", quiet=True)
+
+    counter = Counter(
+        [word for x in dataset.df[dataset.text_column].str.split() for word in x]
+    )
+    most = counter.most_common()
+
+    def create_corpus(df, text_column):
+        corpus = []
+        for x in df[text_column].str.split():
+            for i in x:
+                corpus.append(i)
+        return corpus
+
+    corpus = create_corpus(dataset.df, text_column=dataset.text_column)
+    counter = Counter(corpus)
+    most = counter.most_common()
+
+    x = []
+    y = []
+
+    stop = set(stopwords.words("english"))
+    for word, count in most[:40]:
+        if word not in stop:
+            x.append(word)
+            y.append(count)
+
+    fig = go.Figure(data=[go.Bar(x=x, y=y, marker_color="#17C37B")])
+    fig.update_layout(
+        title="Most Common Words",
+        xaxis_title="Words",
+        yaxis_title="Frequency",
+        xaxis_tickangle=-45,
+    )
+
+    return fig

validmind/tests/data_validation/nlp/Hashtags.py

@@ -2,20 +2,18 @@
 # See the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
-"""
-Threshold based tests
-"""
-
 import re
-from dataclasses import dataclass
 
 import plotly.graph_objects as go
 
-from validmind.vm_models import Figure, ThresholdTest, VMDataset
+from validmind import tags, tasks
+from validmind.errors import SkipTestError
+from validmind.vm_models import VMDataset
 
 
-@dataclass
-class Hashtags(ThresholdTest):
+@tags("nlp", "text_data", "visualization", "frequency_analysis")
+@tasks("text_classification", "text_summarization")
+def Hashtags(dataset: VMDataset, top_hashtags: int = 25):
     """
     Assesses hashtag frequency in a text column, highlighting usage trends and potential dataset bias or spam.
 
@@ -58,44 +56,24 @@ class Hashtags(ThresholdTest):
     - Does not provide context or sentiment associated with the hashtags, so the information provided may have limited
     utility on its own.
     """
-
-    name = "hashtags"
-    required_inputs = ["dataset"]
-    default_params = {"top_hashtags": 25}
-    tasks = ["text_classification", "text_summarization"]
-    tags = ["nlp", "text_data", "visualization", "frequency_analysis"]
-
-    def run(self):
-        # Can only run this test if we have a Dataset object
-        if not isinstance(self.inputs.dataset, VMDataset):
-            raise ValueError("Hashtags requires a validmind Dataset object")
-
-        text_column = self.inputs.dataset.text_column
-
-        def find_hash(text):
-            return re.findall(r"(?<=#)\w+", str(text))
-
-        # Extract hashtags from the text column and count occurrences
-        hashtags = self.inputs.dataset.df[text_column].apply(find_hash).explode()
-        temp = hashtags.value_counts().head(self.params["top_hashtags"])
-
-        print(f"temp: {temp}")
-
-        figures = []
-        if not temp.empty:
-            fig = go.Figure(data=[go.Bar(x=temp.index, y=temp.values)])
-            fig.update_layout(
-                title="Top Hashtags",
-                xaxis_title="Hashtag",
-                yaxis_title="Count",
-                xaxis_tickangle=-45,
-            )
-            figures.append(
-                Figure(
-                    for_object=self,
-                    key=self.name,
-                    figure=fig,
-                )
-            )
-
-        return self.cache_results([], passed=True, figures=figures)
+    hashtags = (
+        dataset.df[dataset.text_column]
+        .apply(lambda x: re.findall(r"(?<=#)\w+", str(x)))
+        .explode()
+    )
+    top_hashtag_counts = hashtags.value_counts().head(top_hashtags)
+
+    if top_hashtag_counts.empty:
+        raise SkipTestError("No hashtags found in the dataset")
+
+    fig = go.Figure(
+        data=[go.Bar(x=top_hashtag_counts.index, y=top_hashtag_counts.values)]
+    )
+    fig.update_layout(
+        title="Top Hashtags",
+        xaxis_title="Hashtag",
+        yaxis_title="Count",
+        xaxis_tickangle=-45,
+    )
+
+    return fig

validmind/tests/data_validation/nlp/LanguageDetection.py

@@ -2,11 +2,6 @@
 # See the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
-"""
-Metrics functions for any Pandas-compatible datasets
-"""
-
-
 import plotly.express as px
 from langdetect import LangDetectException, detect
 
@@ -55,24 +50,23 @@ def LanguageDetection(dataset):
     - The test returns "Unknown" for entries where language detection fails, which might mask underlying issues with
     certain languages or text formats.
     """
-    # check text column
     if not dataset.text_column:
-        raise ValueError("Please set text_column name in the Validmind Dataset object")
+        raise ValueError(
+            "Please set the `text_column` option when "
+            "initializing your Dataset object to use this test"
+        )
 
-    # Function to detect language
     def detect_language(text):
         try:
             return detect(text)
         except LangDetectException:
-            return "Unknown"  # Return 'Unknown' if language detection fails
+            return "Unknown"
 
-    # Applying the language detection function to each text entry
     languages = dataset.df[dataset.text_column].apply(detect_language)
-    fig = px.histogram(
+
+    return px.histogram(
         languages,
         x=languages,
         title="Language Distribution",
         labels={"x": "Language Codes"},
     )
-
-    return fig

validmind/tests/data_validation/nlp/Mentions.py

@@ -2,21 +2,19 @@
 # See the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
-"""
-Threshold based tests
-"""
 import re
-from dataclasses import dataclass
 
-import matplotlib.pyplot as plt
 import pandas as pd
 import plotly.express as px
 
-from validmind.vm_models import Figure, ThresholdTest, VMDataset
+from validmind import tags, tasks
+from validmind.errors import SkipTestError
+from validmind.vm_models import VMDataset
 
 
-@dataclass
-class Mentions(ThresholdTest):
+@tags("nlp", "text_data", "visualization", "frequency_analysis")
+@tasks("text_classification", "text_summarization")
+def Mentions(dataset: VMDataset, top_mentions: int = 25):
     """
     Calculates and visualizes frequencies of '@' prefixed mentions in a text-based dataset for NLP model analysis.
 
@@ -57,58 +55,29 @@ class Mentions(ThresholdTest):
     - It does not provide insights on less frequently occurring data or outliers, which means potentially significant
     patterns could be overlooked.
     """
-
-    name = "mentions"
-
-    required_inputs = ["dataset"]
-    default_params = {"top_mentions": 25}
-    tasks = ["text_classification", "text_summarization"]
-    tags = ["nlp", "text_data", "visualization", "frequency_analysis"]
-
-    def run(self):
-        # Can only run this test if we have a Dataset object
-        if not isinstance(self.inputs.dataset, VMDataset):
-            raise ValueError("Mentions requires a validmind Dataset object")
-
-        text_column = self.inputs.dataset.text_column
-
-        def mentions(text):
-            line = re.findall(r"(?<=@)\w+", text)
-            return " ".join(line)
-
-        b = (
-            self.inputs.dataset.df[text_column]
-            .apply(lambda x: mentions(x))
-            .value_counts()[:][1 : self.params["top_mentions"]]
-            .index.tolist()
-        )
-        a = (
-            self.inputs.dataset.df[text_column]
-            .apply(lambda x: mentions(x))
-            .value_counts()[:][1 : self.params["top_mentions"]]
-            .tolist()
-        )
-        row = pd.DataFrame({"scenario": []})
-        row["scenario"] = b
-        row["Percentage"] = a
-        figures = []
-        if not row.empty:
-            fig = px.treemap(
-                row, path=["scenario"], values="Percentage", title="Tree of Mentions"
-            )
-            figures.append(
-                Figure(
-                    for_object=self,
-                    key=self.name,
-                    figure=fig,
-                )
-            )
-
-        # Do this if you want to prevent the figure from being displayed
-        plt.close("all")
-
-        return self.cache_results(
-            [],
-            passed=True,
-            figures=figures,
-        )
+    mention_counts = (
+        dataset.df[dataset.text_column]
+        .apply(lambda x: " ".join(re.findall(r"(?<=@)\w+", x)))
+        .value_counts()
+    )
+
+    if mention_counts.empty:
+        raise SkipTestError("No mentions found in the dataset")
+
+    start_index = 1 if mention_counts.iloc[0] == "" else 0
+    end_index = top_mentions + start_index
+    mention_counts = mention_counts[start_index:end_index]
+
+    mention_frequencies_df = pd.DataFrame(
+        {
+            "Scenario": mention_counts.index.tolist(),
+            "Percentage": mention_counts.tolist(),
+        }
+    )
+
+    return px.treemap(
+        mention_frequencies_df,
+        path=["Scenario"],
+        values="Percentage",
+        title="Tree of Mentions",
+    )

validmind/tests/data_validation/nlp/PolarityAndSubjectivity.py

@@ -12,7 +12,7 @@ from validmind import tags, tasks
 
 @tags("nlp", "text_data", "data_validation")
 @tasks("nlp")
-def PolarityAndSubjectivity(dataset):
+def PolarityAndSubjectivity(dataset, threshold_subjectivity=0.5, threshold_polarity=0):
     """
     Analyzes the polarity and subjectivity of text data within a given dataset to visualize the sentiment distribution.
 
@@ -50,23 +50,98 @@ def PolarityAndSubjectivity(dataset):
     - Reliance on TextBlob which may not be accurate for all domains or contexts.
     - Visualization could become cluttered with very large datasets, making interpretation difficult.
     """
-
-    # Function to calculate sentiment and subjectivity
-    def analyze_sentiment(text):
-        analysis = TextBlob(text)
-        return analysis.sentiment.polarity, analysis.sentiment.subjectivity
-
-    data = pd.DataFrame()
-    # Apply the function to each row
-    data[["polarity", "subjectivity"]] = dataset.df[dataset.text_column].apply(
-        lambda x: pd.Series(analyze_sentiment(x))
+    # Check text column
+    if not dataset.text_column:
+        raise ValueError("Please set text_column name in the Validmind Dataset object")
+
+    sentiments = dataset.df[dataset.text_column].apply(lambda x: TextBlob(x).sentiment)
+    data = pd.DataFrame(
+        {
+            "polarity": [s.polarity for s in sentiments],
+            "subjectivity": [s.subjectivity for s in sentiments],
+        }
     )
 
     # Create a Plotly scatter plot
     fig = px.scatter(
-        data, x="polarity", y="subjectivity", title="Polarity vs Subjectivity"
+        data_frame=data,
+        x="polarity",
+        y="subjectivity",
+        title="Polarity vs Subjectivity",
     )
     fig.update_traces(textposition="top center")
-    fig.update_layout(xaxis_title="Polarity", yaxis_title="Subjectivity")
 
-    return fig
+    # Add threshold lines with names for legend
+    fig.add_hline(
+        y=threshold_subjectivity,
+        line_dash="dash",
+        line_color="gray",
+        opacity=0.5,
+        name=f"Subjectivity Threshold ({threshold_subjectivity})",
+    )
+    fig.add_vline(
+        x=threshold_polarity,
+        line_dash="dash",
+        line_color="gray",
+        opacity=0.5,
+        name=f"Polarity Threshold ({threshold_polarity})",
+    )
+
+    fig.update_layout(
+        xaxis_title="Polarity",
+        yaxis_title="Subjectivity",
+        xaxis=dict(range=[-1, 1]),
+        yaxis=dict(range=[0, 1]),
+        showlegend=True,
+    )
+
+    # Create Quadrant Distribution table
+    quadrant_df = pd.DataFrame(
+        {
+            "Quadrant": [
+                "Subjective - Positive Sentiment",
+                "Subjective - Negative Sentiment",
+                "Objective - Positive Sentiment",
+                "Objective - Negative Sentiment",
+            ],
+            "Ratio (%)": [
+                (
+                    (data["polarity"] >= threshold_polarity)
+                    & (data["subjectivity"] >= threshold_subjectivity)
+                ).mean()
+                * 100,
+                (
+                    (data["polarity"] < threshold_polarity)
+                    & (data["subjectivity"] >= threshold_subjectivity)
+                ).mean()
+                * 100,
+                (
+                    (data["polarity"] >= threshold_polarity)
+                    & (data["subjectivity"] < threshold_subjectivity)
+                ).mean()
+                * 100,
+                (
+                    (data["polarity"] < threshold_polarity)
+                    & (data["subjectivity"] < threshold_subjectivity)
+                ).mean()
+                * 100,
+            ],
+        }
+    )
+
+    # Create Statistics table
+    stats_df = pd.DataFrame(
+        {
+            "Metric": ["Polarity", "Subjectivity"],
+            "Range": ["[-1, 1]", "[0, 1]"],
+            "Mean": [data["polarity"].mean(), data["subjectivity"].mean()],
+            "Median": [data["polarity"].median(), data["subjectivity"].median()],
+            "Std": [data["polarity"].std(), data["subjectivity"].std()],
+            "Min": [data["polarity"].min(), data["subjectivity"].min()],
+            "Max": [data["polarity"].max(), data["subjectivity"].max()],
+        }
+    )
+
+    statistics_tables = {"Quadrant Distribution": quadrant_df, "Statistics": stats_df}
+
+    return fig, statistics_tables

validmind/tests/data_validation/nlp/Punctuations.py

@@ -8,15 +8,15 @@ Metrics functions for any Pandas-compatible datasets
 
 import string
 from collections import defaultdict
-from dataclasses import dataclass
 
-import matplotlib.pyplot as plt
+import plotly.graph_objects as go
 
-from validmind.vm_models import Figure, Metric, VMDataset
+from validmind import tags, tasks
 
 
-@dataclass
-class Punctuations(Metric):
+@tags("nlp", "text_data", "visualization", "frequency_analysis")
+@tasks("text_classification", "text_summarization", "nlp")
+def Punctuations(dataset, count_mode="token"):
     """
     Analyzes and visualizes the frequency distribution of punctuation usage in a given text dataset.
 
@@ -28,10 +28,11 @@ class Punctuations(Metric):
 
     ### Test Mechanism
 
-    The test begins by verifying that the input "dataset" is of the type VMDataset. Following that, a corpus is created
-    from the dataset by splitting its text on spaces. Each unique punctuation character in the text corpus is then
-    tallied. The frequency distribution of each punctuation symbol is visualized as a bar graph, with these results
-    being stored as Figures and associated with the main Punctuations object.
+    The test begins by verifying that the input "dataset" is of the type VMDataset. The count_mode parameter must be
+    either "token" (counts punctuation marks as individual tokens) or "word" (counts punctuation marks within words).
+    Following that, a corpus is created from the dataset by splitting its text on spaces. Each unique punctuation
+    character in the text corpus is then tallied. The frequency distribution of each punctuation symbol is visualized
+    as a bar graph, with these results being stored as Figures and associated with the main Punctuations object.
 
     ### Signs of High Risk
 
@@ -53,45 +54,60 @@ class Punctuations(Metric):
     - Less effective with languages that use non-standard or different punctuation.
     - Visualization may lack interpretability when there are many unique punctuation marks in the dataset.
     """
-
-    name = "punctuations"
-    required_inputs = ["dataset"]
-    tasks = ["text_classification", "text_summarization"]
-    tags = ["nlp", "text_data", "visualization", "frequency_analysis"]
-
-    def run(self):
-        # Can only run this test if we have a Dataset object
-        if not isinstance(self.inputs.dataset, VMDataset):
-            raise ValueError("Punctuations requires a validmind Dataset object")
-
-        def create_corpus(df, text_column):
-            corpus = []
-            for x in df[text_column].str.split():
-                for i in x:
-                    corpus.append(i)
-            return corpus
-
-        text_column = self.inputs.dataset.text_column
-        corpus = create_corpus(self.inputs.dataset.df, text_column=text_column)
-
-        special = string.punctuation
-        dic = defaultdict(int, {key: 0 for key in special})
+    # Check text column
+    if not dataset.text_column:
+        raise ValueError("Please set text_column name in the Validmind Dataset object")
+
+    if count_mode not in ["token", "word"]:
+        raise ValueError("count_mode parameter must be either 'token' or 'word'")
+
+    corpus = _create_corpus(dataset.df, dataset.text_column)
+    punctuation_counts = _count_punctuations(corpus, count_mode)
+    return _create_punctuation_plot(punctuation_counts)
+
+
+def _create_punctuation_plot(punctuation_counts):
+    """Create a bar plot visualization of punctuation frequencies."""
+    fig = go.Figure(
+        data=[
+            go.Bar(
+                x=list(punctuation_counts.keys()),
+                y=list(punctuation_counts.values()),
+                marker_color="#17C37B",
+            )
+        ]
+    )
+    fig.update_layout(
+        title="Punctuation Distribution",
+        xaxis_title="Punctuation Marks",
+        yaxis_title="Frequency",
+        showlegend=False,
+    )
+    return fig
+
+
+def _create_corpus(df, text_column):
+    """Create a corpus from the dataset's text column."""
+    corpus = []
+    for x in df[text_column].str.split():
+        for i in x:
+            corpus.append(i)
+    return corpus
+
+
+def _count_punctuations(corpus, count_mode="token"):
+    """Count punctuation marks in the corpus based on the specified mode."""
+    special = string.punctuation
+    dic = defaultdict(int, {key: 0 for key in special})
+
+    if count_mode == "token":
         for i in corpus:
             if i in special:
                 dic[i] += 1
-        figures = []
-        # if dic:
-        fig = plt.figure()
-        x, y = zip(*dic.items())
-        plt.bar(x, y, color="#17C37B")
-        figures.append(
-            Figure(
-                for_object=self,
-                key=self.key,
-                figure=fig,
-            )
-        )
-        # Do this if you want to prevent the figure from being displayed
-        plt.close("all")
+    else:  # count_mode == "word"
+        for word in corpus:
+            for char in word:
+                if char in special:
+                    dic[char] += 1
 
-        return self.cache_results(figures=figures)
+    return dic

validmind/tests/data_validation/nlp/Sentiment.py

@@ -47,6 +47,10 @@ def Sentiment(dataset):
     - Relies heavily on the accuracy of the VADER sentiment analysis tool.
     - Visualization alone may not provide comprehensive insights into underlying causes of sentiment distribution.
     """
+    # Check text column
+    if not dataset.text_column:
+        raise ValueError("Please set text_column name in the Validmind Dataset object")
+
     nltk.download("vader_lexicon", quiet=True)
     # Initialize VADER
     sia = SentimentIntensityAnalyzer()