dataframe-textual 0.3.2__py3-none-any.whl → 1.0.0__py3-none-any.whl

dataframe_textual/table_screen.py

@@ -13,7 +13,7 @@ from textual.renderables.bar import Bar
 from textual.screen import ModalScreen
 from textual.widgets import DataTable
 
-from .common import DtypeConfig, _format_row
+from .common import NULL, NULL_DISPLAY, RIDX, DtypeConfig, format_row
 
 
 class TableScreen(ModalScreen):
@@ -31,68 +31,101 @@ class TableScreen(ModalScreen):
         TableScreen > DataTable {
             width: auto;
             min-width: 30;
-            height: auto;
             border: solid $primary;
         }
     """
 
-    def __init__(self, dftable: DataFrameTable):
+    def __init__(self, dftable: DataFrameTable) -> None:
+        """Initialize the table screen.
+
+        Sets up the base modal screen with reference to the main DataFrameTable widget
+        and stores the DataFrame for display.
+
+        Args:
+            dftable: Reference to the parent DataFrameTable widget.
+
+        Returns:
+            None
+        """
         super().__init__()
         self.df: pl.DataFrame = dftable.df  # Polars DataFrame
         self.dftable = dftable  # DataFrameTable
+        self.thousand_separator = False  # Whether to use thousand separators in numbers
 
     def compose(self) -> ComposeResult:
-        """Create the table. Must be overridden by subclasses."""
+        """Compose the table screen widget structure.
+
+        Creates and yields a DataTable widget for displaying tabular data.
+        Subclasses should override to customize table configuration.
+
+        Yields:
+            DataTable: The table widget for this screen.
+        """
         self.table = DataTable(zebra_stripes=True)
         yield self.table
 
-    def on_key(self, event):
+    def build_table(self) -> None:
+        """Build the table content.
+
+        Subclasses should implement this method to populate the DataTable
+        with appropriate columns and rows based on the specific screen's purpose.
+
+        Returns:
+            None
+        """
+        raise NotImplementedError("Subclasses must implement build_table method.")
+
+    def on_key(self, event) -> None:
+        """Handle key press events in the table screen.
+
+        Provides keyboard shortcuts for navigation and interaction, including q/Escape to close.
+        Prevents propagation of non-navigation keys to parent screens.
+
+        Args:
+            event: The key event object.
+
+        Returns:
+            None
+        """
         if event.key in ("q", "escape"):
             self.app.pop_screen()
             event.stop()
-        # Prevent key events from propagating to parent screen,
-        # except for the following default key bindings for DataTable
-        elif event.key not in (
-            "up",
-            "down",
-            "right",
-            "left",
-            "pageup",
-            "pagedown",
-            "ctrl+home",
-            "ctrl+end",
-            "home",
-            "end",
-        ):
+        elif event.key == "comma":
+            self.thousand_separator = not self.thousand_separator
+            self.build_table()
             event.stop()
 
     def _filter_or_highlight_selected_value(
-        self, col_name_value: tuple[str, str] | None, action: str = "filter"
+        self, col_name_value: tuple[str, Any] | None, action: str = "filter"
     ) -> None:
-        """Apply filter or highlight action by the selected value from the frequency table.
+        """Apply filter or highlight action by the selected value.
+
+        Filters or highlights rows in the main table based on a selected value from
+        this table (typically frequency or row detail). Updates the main table's display
+        and notifies the user of the action.
 
         Args:
-            col_name: The name of the column to filter/highlight.
-            col_value: The value to filter/highlight by.
-            action: Either "filter" to filter visible rows, or "highlight" to select matching rows.
+            col_name_value: Tuple of (column_name, column_value) to filter/highlight by, or None.
+            action: Either "filter" to hide non-matching rows, or "highlight" to select matching rows. Defaults to "filter".
+
+        Returns:
+            None
         """
         if col_name_value is None:
             return
         col_name, col_value = col_name_value
 
         # Handle NULL values
-        if col_value == "-":
+        if col_value == NULL:
             # Create expression for NULL values
             expr = pl.col(col_name).is_null()
-            value_display = "[on $primary]NULL[/]"
+            value_display = "[$success]NULL[/]"
         else:
             # Create expression for the selected value
             expr = pl.col(col_name) == col_value
-            value_display = f"[on $primary]{col_value}[/]"
+            value_display = f"[$success]{col_value}[/]"
 
-        matched_indices = set(
-            self.dftable.df.with_row_index("__rid__").filter(expr)["__rid__"].to_list()
-        )
+        matched_indices = set(self.dftable.df.with_row_index(RIDX).filter(expr)[RIDX].to_list())
 
         # Apply the action
         if action == "filter":
@@ -100,13 +133,13 @@ class TableScreen(ModalScreen):
             for i in range(len(self.dftable.visible_rows)):
                 self.dftable.visible_rows[i] = i in matched_indices
             title = "Filter"
-            message = f"Filtered by [on $primary]{col_name}[/] = {value_display}"
+            message = f"Filtered by [$accent]{col_name}[/] == [$success]{value_display}[/]"
         else:  # action == "highlight"
             # Update selected_rows to reflect the highlights
             for i in range(len(self.dftable.selected_rows)):
                 self.dftable.selected_rows[i] = i in matched_indices
             title = "Highlight"
-            message = f"Highlighted [on $primary]{col_name}[/] = {value_display}"
+            message = f"Highlighted [$accent]{col_name}[/] == [$success]{value_display}[/]"
 
         # Recreate the table display with updated data in the main app
         self.dftable._setup_table()
@@ -122,37 +155,56 @@ class RowDetailScreen(TableScreen):
 
     CSS = TableScreen.DEFAULT_CSS.replace("TableScreen", "RowDetailScreen")
 
-    def __init__(self, row_idx: int, dftable):
+    def __init__(self, ridx: int, dftable):
         super().__init__(dftable)
-        self.row_idx = row_idx
+        self.ridx = ridx
 
     def on_mount(self) -> None:
-        """Create the detail table."""
+        """Initialize the row detail screen.
+
+        Populates the table with column names and values from the selected row
+        of the main DataFrame. Sets the table cursor type to "row".
+
+        Returns:
+            None
+        """
+        self.build_table()
+
+    def build_table(self) -> None:
+        """Build the row detail table."""
+        self.table.clear(columns=True)
         self.table.add_column("Column")
         self.table.add_column("Value")
 
         # Get all columns and values from the dataframe row
-        for col, val, dtype in zip(
-            self.df.columns, self.df.row(self.row_idx), self.df.dtypes
-        ):
+        for col, val, dtype in zip(self.df.columns, self.df.row(self.ridx), self.df.dtypes):
             self.table.add_row(
-                *_format_row([col, val], [None, dtype], apply_justify=False)
+                *format_row([col, val], [None, dtype], apply_justify=False, thousand_separator=self.thousand_separator)
             )
 
         self.table.cursor_type = "row"
 
-    def on_key(self, event):
+    def on_key(self, event) -> None:
+        """Handle key press events in the row detail screen.
+
+        Supports 'v' for filtering and '"' for highlighting the main table
+        by the value in the selected row.
+
+        Args:
+            event: The key event object.
+
+        Returns:
+            None
+        """
         if event.key == "v":
             # Filter the main table by the selected value
-            self._filter_or_highlight_selected_value(
-                self._get_col_name_value(), action="filter"
-            )
+            self._filter_or_highlight_selected_value(self._get_col_name_value(), action="filter")
             event.stop()
         elif event.key == "quotation_mark":  # '"'
             # Highlight the main table by the selected value
-            self._filter_or_highlight_selected_value(
-                self._get_col_name_value(), action="highlight"
-            )
+            self._filter_or_highlight_selected_value(self._get_col_name_value(), action="highlight")
+            event.stop()
+        elif event.key == "comma":
             event.stop()
 
     def _get_col_name_value(self) -> tuple[str, Any] | None:
@@ -161,11 +213,126 @@ class RowDetailScreen(TableScreen):
             return None  # Invalid row
 
         col_name = self.df.columns[row_idx]
-        col_value = self.df.item(self.row_idx, row_idx)
+        col_value = self.df.item(self.ridx, row_idx)
 
         return col_name, col_value
 
 
+class StatisticsScreen(TableScreen):
+    """Modal screen to display statistics for a column or entire dataframe."""
+
+    CSS = TableScreen.DEFAULT_CSS.replace("TableScreen", "StatisticsScreen")
+
+    def __init__(self, dftable: DataFrameTable, col_idx: int | None = None):
+        super().__init__(dftable)
+        self.col_idx = col_idx  # None for dataframe statistics, otherwise column index
+
+    def on_mount(self) -> None:
+        """Create the statistics table."""
+        self.build_table()
+
+    def build_table(self) -> None:
+        """Build the statistics table."""
+        self.table.clear(columns=True)
+
+        if self.col_idx is None:
+            # Dataframe statistics
+            self._build_dataframe_stats()
+        else:
+            # Column statistics
+            self._build_column_stats()
+
+    def _build_column_stats(self) -> None:
+        """Build statistics for a single column."""
+        col_name = self.df.columns[self.col_idx]
+        lf = self.df.lazy()
+
+        # Apply only to visible rows
+        if False in self.dftable.visible_rows:
+            lf = lf.filter(self.dftable.visible_rows)
+
+        # Get column statistics
+        stats_df = lf.select(pl.col(col_name)).collect().describe()
+        if len(stats_df) == 0:
+            return
+
+        col_dtype = stats_df.dtypes[1]  # 'value' column
+        dc = DtypeConfig(col_dtype)
+
+        # Add statistics label column
+        self.table.add_column(Text("Statistic", justify="left"), key="statistic")
+
+        # Add value column with appropriate styling
+        self.table.add_column(Text(col_name, justify=dc.justify), key=col_name)
+
+        # Add rows
+        for row in stats_df.rows():
+            stat_label, stat_value = row
+            value = stat_value
+            if stat_value is None:
+                value = NULL_DISPLAY
+            elif dc.gtype == "int" and self.thousand_separator:
+                value = f"{stat_value:,}"
+            elif dc.gtype == "float":
+                value = f"{stat_value:,.2f}" if self.thousand_separator else f"{stat_value:.2f}"
+            else:
+                value = str(stat_value)
+
+            self.table.add_row(
+                Text(stat_label, justify="left"),
+                Text(value, style=dc.style, justify=dc.justify),
+            )
+
+    def _build_dataframe_stats(self) -> None:
+        """Build statistics for the entire dataframe."""
+        lf = self.df.lazy()
+
+        # Apply only to visible rows
+        if False in self.dftable.visible_rows:
+            lf = lf.filter(self.dftable.visible_rows)
+
+        # Get dataframe statistics
+        stats_df = lf.collect().describe()
+
+        # Add columns for each dataframe column with appropriate styling
+        for idx, (col_name, col_dtype) in enumerate(zip(stats_df.columns, stats_df.dtypes), 0):
+            if idx == 0:
+                # Add statistics label column (first column, no styling)
+                self.table.add_column("Statistic", key="statistic")
+                continue
+
+            dc = DtypeConfig(col_dtype)
+            self.table.add_column(Text(col_name, justify=dc.justify), key=col_name)
+
+        # Add rows
+        for row in stats_df.rows():
+            formatted_row = []
+
+            # Format remaining values with appropriate styling
+            for idx, stat_value in enumerate(row):
+                # First element is the statistic label
+                if idx == 0:
+                    formatted_row.append(stat_value)
+                    continue
+
+                col_dtype = stats_df.dtypes[idx]
+                dc = DtypeConfig(col_dtype)
+
+                value = stat_value
+                if stat_value is None:
+                    value = NULL_DISPLAY
+                elif dc.gtype == "int" and self.thousand_separator:
+                    value = f"{stat_value:,}"
+                elif dc.gtype == "float":
+                    value = f"{stat_value:,.2f}" if self.thousand_separator else f"{stat_value:.2f}"
+                else:
+                    value = str(stat_value)
+
+                formatted_row.append(Text(value, style=dc.style, justify=dc.justify))
+
+            self.table.add_row(*formatted_row)
+
+
 class FrequencyScreen(TableScreen):
     """Modal screen to display frequency of values in a column."""
 
@@ -176,12 +343,9 @@ class FrequencyScreen(TableScreen):
         self.col_idx = col_idx
         self.sorted_columns = {
             1: True,  # Count
-            2: True,  # %
         }
         self.df: pl.DataFrame = (
-            dftable.df[dftable.df.columns[self.col_idx]]
-            .value_counts(sort=True)
-            .sort("count", descending=True)
+            dftable.df[dftable.df.columns[self.col_idx]].value_counts(sort=True).sort("count", descending=True)
         )
 
     def on_mount(self) -> None:
@@ -199,49 +363,70 @@ class FrequencyScreen(TableScreen):
             event.stop()
         elif event.key == "v":
             # Filter the main table by the selected value
-            self._filter_or_highlight_selected_value(
-                self._get_col_name_value(), action="filter"
-            )
+            self._filter_or_highlight_selected_value(self._get_col_name_value(), action="filter")
             event.stop()
         elif event.key == "quotation_mark":  # '"'
             # Highlight the main table by the selected value
-            self._filter_or_highlight_selected_value(
-                self._get_col_name_value(), action="highlight"
-            )
+            self._filter_or_highlight_selected_value(self._get_col_name_value(), action="highlight")
             event.stop()
 
     def build_table(self) -> None:
+        """Build the frequency table."""
+        self.table.clear(columns=True)
+
         # Create frequency table
         column = self.dftable.df.columns[self.col_idx]
-        dtype = str(self.dftable.df.dtypes[self.col_idx])
+        dtype = self.dftable.df.dtypes[self.col_idx]
         dc = DtypeConfig(dtype)
 
         # Calculate frequencies using Polars
         total_count = len(self.dftable.df)
 
-        self.table.add_column(Text(column, justify=dc.justify), key=column)
-        self.table.add_column(Text("Count", justify="right"), key="Count")
-        self.table.add_column(Text("%", justify="right"), key="%")
-        self.table.add_column(Text("Histogram", justify="left"), key="Histogram")
+        # Add column headers with sort indicators
+        columns = [
+            (column, "Value", 0),
+            ("Count", "Count", 1),
+            ("%", "%", 2),
+            ("Histogram", "Histogram", 3),
+        ]
+
+        for display_name, key, col_idx_num in columns:
+            # Check if this column is sorted and add indicator
+            if col_idx_num in self.sorted_columns:
+                descending = self.sorted_columns[col_idx_num]
+                sort_indicator = " ▼" if descending else " ▲"
+                header_text = display_name + sort_indicator
+            else:
+                header_text = display_name
+
+            justify = dc.justify if col_idx_num == 0 else ("right" if col_idx_num in (1, 2) else "left")
+            self.table.add_column(Text(header_text, justify=justify), key=key)
 
         # Get style config for Int64 and Float64
-        ds_int = DtypeConfig("Int64")
-        ds_float = DtypeConfig("Float64")
+        ds_int = DtypeConfig(pl.Int64)
+        ds_float = DtypeConfig(pl.Float64)
 
         # Add rows to the frequency table
         for row_idx, row in enumerate(self.df.rows()):
-            value, count = row
+            column, count = row
             percentage = (count / total_count) * 100
 
+            if column is None:
+                value = NULL_DISPLAY
+            elif dc.gtype == "int" and self.thousand_separator:
+                value = f"{column:,}"
+            elif dc.gtype == "float":
+                value = f"{column:,.2f}" if self.thousand_separator else f"{column:.3f}"
+            else:
+                value = str(column)
+
             self.table.add_row(
+                Text(value, style=dc.style, justify=dc.justify),
                 Text(
-                    "-" if value is None else str(value),
-                    style=dc.style,
-                    justify=dc.justify,
+                    f"{count:,}" if self.thousand_separator else str(count), style=ds_int.style, justify=ds_int.justify
                 ),
-                Text(str(count), style=ds_int.style, justify=ds_int.justify),
                 Text(
-                    f"{percentage:.2f}",
+                    f"{percentage:,.3f}" if self.thousand_separator else f"{percentage:.3f}",
                     style=ds_float.style,
                     justify=ds_float.justify,
                 ),
@@ -266,9 +451,6 @@ class FrequencyScreen(TableScreen):
 
     def _sort_by_column(self, descending: bool) -> None:
         """Sort the dataframe by the selected column and refresh the main table."""
-
-        self.log(self.df)
-
         row_idx, col_idx = self.table.cursor_coordinate
         col_sort = col_idx if col_idx == 0 else 1
 
@@ -276,16 +458,14 @@ class FrequencyScreen(TableScreen):
         if sort_dir is not None:
             # If already sorted in the same direction, do nothing
             if sort_dir == descending:
-                self.notify(
-                    "Already sorted in that order", title="Sort", severity="warning"
-                )
+                self.notify("Already sorted in that order", title="Sort", severity="warning")
                 return
 
         self.sorted_columns.clear()
         self.sorted_columns[col_sort] = descending
 
         col_name = self.df.columns[col_sort]
-        self.df = self.df.sort(col_name, descending=descending)
+        self.df = self.df.sort(col_name, descending=descending, nulls_last=True)
 
         # Rebuild the frequency table
         self.table.clear(columns=True)
@@ -293,19 +473,18 @@ class FrequencyScreen(TableScreen):
 
         self.table.move_cursor(row=row_idx, column=col_idx)
 
-        # Notify the user
-        order = "desc" if descending else "asc"
-        self.notify(f"Sorted by [on $primary]{col_name}[/] ({order})", title="Sort")
+        # order = "desc" if descending else "asc"
+        # self.notify(f"Sorted by [on $primary]{col_name}[/] ({order})", title="Sort")
 
     def _get_col_name_value(self) -> tuple[str, str] | None:
         row_idx = self.table.cursor_row
-        if row_idx >= len(self.df.columns):
-            return None  # Skip total row
+        if row_idx >= len(self.df[:, 0]):  # first column
+            return None  # Skip the last `Total` row
 
-        col_name = self.df.columns[self.col_idx]
-        col_dtype = self.df.dtypes[self.col_idx]
+        col_name = self.dftable.df.columns[self.col_idx]
+        col_dtype = self.dftable.df.dtypes[self.col_idx]
 
         cell_value = self.table.get_cell_at(Coordinate(row_idx, 0))
-        col_value = cell_value.plain
+        col_value = NULL if cell_value.plain == NULL_DISPLAY else DtypeConfig(col_dtype).convert(cell_value.plain)
 
-        return col_name, DtypeConfig(col_dtype).convert(col_value)
+        return col_name, col_value