ethiclean-aditya 0.1.0__tar.gz

ethiclean_aditya-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: ethiclean-aditya
+Version: 0.1.0
+Summary: A lightweight tool for cleaning data and checking demographic bias.
+Author-email: Aditya OHS <1adityaneil@gmail.com>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pandas
+
+# ethiclean

ethiclean_aditya-0.1.0/README.md

@@ -0,0 +1 @@
+# ethiclean

ethiclean_aditya-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ethiclean-aditya" # Must be unique on PyPI!
+version = "0.1.0"
+authors = [
+  { name="Aditya OHS", email="1adityaneil@gmail.com" },
+]
+description = "A lightweight tool for cleaning data and checking demographic bias."
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "pandas",
+]

ethiclean_aditya-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ethiclean_aditya-0.1.0/src/ethiclean/bias.py

@@ -0,0 +1,74 @@
+import pandas as pd
+import warnings
+
+
+class BiasDetector:
+    """A class to detect potential bias in categorical columns of a DataFrame."""
+
+    def detect_class_imbalance(self, df, column_name):
+        """
+        Analyze the distribution of unique values in a column and detect class imbalance.
+        
+        This method performs the following operations:
+        1. Validates that the column exists in the DataFrame
+        2. Calculates the count and percentage of each unique value
+        3. Identifies if any single group dominates the dataset (>80%)
+        4. Issues a warning if significant imbalance is detected
+        
+        Args:
+            df (pd.DataFrame): The DataFrame containing the column to analyze.
+            column_name (str): The name of the column to check for bias.
+            
+        Returns:
+            dict: A dictionary containing:
+                - 'distributions': dict of each unique value and its percentage
+                - 'imbalance_detected': bool indicating if any group exceeds 80%
+                - 'dominant_group': str or None, the group exceeding 80% (if any)
+                - 'dominant_percentage': float or None, the percentage of the dominant group
+                - 'total_records': int, the total number of records analyzed
+        """
+        # Validate that the specified column exists in the DataFrame
+        if column_name not in df.columns:
+            raise ValueError(f"Column '{column_name}' not found in DataFrame.")
+        
+        # Get the total count of non-null values in the column
+        total_records = df[column_name].notna().sum()
+        
+        if total_records == 0:
+            raise ValueError(f"Column '{column_name}' contains no non-null values.")
+        
+        # Calculate the frequency of each unique value
+        value_counts = df[column_name].value_counts()
+        
+        # Calculate the percentage distribution for each unique value
+        # This shows the proportion of the dataset each group represents
+        distributions = (value_counts / total_records * 100).round(2).to_dict()
+        
+        # Identify if any single group exceeds 80% of the dataset
+        # This threshold indicates potential bias or class imbalance
+        imbalance_detected = False
+        dominant_group = None
+        dominant_percentage = None
+        
+        for group, percentage in distributions.items():
+            if percentage > 80:
+                imbalance_detected = True
+                dominant_group = group
+                dominant_percentage = percentage
+                # Issue a warning about the detected imbalance
+                warnings.warn(
+                    f"Potential bias detected in column '{column_name}': "
+                    f"Group '{group}' represents {percentage}% of the dataset.",
+                    UserWarning
+                )
+                break
+        
+        # Return results as a structured dictionary
+        return {
+            'distributions': distributions,
+            'imbalance_detected': imbalance_detected,
+            'dominant_group': dominant_group,
+            'dominant_percentage': dominant_percentage,
+            'total_records': total_records
+        }
+        

ethiclean_aditya-0.1.0/src/ethiclean/cleaner.py

@@ -0,0 +1,35 @@
+import pandas as pd
+
+
+class DataCleaner:
+    """A class to clean and standardize messy CSV data."""
+
+    def clean_csv(self, file_path):
+        """
+        Clean a CSV file by standardizing column headers and removing blank rows.
+        
+        This method performs the following operations:
+        1. Reads the CSV file into a DataFrame
+        2. Converts all column headers to lowercase
+        3. Replaces spaces in column names with underscores
+        4. Removes any rows that are completely blank (all NaN values)
+        
+        Args:
+            file_path (str): Path to the CSV file to be cleaned.
+            
+        Returns:
+            pd.DataFrame: A cleaned DataFrame with standardized column names and no blank rows.
+        """
+        # Read the CSV file into a pandas DataFrame
+        df = pd.read_csv(file_path)
+        
+        # Standardize column headers: convert to lowercase and replace spaces with underscores
+        # This ensures consistent column naming conventions across the dataset
+        df.columns = df.columns.str.strip().str.lower().str.replace(' ', '_')
+        
+        # Remove rows that are completely blank (all NaN values)
+        # This cleans up formatting issues or incomplete entries in the dataset
+        df = df.dropna(how='all')
+        
+        return df
+

ethiclean_aditya-0.1.0/src/ethiclean/report.py

@@ -0,0 +1,107 @@
+import pandas as pd
+from ethiclean.cleaner import DataCleaner
+from ethiclean.bias import BiasDetector
+
+
+class ReportGenerator:
+    """A class to generate formatted health reports from cleaned data and bias analysis."""
+
+    def generate_report(self, original_df, cleaned_df, bias_results):
+        """
+        Generate and print a formatted dataset health report to the terminal.
+        
+        This method creates a visually organized report showing:
+        1. Report title and timestamp information
+        2. Data cleaning statistics (rows removed, rows retained)
+        3. Column header standardization summary
+        4. Bias analysis results and warnings
+        
+        Args:
+            original_df (pd.DataFrame): The original DataFrame before cleaning.
+            cleaned_df (pd.DataFrame): The cleaned DataFrame after processing.
+            bias_results (dict): Dictionary output from BiasDetector.detect_class_imbalance().
+        """
+        # Calculate cleaning statistics
+        original_rows = len(original_df)
+        cleaned_rows = len(cleaned_df)
+        rows_removed = original_rows - cleaned_rows
+        
+        # Print the report header
+        print("\n" + "=" * 70)
+        print(" " * 15 + "DATASET HEALTH REPORT")
+        print("=" * 70 + "\n")
+        
+        # Print data cleaning summary
+        print("📊 DATA CLEANING SUMMARY")
+        print("-" * 70)
+        print(f"  Original rows:        {original_rows:,}")
+        print(f"  Cleaned rows:         {cleaned_rows:,}")
+        print(f"  Rows removed:         {rows_removed:,}")
+        print(f"  Removal rate:         {(rows_removed / original_rows * 100):.2f}%")
+        print()
+        
+        # Print column standardization information
+        print("🔧 COLUMN STANDARDIZATION")
+        print("-" * 70)
+        print(f"  Total columns:        {len(cleaned_df.columns)}")
+        print(f"  Standardized columns:")
+        for col in cleaned_df.columns:
+            print(f"    • {col}")
+        print()
+        
+        # Print bias analysis results
+        print("⚠️  BIAS ANALYSIS RESULTS")
+        print("-" * 70)
+        
+        if bias_results['imbalance_detected']:
+            # Print warning if imbalance is detected
+            print(f"  ⛔ IMBALANCE DETECTED!")
+            print(f"  Dominant group:       {bias_results['dominant_group']}")
+            print(f"  Dominance level:      {bias_results['dominant_percentage']}%")
+            print(f"  Status:               REQUIRES ATTENTION")
+        else:
+            # Print all clear message if no imbalance
+            print("  ✅ No significant imbalance detected")
+            print(f"  Status:               ALL CLEAR")
+        
+        print()
+        print("  Distribution Breakdown:")
+        for group, percentage in sorted(
+            bias_results['distributions'].items(),
+            key=lambda x: x[1],
+            reverse=True
+        ):
+            # Create a simple bar chart representation
+            bar_length = int(percentage / 5)
+            bar = "█" * bar_length
+            print(f"    {group:20} {percentage:6.2f}%  {bar}")
+        print()
+        print("=" * 70 + "\n")
+
+    def generate_report_from_csv(self, csv_file_path, column_to_analyze):
+        """
+        Convenience method that performs cleaning and bias detection in one call.
+        
+        This method orchestrates the full workflow:
+        1. Load the original CSV
+        2. Clean the data using DataCleaner
+        3. Detect bias using BiasDetector
+        4. Generate and display the report
+        
+        Args:
+            csv_file_path (str): Path to the CSV file to process.
+            column_to_analyze (str): Name of the column to check for bias.
+        """
+        # Load the original DataFrame before any processing
+        original_df = pd.read_csv(csv_file_path)
+        
+        # Clean the data using DataCleaner
+        cleaner = DataCleaner()
+        cleaned_df = cleaner.clean_csv(csv_file_path)
+        
+        # Analyze bias in the specified column using BiasDetector
+        detector = BiasDetector()
+        bias_results = detector.detect_class_imbalance(cleaned_df, column_to_analyze)
+        
+        # Generate and display the formatted report
+        self.generate_report(original_df, cleaned_df, bias_results)

ethiclean_aditya-0.1.0/src/ethiclean_aditya.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: ethiclean-aditya
+Version: 0.1.0
+Summary: A lightweight tool for cleaning data and checking demographic bias.
+Author-email: Aditya OHS <1adityaneil@gmail.com>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pandas
+
+# ethiclean

ethiclean_aditya-0.1.0/src/ethiclean_aditya.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/ethiclean/__init__.py
+src/ethiclean/bias.py
+src/ethiclean/cleaner.py
+src/ethiclean/report.py
+src/ethiclean_aditya.egg-info/PKG-INFO
+src/ethiclean_aditya.egg-info/SOURCES.txt
+src/ethiclean_aditya.egg-info/dependency_links.txt
+src/ethiclean_aditya.egg-info/requires.txt
+src/ethiclean_aditya.egg-info/top_level.txt

ethiclean_aditya-0.1.0/src/ethiclean_aditya.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ethiclean_aditya-0.1.0/src/ethiclean_aditya.egg-info/requires.txt

@@ -0,0 +1 @@
+pandas

ethiclean_aditya-0.1.0/src/ethiclean_aditya.egg-info/top_level.txt

@@ -0,0 +1 @@
+ethiclean