tablelab 0.5.0__py3-none-any.whl

tablelab/filepicker.py

@@ -0,0 +1,195 @@
+"""A browse dialog over the filesystem the kernel can see.
+
+`FileUpload` opens the browser's own file dialog, which is the right thing when
+the notebook is on one machine and the file on another - but it copies the whole
+file through the front end, which is slow for a large table and size-capped by
+the browser. For local work the file is already next to the kernel, so browsing
+the kernel's own folders is both faster and unbounded. tablelab offers both and
+lets the situation decide.
+
+Built from ordinary widgets rather than a native dialog on purpose: a native one
+opens on the machine running the kernel, which over SSH or in a container is not
+the machine the person is looking at.
+"""
+import os
+
+import ipywidgets as widgets
+
+# What the dialog lists. Everything else is hidden until "all files" is ticked -
+# a data folder is usually full of things that are not tables.
+SUFFIXES = (".csv", ".tsv", ".tab", ".psv", ".txt", ".json", ".jsonl", ".ndjson",
+            ".parquet", ".feather", ".arrow", ".xlsx", ".xls")
+
+PARENT = ".."
+
+
+class FilePicker:
+    """A folder listing. Calls `on_choose(path)` when a file is opened.
+
+    Clicking a folder walks into it, because a dialog that needs two clicks to
+    move one level down is a dialog people stop using.
+    """
+
+    def __init__(self, on_choose, start=None):
+        self._on_choose = on_choose
+        self._entries = {}              # label shown in the list -> absolute path
+        self._folder = os.path.abspath(start or os.getcwd())
+
+        self.folder = widgets.Text(description="folder:", continuous_update=False,
+                                   layout=widgets.Layout(width="480px"))
+        self.up = widgets.Button(description="Up", icon="arrow-up",
+                                 layout=widgets.Layout(width="90px"))
+        self.listing = widgets.Select(rows=9, layout=widgets.Layout(width="560px"))
+        self.all_files = widgets.Checkbox(value=False, description="all files",
+                                          indent=False,
+                                          layout=widgets.Layout(width="110px"),
+                                          tooltip="List files of every type, not "
+                                                  "just the ones tablelab reads")
+        self.open_btn = widgets.Button(description="Open", button_style="primary",
+                                       icon="check", disabled=True,
+                                       layout=widgets.Layout(width="110px"))
+        self.close_btn = widgets.Button(description="Close",
+                                        layout=widgets.Layout(width="110px"))
+        self.note = widgets.HTML()
+
+        self.up.on_click(lambda _: self._go(os.path.dirname(self._folder)))
+        self.folder.observe(self._on_folder, names="value")
+        self.all_files.observe(lambda _: self._fill(), names="value")
+        self.listing.observe(self._on_select, names="value")
+        self.open_btn.on_click(lambda _: self._choose())
+        self.close_btn.on_click(lambda _: self.close())
+
+        self.ui = widgets.VBox(
+            [widgets.HBox([self.folder, self.up]),
+             self.listing,
+             widgets.HBox([self.open_btn, self.close_btn, self.all_files]),
+             self.note],
+            layout=widgets.Layout(display="none", width="600px", padding="8px",
+                                  border="1px solid #d8d7d3",
+                                  margin="4px 0 8px 0"))
+
+    # -- open and close ------------------------------------------------------
+    def open(self, folder=None):
+        """Show the dialog, starting in `folder` (or where it was left)."""
+        if folder:
+            self._folder = os.path.abspath(folder)
+        self._fill()
+        self.ui.layout.display = "flex"
+
+    def close(self):
+        self.ui.layout.display = "none"
+
+    def toggle(self, folder=None):
+        if self.ui.layout.display == "none":
+            self.open(folder)
+        else:
+            self.close()
+
+    # -- navigation ----------------------------------------------------------
+    def _go(self, folder):
+        folder = os.path.abspath(os.path.expanduser(folder or self._folder))
+        if not os.path.isdir(folder):
+            self.note.value = _warn(f"no folder {folder}")
+            return
+        self._folder = folder
+        self._fill()
+
+    def _on_folder(self, _change):
+        self._go(self.folder.value)
+
+    def _fill(self):
+        """List the current folder: parent first, then folders, then files."""
+        _set(self.folder, self._folder, self._on_folder)
+        try:
+            names = sorted(os.listdir(self._folder), key=str.lower)
+        except OSError as e:
+            self.note.value = _warn(f"{type(e).__name__}: {e}")
+            names = []
+
+        folders, files = [], []
+        for name in names:
+            if name.startswith("."):                # dotfiles are not what anyone
+                continue                            # came here to open
+            path = os.path.join(self._folder, name)
+            if os.path.isdir(path):
+                folders.append((f"{name}/", path))
+            elif self.all_files.value or name.lower().endswith(SUFFIXES):
+                files.append((name, path))
+
+        self._entries = dict([(PARENT, os.path.dirname(self._folder))] + folders + files)
+        self.listing.unobserve(self._on_select, names="value")
+        self.listing.options = list(self._entries)
+        self.listing.value = None               # nothing chosen in a new folder
+        self.listing.observe(self._on_select, names="value")
+
+        self.open_btn.disabled = True
+        self.note.value = ("" if files else
+                           "<span style='color:#52514e'>no table files here - "
+                           "tick <b>all files</b> to see everything</span>")
+
+    def _on_select(self, _change):
+        """A folder is walked into; a file only arms the Open button."""
+        label = self.listing.value
+        if label is None:
+            return
+        path = self._entries[label]
+        if label == PARENT or label.endswith("/"):
+            self._go(path)
+        else:
+            self.open_btn.disabled = False
+
+    def _choose(self):
+        label = self.listing.value
+        if label is None or label.endswith("/"):
+            return
+        self.close()
+        self._on_choose(self._entries[label])
+
+
+def _set(widget, value, handler):
+    """Set a widget's value without waking its own observer."""
+    widget.unobserve(handler, names="value")
+    widget.value = value
+    widget.observe(handler, names="value")
+
+
+def _warn(text):
+    return f"<span style='color:#b3261e'>{text}</span>"
+
+
+class SaveFilePicker(FilePicker):
+    """Browse a destination folder and choose a new CSV filename."""
+
+    def __init__(self, on_choose, start=None):
+        super().__init__(on_choose, start)
+        self.filename = widgets.Text(description="File name:", value="table.csv",
+                                     continuous_update=False,
+                                     layout=widgets.Layout(width="480px"))
+        self.open_btn.description = "Save"
+        self.open_btn.icon = "save"
+        self.close_btn.description = "Cancel"
+        self.ui.children = (
+            widgets.HBox([self.folder, self.up]), self.listing, self.filename,
+            widgets.HBox([self.open_btn, self.close_btn]), self.note)
+
+    def _fill(self):
+        super()._fill()
+        self.open_btn.disabled = not os.path.isdir(self._folder)
+        self.note.value = "Choose a folder and enter a CSV filename."
+
+    def _on_select(self, change):
+        label = self.listing.value
+        if label is None:
+            return
+        if label == PARENT or label.endswith("/"):
+            self._go(self._entries[label])
+        else:
+            self.filename.value = label
+
+    def _choose(self):
+        filename = self.filename.value.strip()
+        if not filename or filename in {".", ".."} or os.path.basename(filename) != filename:
+            self.note.value = "Enter a filename; choose its folder above."
+            return
+        if self._on_choose(os.path.join(self._folder, filename)) is not None:
+            self.close()

tablelab/helpers/__init__.py

@@ -0,0 +1,50 @@
+"""Reusable building blocks behind the notebook GUI.
+
+Most users only need ``from tablelab import main``.  This namespace keeps the
+data, plotting, and widget helpers discoverable for notebooks that want to
+assemble a more specialised interface.
+"""
+
+from .data import (
+    describe,
+    find_label_column,
+    label_name,
+    load_table,
+    numeric_columns,
+    read_uploaded_dataframe,
+    resolve_column,
+    row_series,
+    summary_stats,
+)
+from .plotting import (
+    KINDS,
+    apply_grid,
+    box_plot,
+    draw,
+    ecdf,
+    histogram,
+    run_chart,
+    sorted_run_chart,
+)
+from .widgets import FilePicker
+
+__all__ = [
+    "KINDS",
+    "FilePicker",
+    "apply_grid",
+    "box_plot",
+    "describe",
+    "draw",
+    "ecdf",
+    "find_label_column",
+    "histogram",
+    "label_name",
+    "load_table",
+    "numeric_columns",
+    "read_uploaded_dataframe",
+    "resolve_column",
+    "row_series",
+    "run_chart",
+    "sorted_run_chart",
+    "summary_stats",
+]

tablelab/helpers/data.py

@@ -0,0 +1,30 @@
+"""Data-loading and table-inspection helpers used by the GUI."""
+
+from ..file_readers import load_table, read_uploaded_dataframe
+from ..table import (
+    column_choices,
+    data_type,
+    describe,
+    find_label_column,
+    is_numeric,
+    label_name,
+    numeric_columns,
+    resolve_column,
+    row_series,
+    summary_stats,
+)
+
+__all__ = [
+    "column_choices",
+    "data_type",
+    "describe",
+    "find_label_column",
+    "is_numeric",
+    "label_name",
+    "load_table",
+    "numeric_columns",
+    "read_uploaded_dataframe",
+    "resolve_column",
+    "row_series",
+    "summary_stats",
+]

tablelab/helpers/plotting.py

@@ -0,0 +1,31 @@
+"""Plotting helpers used by the GUI and custom notebooks."""
+
+from ..charts import (
+    CENTRED,
+    KINDS,
+    apply_grid,
+    box_plot,
+    draw,
+    ecdf,
+    histogram,
+    run_chart,
+    sorted_run_chart,
+)
+from ..figures import enable_zoom, figure, show, show_in_output, zoom_active
+
+__all__ = [
+    "CENTRED",
+    "KINDS",
+    "apply_grid",
+    "box_plot",
+    "draw",
+    "ecdf",
+    "enable_zoom",
+    "figure",
+    "histogram",
+    "run_chart",
+    "show",
+    "show_in_output",
+    "sorted_run_chart",
+    "zoom_active",
+]

tablelab/helpers/widgets.py

@@ -0,0 +1,5 @@
+"""Widget helpers used to compose the tablelab interface."""
+
+from ..filepicker import FilePicker
+
+__all__ = ["FilePicker"]

tablelab/missing_values.py

@@ -0,0 +1,97 @@
+"""Missing-value operations and their standalone pandas equivalents."""
+import inspect
+
+import pandas as pd
+
+
+def _fixed_value(series, value):
+    dtype = series.cat.categories.dtype if isinstance(series.dtype, pd.CategoricalDtype) else series.dtype
+    if pd.api.types.is_bool_dtype(dtype):
+        choices = {'true': True, 'false': False, '1': True, '0': False}
+        if value.strip().lower() not in choices:
+            raise ValueError(f'{series.name}: enter true or false for Boolean data.')
+        return choices[value.strip().lower()]
+    if pd.api.types.is_numeric_dtype(dtype):
+        return pd.to_numeric(value)
+    if pd.api.types.is_datetime64_any_dtype(dtype):
+        replacement = pd.to_datetime(value)
+        if isinstance(dtype, pd.DatetimeTZDtype) and pd.notna(replacement):
+            replacement = (replacement.tz_localize(dtype.tz) if replacement.tzinfo is None
+                           else replacement.tz_convert(dtype.tz))
+        return replacement
+    if pd.api.types.is_timedelta64_dtype(dtype):
+        return pd.to_timedelta(value)
+    return value
+
+
+def _fill_column(series, value):
+    if not series.isna().any():
+        return series.copy()
+    replacement = _fixed_value(series, value)
+    if pd.isna(replacement):
+        raise ValueError(f'{series.name}: the fill value must not itself be missing.')
+    if isinstance(series.dtype, pd.CategoricalDtype):
+        if replacement not in series.cat.categories:
+            series = series.cat.add_categories([replacement])
+    elif pd.api.types.is_integer_dtype(series.dtype) and replacement != int(replacement):
+        series = series.astype('Float64')
+    return series.fillna(replacement)
+
+
+def _median_column(series):
+    if not series.isna().any() or not series.notna().any():
+        return series.copy()
+    median = series.median()
+    if pd.api.types.is_integer_dtype(series.dtype) and median != int(median):
+        series = series.astype('Float64')
+    return series.fillna(median)
+
+
+def validate_missing(df, columns, action):
+    if not columns:
+        raise ValueError('Select at least one column for missing-value handling.')
+    if action == 'median':
+        invalid = [str(column) for column in columns
+                   if not pd.api.types.is_numeric_dtype(df[column].dtype)
+                   or pd.api.types.is_bool_dtype(df[column].dtype)
+                   or pd.api.types.is_complex_dtype(df[column].dtype)]
+        if invalid:
+            raise ValueError('Median filling requires numeric columns. Deselect: ' + ', '.join(invalid))
+    if action not in {'inspect', 'drop', 'fixed', 'median'}:
+        raise ValueError('Select a missing-value action.')
+
+
+def missing_result(df, columns, action, value='', how='any'):
+    validate_missing(df, columns, action)
+    if action == 'inspect':
+        counts = df.loc[:, columns].isna().sum()
+        return pd.DataFrame({'column': columns, 'missing_count': counts.to_numpy(),
+                             'missing_percent': (counts.to_numpy() * 100 / len(df)
+                                                 if len(df) else [0.0] * len(columns))})
+    if action == 'drop':
+        return df.dropna(subset=columns, how=how).copy()
+    result = df.copy()
+    for column in columns:
+        result[column] = (_fill_column(result[column], value) if action == 'fixed'
+                          else _median_column(result[column]))
+    return result
+
+
+def missing_code(df, columns, action, value='', how='any'):
+    validate_missing(df, columns, action)
+    if action == 'inspect':
+        return [f'columns = {columns!r}', 'counts = source.loc[:, columns].isna().sum()',
+                "result = pd.DataFrame({'column': columns, 'missing_count': counts.to_numpy(),",
+                "                       'missing_percent': (counts.to_numpy() * 100 / len(source)",
+                "                                           if len(source) else [0.0] * len(columns))})"]
+    if action == 'drop':
+        return [f'result = source.dropna(subset={columns!r}, how={how!r}).copy()']
+    helper = _fill_column if action == 'fixed' else _median_column
+    lines = []
+    if action == 'fixed':
+        lines.extend(inspect.getsource(_fixed_value).splitlines() + [''])
+    lines.extend(inspect.getsource(helper).splitlines() + ['', 'result = source.copy()'])
+    lines.append(f'for column in {columns!r}:')
+    argument = f', {value!r}' if action == 'fixed' else ''
+    lines.append(f'    result[column] = {helper.__name__}(result[column]{argument})')
+    return lines

tablelab/paged_preview.py

@@ -0,0 +1,152 @@
+"""A bounded preview that references a table and renders only one page."""
+import uuid
+
+import ipywidgets as widgets
+from IPython.display import HTML
+
+
+JOIN_COLORS = {'left': '#dceeff', 'right': '#ffe4cc', 'both': '#e7ddf5'}
+
+
+def join_column_origins(left_columns, right_columns, left_keys, right_keys):
+    """Match pandas merge's suffixes and shared-key projection."""
+    common = {left for left, right in zip(left_keys, right_keys) if left == right}
+    overlap = (set(left_columns) & set(right_columns)) - common
+    origins = {f'{column}_left' if column in overlap else column:
+               'both' if column in common else 'left' for column in left_columns}
+    origins.update({f'{column}_right' if column in overlap else column: 'right'
+                    for column in right_columns if column not in common})
+    return origins
+
+
+def table_preview_html(df, selected_column=None, column_origins=None):
+    """Keep column headers visible inside a scrollable notebook preview."""
+    scope = "tablelab-selected-" + uuid.uuid4().hex
+    shading = ""
+    legend = ''
+    if column_origins:
+        for position, column in enumerate(df.columns):
+            origin = column_origins.get(column)
+            if origin in JOIN_COLORS:
+                cell = len(df.columns) - position
+                shading += (f'.{scope} tr > :nth-last-child({cell}) '
+                            f'{{ background: {JOIN_COLORS[origin]}; color: #222; }}')
+        legend = ('<div>Column origin: ' + ' · '.join(
+            f'<span style="background:{JOIN_COLORS[origin]};color:#222;padding:2px 6px">{label}</span>'
+            for origin, label in [('left', 'Left table'), ('right', 'Right table'),
+                                  ('both', 'Shared join key')]) + '</div>')
+    if selected_column is not None:
+        for position, column in enumerate(df.columns):
+            if column == selected_column:
+                # Count from the right so index cells do not affect the position.
+                cell = len(df.columns) - position
+                shading += f".{scope} tr > :nth-last-child({cell}) {{ background: #fff2cc; color: #222; }}"
+    return HTML("<style>" + shading + """
+.tablelab-table-preview { max-height: 420px; overflow: auto; }
+.tablelab-table-preview table { border-collapse: separate; border-spacing: 0; }
+.tablelab-table-preview thead {
+    position: sticky;
+    top: 0;
+    z-index: 1;
+    background: var(--jp-layout-color0, white);
+    color: var(--jp-ui-font-color1, #222);
+}
+</style>""" + legend + '<div class="tablelab-table-preview ' + scope + '">' + df.to_html() + "</div>")
+
+
+class PagedTablePreview:
+    DEFAULT_PAGE_SIZE = 100
+
+    def __init__(self):
+        self.df = None
+        self.active = False
+        self._updating = False
+        self._page_size = self.DEFAULT_PAGE_SIZE
+        options = dict(min=0, max=0, value=0, disabled=True,
+                       layout=widgets.Layout(width="150px"),
+                       style={"description_width": "70px"})
+        self.start_row = widgets.BoundedIntText(description="Start row:", **options)
+        self.end_row = widgets.BoundedIntText(description="End row:", **options)
+        self.previous = widgets.Button(description="Previous", disabled=True)
+        self.next = widgets.Button(description="Next", disabled=True)
+        self.info = widgets.HTML()
+        self.output = widgets.Output()
+        self.ui = widgets.VBox([
+            widgets.HBox([self.start_row, self.end_row, self.previous, self.next],
+                          layout=widgets.Layout(flex_flow="row wrap")), self.info, self.output])
+        self.start_row.observe(self._bounds_changed, names="value")
+        self.end_row.observe(self._bounds_changed, names="value")
+        self.previous.on_click(lambda _: self._move(-1))
+        self.next.on_click(lambda _: self._move(1))
+
+    def set_table(self, df):
+        self.df = df  # Share the loaded DataFrame; no extra full-table copy.
+        count = len(df) if df is not None else 0
+        self._updating = True
+        try:
+            for field in (self.start_row, self.end_row):
+                field.min = 0
+                field.max = count
+                field.disabled = count == 0
+            self.start_row.value = 1 if count else 0
+            self._page_size = min(count, self.DEFAULT_PAGE_SIZE) if count else self.DEFAULT_PAGE_SIZE
+            self.end_row.value = min(count, self._page_size)
+            if count:
+                self.start_row.min = self.end_row.min = 1
+        finally:
+            self._updating = False
+        self.render()
+
+    def set_active(self, active):
+        self.active = active
+        self.render()
+
+    def _bounds_changed(self, change):
+        if self._updating:
+            return
+        self._updating = True
+        try:
+            if self.start_row.value > self.end_row.value:
+                if change["owner"] is self.start_row:
+                    self.end_row.value = self.start_row.value
+                else:
+                    self.start_row.value = self.end_row.value
+            self._page_size = self.end_row.value - self.start_row.value + 1
+        finally:
+            self._updating = False
+        self.render()
+
+    def _move(self, direction):
+        if self.df is None or not len(self.df):
+            return
+        candidate = (self.end_row.value + 1 if direction > 0 else
+                     max(1, self.start_row.value - self._page_size))
+        if candidate > len(self.df):
+            return
+        self._updating = True
+        try:
+            self.start_row.value = candidate
+            self.end_row.value = min(candidate + self._page_size - 1, len(self.df))
+        finally:
+            self._updating = False
+        self.render()
+
+    def render(self):
+        count = len(self.df) if self.df is not None else 0
+        start, end = self.start_row.value, self.end_row.value
+        self.previous.disabled = not count or start <= 1
+        self.next.disabled = not count or end >= count
+        self.info.value = (f"Rows {start:,}–{end:,} of {count:,}. "
+                           f"Page size: {self._page_size:,} rows (End − Start + 1)."
+                           if count else "No source rows to display.")
+        if self.active and count:
+            # Replace the widget's state directly. Output capture and deferred
+            # clear_output messages can accumulate displays in notebook clients.
+            preview = table_preview_html(self.df.iloc[start - 1:end])
+            self.output.outputs = ({
+                "output_type": "display_data",
+                "data": {"text/html": preview.data},
+                "metadata": {},
+            },)
+        else:
+            self.output.outputs = ()