validmind 2.5.6__py3-none-any.whl → 2.5.15__py3-none-any.whl

validmind/tests/data_validation/TimeSeriesLinePlot.py

@@ -12,22 +12,28 @@ class TimeSeriesLinePlot(Metric):
     """
     Generates and analyses time-series data through line plots revealing trends, patterns, anomalies over time.
 
-    **Purpose**: The TimeSeriesLinePlot metric is designed to generate and analyze time series data through the
-    creation of line plots. This assists in the initial inspection of the data by providing a visual representation of
-    patterns, trends, seasonality, irregularity, and anomalies that may be present in the dataset over a period of time.
+    ### Purpose
 
-    **Test Mechanism**: The mechanism for this Python class involves extracting the column names from the provided
-    dataset and subsequently generates line plots for each column using the Plotly Python library. For every column in
-    the dataset, a time-series line plot is created where the values are plotted against the dataset's datetime index.
-    It is important to note that indexes that are not of datetime type will result in a ValueError.
+    The TimeSeriesLinePlot metric is designed to generate and analyze time series data through the creation of line
+    plots. This assists in the initial inspection of the data by providing a visual representation of patterns, trends,
+    seasonality, irregularity, and anomalies that may be present in the dataset over a period of time.
+
+    ### Test Mechanism
+
+    The mechanism for this Python class involves extracting the column names from the provided dataset and subsequently
+    generating line plots for each column using the Plotly Python library. For every column in the dataset, a
+    time-series line plot is created where the values are plotted against the dataset's datetime index. It is important
+    to note that indexes that are not of datetime type will result in a ValueError.
+
+    ### Signs of High Risk
 
-    **Signs of High Risk**:
     - Presence of time-series data that does not have datetime indices.
     - Provided columns do not exist in the provided dataset.
     - The detection of anomalous patterns or irregularities in the time-series plots, indicating potential high model
     instability or probable predictive error.
 
-    **Strengths**:
+    ### Strengths
+
     - The visual representation of complex time series data, which simplifies understanding and helps in recognizing
     temporal trends, patterns, and anomalies.
     - The adaptability of the metric, which allows it to effectively work with multiple time series within the same
@@ -35,7 +41,8 @@ class TimeSeriesLinePlot(Metric):
     - Enables the identification of anomalies and irregular patterns through visual inspection, assisting in spotting
     potential data or model performance problems.
 
-    **Limitations**:
+    ### Limitations
+
     - The effectiveness of the metric is heavily reliant on the quality and patterns of the provided time series data.
     - Exclusively a visual tool, it lacks the capability to provide quantitative measurements, making it less effective
     for comparing and ranking multiple models or when specific numerical diagnostics are needed.

validmind/tests/data_validation/TimeSeriesMissingValues.py

@@ -23,37 +23,42 @@ class TimeSeriesMissingValues(ThresholdTest):
     """
     Validates time-series data quality by confirming the count of missing values is below a certain threshold.
 
-    **Purpose**:
+    ### Purpose
+
     This test is designed to validate the quality of a historical time-series dataset by verifying that the number of
     missing values is below a specified threshold. As time-series models greatly depend on the continuity and
     temporality of data points, missing values could compromise the model's performance. Consequently, this test aims
     to ensure data quality and readiness for the machine learning model, safeguarding its predictive capacity.
 
-    **Test Mechanism**:
-    The test method commences by validating if the dataset has a datetime index, if not, an error is raised. It
+    ### Test Mechanism
+
+    The test method commences by validating if the dataset has a datetime index; if not, an error is raised. It
     establishes a lower limit threshold for missing values and performs a missing values check on each column of the
     dataset. An object for the test result is created stating whether the number of missing values is within the
     specified threshold. Additionally, the test calculates the percentage of missing values alongside the raw count.
 
-    To aid in data visualization, the test generates two plots - a bar plot and a heatmap, to better illustrate the
-    distribution and quantity of missing values per variable. The test results, a count of missing values, the
-    percentage of missing values, and a pass/fail status are returned in a results table.
+    To aid in data visualization, the test generates two plots - a bar plot and a heatmap - to better illustrate the
+    distribution and quantity of missing values per variable. The test results, including a count of missing values,
+    the percentage of missing values, and a pass/fail status, are returned in a results table.
+
+    ### Signs of High Risk
 
-    **Signs of High Risk**:
     - The number of missing values in any column of the dataset surpasses the threshold, marking a failure and a
     high-risk scenario. The reasons could range from incomplete data collection, faulty sensors to data preprocessing
     errors.
     - A continuous visual 'streak' in the heatmap may indicate a systematic error during data collection, pointing
     towards another potential risk source.
 
-    **Strengths**:
-    - Effectively identifies missing values which could adversely affect the model's performance.
+    ### Strengths
+
+    - Effectively identifies missing values which could adversely affect the model’s performance.
     - Applicable and customizable through the threshold parameter across different data sets.
     - Goes beyond raw numbers by calculating the percentage of missing values, offering a more relative understanding
     of data scarcity.
     - Includes a robust visualization mechanism for easy and fast understanding of data quality.
 
-    **Limitations**:
+    ### Limitations
+
     - Although it identifies missing values, the test does not provide solutions to handle them.
     - The test demands that the dataset should have a datetime index, hence limiting its use only to time series
     analysis.

validmind/tests/data_validation/TimeSeriesOutliers.py

@@ -20,43 +20,47 @@ from validmind.vm_models import (
 @dataclass
 class TimeSeriesOutliers(ThresholdTest):
     """
-    Identifies and visualizes outliers in time-series data using z-score method.
-
-    **Purpose**: This test is designed to identify outliers in time-series data using the z-score method. It's vital
-    for ensuring data quality before modeling, as outliers can skew predictive models and significantly impact their
-    overall performance.
-
-    **Test Mechanism**: The test processes a given dataset which must have datetime indexing, checks if a
-    'zscore_threshold' parameter has been supplied, and identifies columns with numeric data types. After finding
-    numeric columns, the implementer then applies the z-score method to each numeric column, identifying outliers based
-    on the threshold provided. Each outlier is listed together with their variable name, z-score, timestamp and
-    relative threshold in a dictionary and converted to a DataFrame for convenient output. Additionally, it produces
-    visual plots for each time series illustrating outliers in the context of the broader dataset. The
-    'zscore_threshold' parameter sets the limit beyond which a data point will be labeled as an outlier. The default
-    threshold is set at 3, indicating that any data point that falls 3 standard deviations away from the mean will be
-    marked as an outlier.
-
-    **Signs of High Risk**:
-    - If many or substantial outliers are present within a dataset, this may be an indicator of high risk as it
-    suggests that the dataset contains significant anomalies.
-    - This could potentially affect the performance of the machine learning models, if not properly addressed.
-    - Data points with z-scores higher than the set threshold would be flagged as outliers and could be considered as
-    high risk.
-
-    **Strengths**:
+    Identifies and visualizes outliers in time-series data using the z-score method.
+
+    ### Purpose
+
+    This test is designed to identify outliers in time-series data using the z-score method. It's vital for ensuring
+    data quality before modeling, as outliers can skew predictive models and significantly impact their overall
+    performance.
+
+    ### Test Mechanism
+
+    The test processes a given dataset which must have datetime indexing, checks if a 'zscore_threshold' parameter has
+    been supplied, and identifies columns with numeric data types. After finding numeric columns, the implementer then
+    applies the z-score method to each numeric column, identifying outliers based on the threshold provided. Each
+    outlier is listed together with their variable name, z-score, timestamp, and relative threshold in a dictionary and
+    converted to a DataFrame for convenient output. Additionally, it produces visual plots for each time series
+    illustrating outliers in the context of the broader dataset. The 'zscore_threshold' parameter sets the limit beyond
+    which a data point will be labeled as an outlier. The default threshold is set at 3, indicating that any data point
+    that falls 3 standard deviations away from the mean will be marked as an outlier.
+
+    ### Signs of High Risk
+
+    - Many or substantial outliers are present within the dataset, indicating significant anomalies.
+    - Data points with z-scores higher than the set threshold.
+    - Potential impact on the performance of machine learning models if outliers are not properly addressed.
+
+    ### Strengths
+
     - The z-score method is a popular and robust method for identifying outliers in a dataset.
-    - Time series maintenance is simplified through requiring a datetime index.
-    - Outliers are identified for each numeric feature individually.
-    - Provides an elaborate report which shows variables, date, z-score and whether the test passed or failed.
-    - Offers visual inspection for detected outliers in the respective time-series through plots.
+    - Simplifies time series maintenance by requiring a datetime index.
+    - Identifies outliers for each numeric feature individually.
+    - Provides an elaborate report showing variables, dates, z-scores, and pass/fail tests.
+    - Offers visual inspection for detected outliers through plots.
+
+    ### Limitations
 
-    **Limitations**:
-    - This test only identifies outliers in numeric columns, and won't identify outliers in categorical variables.
+    - The test only identifies outliers in numeric columns, not in categorical variables.
     - The utility and accuracy of z-scores can be limited if the data doesn't follow a normal distribution.
     - The method relies on a subjective z-score threshold for deciding what constitutes an outlier, which might not
-    always be suitable depending on the dataset and the use case.
+    always be suitable depending on the dataset and use case.
     - It does not address possible ways to handle identified outliers in the data.
-    - The necessity for a datetime index could limit the extent of its application.
+    - The requirement for a datetime index could limit its application.
     """
 
     name = "time_series_outliers"
@@ -215,7 +219,7 @@ class TimeSeriesOutliers(ThresholdTest):
                 )
 
             fig.update_layout(
-                title=f"Time Series with Outliers for {col}",
+                title=f"Outliers for {col}",
                 xaxis_title="Date",
                 yaxis_title=col,
             )

validmind/tests/data_validation/TooManyZeroValues.py

@@ -23,27 +23,31 @@ class TooManyZeroValues(ThresholdTest):
     Identifies numerical columns in a dataset that contain an excessive number of zero values, defined by a threshold
     percentage.
 
-    **Purpose**:
+    ### Purpose
+
     The 'TooManyZeroValues' test is utilized to identify numerical columns in the dataset that may present a quantity
     of zero values considered excessive. The aim is to detect situations where these may implicate data sparsity or a
     lack of variation, limiting their effectiveness within a machine learning model. The definition of 'too many' is
     quantified as a percentage of total values, with a default set to 3%.
 
-    **Test Mechanism**:
+    ### Test Mechanism
+
     This test is conducted by looping through each column in the dataset and categorizing those that pertain to
     numerical data. On identifying a numerical column, the function computes the total quantity of zero values and
     their ratio to the total row count. Should the proportion exceed a pre-set threshold parameter, set by default at
-    0.03 or 3%, the column is considered to have failed the test. The results for each column are summarised and
+    0.03 or 3%, the column is considered to have failed the test. The results for each column are summarized and
     reported, indicating the count and percentage of zero values for each numerical column, alongside a status
     indicating whether the column has passed or failed the test.
 
-    **Signs of High Risk**:
-    - Indicators evidencing a high risk connected with this test would include numerical columns showing a high ratio
-    of zero values when compared to the total count of rows (exceeding a pre-determined threshold).
+    ### Signs of High Risk
+
+    - Numerical columns showing a high ratio of zero values when compared to the total count of rows (exceeding the
+    predetermined threshold).
     - Columns characterized by zero values across the board suggest a complete lack of data variation, signifying high
     risk.
 
-    **Strengths**:
+    ### Strengths
+
     - Assists in highlighting columns featuring an excess of zero values that could otherwise go unnoticed within a
     large dataset.
     - Provides the flexibility to alter the threshold that determines when the quantity of zero values becomes 'too
@@ -53,12 +57,13 @@ class TooManyZeroValues(ThresholdTest):
     - Targets specifically numerical data, thereby avoiding inappropriate application to non-numerical columns and
     mitigating the risk of false test failures.
 
-    **Limitations**:
-    - Is exclusively designed to check for zero values, and doesn’t assesses the potential impact of other values that
-    could affect the dataset, such as extremely high or low figures, missing values or outliers.
+    ### Limitations
+
+    - Is exclusively designed to check for zero values and doesn’t assess the potential impact of other values that
+    could affect the dataset, such as extremely high or low figures, missing values, or outliers.
     - Lacks the ability to detect a repetitive pattern of zeros, which could be significant in time-series or
     longitudinal data.
-    - Zero values can actually be meaningful in some contexts, therefore tagging them as 'too many' could potentially
+    - Zero values can actually be meaningful in some contexts; therefore, tagging them as 'too many' could potentially
     misinterpret the data to some extent.
     - This test does not take into consideration the context of the dataset, and fails to recognize that within certain
     columns, a high number of zero values could be quite normal and not necessarily an indicator of poor data quality.

validmind/tests/data_validation/UniqueRows.py

@@ -19,31 +19,36 @@ class UniqueRows(ThresholdTest):
     """
     Verifies the diversity of the dataset by ensuring that the count of unique rows exceeds a prescribed threshold.
 
-    **Purpose**:
+    ### Purpose
+
     The UniqueRows test is designed to gauge the quality of the data supplied to the machine learning model by
     verifying that the count of distinct rows in the dataset exceeds a specific threshold, thereby ensuring a varied
     collection of data. Diversity in data is essential for training an unbiased and robust model that excels when faced
     with novel data.
 
-    **Test Mechanism**:
+    ### Test Mechanism
+
     The testing process starts with calculating the total number of rows in the dataset. Subsequently, the count of
     unique rows is determined for each column in the dataset. If the percentage of unique rows (calculated as the ratio
     of unique rows to the overall row count) is less than the prescribed minimum percentage threshold given as a
-    function parameter, the test is passed. The results are cached and a final pass or fail verdict is given based on
+    function parameter, the test passes. The results are cached and a final pass or fail verdict is given based on
     whether all columns have successfully passed the test.
 
-    **Signs of High Risk**:
+    ### Signs of High Risk
+
     - A lack of diversity in data columns, demonstrated by a count of unique rows that falls short of the preset
     minimum percentage threshold, is indicative of high risk.
     - This lack of variety in the data signals potential issues with data quality, possibly leading to overfitting in
     the model and issues with generalization, thus posing a significant risk.
 
-    **Strengths**:
+    ### Strengths
+
     - The UniqueRows test is efficient in evaluating the data's diversity across each information column in the dataset.
     - This test provides a quick, systematic method to assess data quality based on uniqueness, which can be pivotal in
     developing effective and unbiased machine learning models.
 
-    **Limitations**:
+    ### Limitations
+
     - A limitation of the UniqueRows test is its assumption that the data's quality is directly proportionate to its
     uniqueness, which may not always hold true. There might be contexts where certain non-unique rows are essential and
     should not be overlooked.

validmind/tests/data_validation/WOEBinPlots.py

@@ -20,34 +20,41 @@ class WOEBinPlots(Metric):
     Generates visualizations of Weight of Evidence (WoE) and Information Value (IV) for understanding predictive power
     of categorical variables in a data set.
 
-    **Purpose**: This test is designed to visualize the Weight of Evidence (WoE) and Information Value (IV) for
-    categorical variables in a provided dataset. By showcasing the data distribution across different categories of
-    each feature, it aids in understanding each variable's predictive power in the context of a classification-based
-    machine learning model. Commonly used in credit scoring models, WoE and IV are robust statistical methods for
-    evaluating a variable's predictive power.
-
-    **Test Mechanism**: The test implementation follows defined steps. Initially, it selects non-numeric columns from
-    the dataset and changes them to string type, paving the way for accurate binning. It then performs an automated WoE
-    binning operation on these selected features, effectively categorizing the potential values of a variable into
-    distinct bins. After the binning process, the function generates two separate visualizations (a scatter chart for
-    WoE values and a bar chart for IV) for each variable. These visual presentations are formed according to the spread
-    of each metric across various categories of each feature.
-
-    **Signs of High Risk**:
+    ### Purpose
+
+    This test is designed to visualize the Weight of Evidence (WoE) and Information Value (IV) for categorical
+    variables in a provided dataset. By showcasing the data distribution across different categories of each feature,
+    it aids in understanding each variable's predictive power in the context of a classification-based machine learning
+    model. Commonly used in credit scoring models, WoE and IV are robust statistical methods for evaluating a
+    variable's predictive power.
+
+    ### Test Mechanism
+
+    The test implementation follows defined steps. Initially, it selects non-numeric columns from the dataset and
+    changes them to string type, paving the way for accurate binning. It then performs an automated WoE binning
+    operation on these selected features, effectively categorizing the potential values of a variable into distinct
+    bins. After the binning process, the function generates two separate visualizations (a scatter chart for WoE values
+    and a bar chart for IV) for each variable. These visual presentations are formed according to the spread of each
+    metric across various categories of each feature.
+
+    ### Signs of High Risk
+
     - Errors occurring during the binning process.
     - Challenges in converting non-numeric columns into string data type.
     - Misbalance in the distribution of WoE and IV, with certain bins overtaking others conspicuously. This could
     denote that the model is disproportionately dependent on certain variables or categories for predictions, an
     indication of potential risks to its robustness and generalizability.
 
-    **Strengths**:
+    ### Strengths
+
     - Provides a detailed visual representation of the relationship between feature categories and the target variable.
     This grants an intuitive understanding of each feature's contribution to the model.
     - Allows for easy identification of features with high impact, facilitating feature selection and enhancing
     comprehension of the model's decision logic.
     - WoE conversions are monotonic, upholding the rank ordering of the original data points, which simplifies analysis.
 
-    **Limitations**:
+    ### Limitations
+
     - The method is largely reliant on the binning process, and an inappropriate binning threshold or bin number choice
     might result in a misrepresentation of the variable's distribution.
     - While excellent for categorical data, the encoding of continuous variables into categorical can sometimes lead to

validmind/tests/data_validation/WOEBinTable.py

@@ -13,36 +13,41 @@ from validmind.vm_models import Metric, ResultSummary, ResultTable, ResultTableM
 @dataclass
 class WOEBinTable(Metric):
     """
-    Calculates and assesses the Weight of Evidence (WoE) and Information Value (IV) of each feature in a ML model.
-
-    **Purpose**: The Weight of Evidence (WoE) and Information Value (IV) test is intended to evaluate the predictive
-    power of each feature in the machine learning model. The test generates binned groups of values from each feature
-    in a dataset, computes the WoE value and the IV value for each bin. These values provide insights on the
-    relationship between each feature and the target variable and their contribution towards the predictive output of
-    the model.
-
-    **Test Mechanism**: The metric leverages the `scorecardpy.woebin` method to perform WoE-based automatic binning on
-    the dataset. Depending on the parameter `breaks_adj`, the method adjusts the cut-off points for binning numeric
-    variables. The bins are then used to calculate the WoE and IV. The metric requires a dataset with the target
-    variable defined. The metric outputs a dataframe that comprises the bin boundaries, WoE, and IV values for each
-    feature.
-
-    **Signs of High Risk**:
-    - High IV values, which denote variables with too much predictive power which might lead to overfitting
-    - Errors during the binning process, which might be due to inappropriate data types or poorly defined bins
-
-    **Strengths**:
-    - The WoE and IV test is highly effective for feature selection in binary classification problems, as it quantifies
-    how much predictive information is packed within each feature regarding the binary outcome
-    - The WoE transformation creates a monotonic relationship between the target and independent variables
-
-    **Limitations**:
-    - Mainly designed for binary classification tasks, therefore it might not be applicable or reliable for multi-class
-    classification or regression tasks
-    - If the dataset has many features or the features are not binnable or they are non-numeric, this process might
-    encounter difficulties
-    - This metric doesn't help in identifying if the predictive factor being observed is a coincidence or a real
-    phenomenon due to data randomness
+    Assesses the Weight of Evidence (WoE) and Information Value (IV) of each feature to evaluate its predictive power
+    in a binary classification model.
+
+    ### Purpose
+
+    The Weight of Evidence (WoE) and Information Value (IV) test is designed to evaluate the predictive power of each
+    feature in a machine learning model. This test generates binned groups of values from each feature, computes the
+    WoE and IV for each bin, and provides insights into the relationship between each feature and the target variable,
+    illustrating their contribution to the model's predictive capabilities.
+
+    ### Test Mechanism
+
+    The test uses the `scorecardpy.woebin` method to perform automatic binning of the dataset based on WoE. The method
+    adjusts the cut-off points for binning numeric variables based on the parameter `breaks_adj`. The bins are then
+    used to calculate the WoE and IV values, effectively creating a dataframe that includes the bin boundaries, WoE,
+    and IV values for each feature. A target variable is required in the dataset to perform this analysis.
+
+    ### Signs of High Risk
+
+    - High IV values, indicating variables with excessive predictive power which might lead to overfitting.
+    - Errors during the binning process, potentially due to inappropriate data types or poorly defined bins.
+
+    ### Strengths
+
+    - Highly effective for feature selection in binary classification problems, as it quantifies the predictive
+    information within each feature concerning the binary outcome.
+    - The WoE transformation creates a monotonic relationship between the target and independent variables.
+
+    ### Limitations
+
+    - Primarily designed for binary classification tasks, making it less applicable or reliable for multi-class
+    classification or regression tasks.
+    - Potential difficulties if the dataset has many features, non-binnable features, or non-numeric features.
+    - The metric does not help in distinguishing whether the observed predictive factor is due to data randomness or a
+    true phenomenon.
     """
 
     name = "woe_bin_table"

validmind/tests/data_validation/ZivotAndrewsArch.py

@@ -17,36 +17,42 @@ logger = get_logger(__name__)
 @dataclass
 class ZivotAndrewsArch(Metric):
     """
-    Evaluates the order of integration and stationarity of time series data using Zivot-Andrews unit root test.
-
-    **Purpose**: The Zivot-Andrews Arch metric is used to evaluate the order of integration for a time series data in a
-    machine learning model. It's designed to test for stationarity, a crucial aspect in time series analysis where data
-    points are not dependent on time. Stationarity means that the statistical properties such as mean, variance and
-    autocorrelation are all constant over time.
-
-    **Test Mechanism**: The Zivot-Andrews unit root test is performed on each feature in the dataset using the
-    `ZivotAndrews` function from the `arch.unitroot` module. This function returns the Zivot-Andrews metric for each
-    feature, which includes the statistical value, p-value (probability value), the number of used lags, and the number
-    of observations. The p-value is later used to decide on the null hypothesis (the time series has a unit root and is
-    non-stationary) based on a chosen level of significance.
-
-    **Signs of High Risk**:
-    - A high p-value can suggest high risk. This might indicate that there's insufficient evidence to reject the null
-    hypothesis, which would mean the time series has a unit root and is therefore non-stationary.
+    Evaluates the order of integration and stationarity of time series data using the Zivot-Andrews unit root test.
+
+    ### Purpose
+
+    The Zivot-Andrews Arch metric is used to evaluate the order of integration for time series data in a machine
+    learning model. It's designed to test for stationarity, a crucial aspect of time series analysis, where data points
+    are independent of time. Stationarity means that the statistical properties such as mean, variance, and
+    autocorrelation are constant over time.
+
+    ### Test Mechanism
+
+    The Zivot-Andrews unit root test is performed on each feature in the dataset using the `ZivotAndrews` function from
+    the `arch.unitroot` module. This function returns several metrics for each feature, including the statistical
+    value, p-value (probability value), the number of lags used, and the number of observations. The p-value is used to
+    decide on the null hypothesis (the time series has a unit root and is non-stationary) based on a chosen level of
+    significance.
+
+    ### Signs of High Risk
+
+    - A high p-value suggests high risk, indicating insufficient evidence to reject the null hypothesis, implying that
+    the time series has a unit root and is non-stationary.
     - Non-stationary time series data can lead to misleading statistics and unreliable machine learning models.
 
-    **Strengths**:
-    - The Zivot-Andrews Arch metric dynamically tests for stationarity against structural breaks in time series data,
-    offering robust evaluation of stationarity in features.
-    - This metric is especially beneficial with financial, economic, or other time-series data where data observations
-    lack a consistent pattern and structural breaks may occur.
-
-    **Limitations**:
-    - The Zivot-Andrews Arch metric assumes that data is derived from a single-equation, autoregressive model. It may,
-    therefore, not be appropriate for multivariate time series data or data which does not align with the
-    autoregressive model assumption.
-    - It might not take into account unexpected shocks or changes in the series trend which can both have a significant
-    impact on the stationarity of the data.
+    ### Strengths
+
+    - Dynamically tests for stationarity against structural breaks in time series data, offering robust evaluation of
+    stationarity in features.
+    - Especially beneficial with financial, economic, or other time-series data where data observations lack a
+    consistent pattern and structural breaks may occur.
+
+    ### Limitations
+
+    - Assumes data is derived from a single-equation, autoregressive model, making it less appropriate for multivariate
+    time series data or data not aligning with this model.
+    - May not account for unexpected shocks or changes in the series trend, both of which can significantly impact data
+    stationarity.
     """
 
     name = "zivot_andrews"

validmind/tests/data_validation/nlp/CommonWords.py

@@ -19,33 +19,40 @@ from ....vm_models import Figure, Metric, VMDataset
 @dataclass
 class CommonWords(Metric):
     """
-    Identifies and visualizes the 40 most frequent non-stopwords in a specified text column within a dataset.
+    Assesses the most frequent non-stopwords in a text column for identifying prevalent language patterns.
 
-    **Purpose**: The CommonWords metric is used to identify and visualize the most prevalent words within a specified
-    text column of a dataset. This provides insights into the prevalent language patterns and vocabulary, especially
-    useful in Natural Language Processing (NLP) tasks such as text classification and text summarization.
+    ### Purpose
 
-    **Test Mechanism**: 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.
+    The CommonWords metric is used to identify and visualize the most prevalent words within a specified text column of
+    a dataset. This provides insights into the prevalent language patterns and vocabulary, especially useful in Natural
+    Language Processing (NLP) tasks such as text classification and text summarization.
+
+    ### Test Mechanism
+
+    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.
+
+    ### Signs of High Risk
 
-    **Signs of High Risk**:
     - A lack of distinct words within the list, or the most common words being stopwords.
     - Frequent occurrence of irrelevant or inappropriate words could point out a poorly curated or noisy dataset.
-    - An error returned due to the absence of a valid Dataset object indicates high risk as the metric cannot be
+    - An error returned due to the absence of a valid Dataset object, indicating high risk as the metric cannot be
     effectively implemented without it.
 
-    **Strengths**:
+    ### Strengths
+
     - 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.
 
-    **Limitations**:
+    ### Limitations
+
     - The test disregards semantic or context-related information as it solely focuses on word frequency.
-    - It intentionally ignores stopwords which might carry necessary significance in certain scenarios.
-    - The applicability is limited to English language text data as English stopwords are used for filtering, hence
+    - It intentionally ignores stopwords, which might carry necessary significance in certain scenarios.
+    - The applicability is limited to English-language text data as English stopwords are used for filtering, hence
     cannot account for data in other languages.
     - The metric requires a valid Dataset object, indicating a dependency condition that limits its broader
     applicability.