tablelab 0.5.0__py3-none-any.whl

tablelab/query_expressions.py

@@ -0,0 +1,91 @@
+"""Small, non-executing grammars for arithmetic and grouped filter conditions."""
+import ast
+import operator
+import re
+from functools import reduce
+
+
+_OPERATIONS = {ast.Add: ('+', operator.add), ast.Sub: ('-', operator.sub),
+               ast.Mult: ('*', operator.mul), ast.Div: ('/', operator.truediv),
+               ast.FloorDiv: ('//', operator.floordiv), ast.Mod: ('%', operator.mod)}
+
+
+def arithmetic_code(expression, columns, variable='source'):
+    try:
+        tree = ast.parse(expression, mode='eval')
+    except SyntaxError as exc:
+        raise ValueError('Enter a valid arithmetic expression.') from exc
+    if sum(1 for _ in ast.walk(tree)) > 100:
+        raise ValueError('The arithmetic expression is too long.')
+
+    def column_code(column):
+        if column not in columns:
+            raise ValueError(f'Unknown column: {column!r}')
+        return f'{variable}[{column!r}]'
+
+    def visit(node):
+        if isinstance(node, ast.Name):
+            return column_code(node.id)
+        if isinstance(node, ast.Constant) and type(node.value) in (int, float):
+            return repr(node.value)
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == 'col':
+            if len(node.args) == 1 and not node.keywords and isinstance(node.args[0], ast.Constant):
+                if type(node.args[0].value) in (str, int):
+                    return column_code(node.args[0].value)
+        if isinstance(node, ast.BinOp) and type(node.op) in _OPERATIONS:
+            return f'({visit(node.left)} {_OPERATIONS[type(node.op)][0]} {visit(node.right)})'
+        if isinstance(node, ast.UnaryOp) and isinstance(node.op, (ast.UAdd, ast.USub)):
+            sign = '+' if isinstance(node.op, ast.UAdd) else '-'
+            return f'({sign}{visit(node.operand)})'
+        raise ValueError("Use columns, numbers, parentheses, +, -, *, /, //, or %. "
+                         "Use col('column name') for names with spaces.")
+    return visit(tree.body)
+
+
+def arithmetic_value(expression, df):
+    code = arithmetic_code(expression, df.columns)
+    def visit(node):
+        if isinstance(node, ast.Constant):
+            return node.value
+        if isinstance(node, ast.Subscript):
+            return df[node.slice.value]
+        if isinstance(node, ast.BinOp):
+            return _OPERATIONS[type(node.op)][1](visit(node.left), visit(node.right))
+        return (operator.neg if isinstance(node.op, ast.USub) else operator.pos)(visit(node.operand))
+    return visit(ast.parse(code, mode='eval').body)
+
+
+def condition_tree(expression, count, mode):
+    if not expression.strip():
+        expression = (' and ' if mode == 'and' else ' or ').join(str(i + 1) for i in range(count))
+    expression = re.sub(r'\b(AND|OR)\b', lambda match: match[0].lower(), expression, flags=re.I)
+    try:
+        tree = ast.parse(expression.strip(), mode='eval').body
+    except SyntaxError as exc:
+        raise ValueError('Combine condition numbers using AND, OR, and parentheses.') from exc
+    if sum(1 for _ in ast.walk(tree)) > 100:
+        raise ValueError('The condition expression is too long.')
+    def validate(node):
+        if isinstance(node, ast.Constant) and type(node.value) is int and 1 <= node.value <= count:
+            return
+        if isinstance(node, ast.BoolOp) and isinstance(node.op, (ast.And, ast.Or)):
+            for value in node.values:
+                validate(value)
+            return
+        raise ValueError(f'Use condition numbers 1–{count}, AND, OR, and parentheses.')
+    validate(tree)
+    return tree
+
+
+def combine_code(tree):
+    if isinstance(tree, ast.Constant):
+        return f'masks[{tree.value - 1}]'
+    symbol = ' & ' if isinstance(tree.op, ast.And) else ' | '
+    return '(' + symbol.join(combine_code(value) for value in tree.values) + ')'
+
+
+def combine_masks(tree, masks):
+    if isinstance(tree, ast.Constant):
+        return masks[tree.value - 1]
+    operation = operator.and_ if isinstance(tree.op, ast.And) else operator.or_
+    return reduce(operation, (combine_masks(value, masks) for value in tree.values))

tablelab/table.py

@@ -0,0 +1,128 @@
+"""What is in the table: the label column, the plottable columns, a summary.
+
+Kept apart from both the widgets and the chart so the same answers are available
+from a notebook cell, from the app, and from the CLI.
+"""
+import pandas as pd
+
+# Column names that mean "this is the class, not a measurement".
+LABEL_NAMES = ("label", "class", "target", "y", "activity", "diagnosis")
+
+# A headerless last column with no more distinct values than this is taken for a
+# label. Generous enough for the UCR archive's 5-class sets, tight enough that a
+# genuine measurement column is not mistaken for one.
+MAX_LABEL_LEVELS = 20
+
+
+def find_label_column(df: pd.DataFrame):
+    """Return the label column's name, or None if the table has no label."""
+    for c in df.columns:
+        if str(c).strip().lower() in LABEL_NAMES:
+            return c
+
+    # Headerless table: columns are positions, so a name cannot say which is the
+    # label. A last column with few distinct values almost always is one.
+    if not any(isinstance(c, str) for c in df.columns) and df.shape[1] > 2:
+        last = df.columns[-1]
+        if df[last].nunique() <= MAX_LABEL_LEVELS:
+            return last
+    return None
+
+
+def label_name(label_col) -> str:
+    """Display name for the label column - a headerless one is just 'label'."""
+    return label_col if isinstance(label_col, str) else "label"
+
+
+def numeric_columns(df: pd.DataFrame, exclude=None):
+    """Columns that can be plotted, with the label column left out."""
+    cols = df.select_dtypes("number").columns
+    return [c for c in cols if c != exclude]
+
+
+def column_choices(df: pd.DataFrame, exclude=None):
+    """Every column a user may pick, numeric or not - the label included.
+
+    A table of file names and ids has no numeric column at all; listing only
+    the plottable ones would leave the menu empty and the header looking lost.
+    The label is listed too: counting its classes is a fair thing to inspect.
+    """
+    return [c for c in df.columns if c != exclude]
+
+
+def is_numeric(series: pd.Series) -> bool:
+    return pd.api.types.is_numeric_dtype(series) and not pd.api.types.is_bool_dtype(series)
+
+
+def data_type(series: pd.Series) -> str:
+    """Readable type of a selected series, alongside its pandas dtype in the UI."""
+    dtype = series.dtype
+    if pd.api.types.is_bool_dtype(dtype):
+        return "Boolean"
+    if is_numeric(series):
+        return "Numeric"
+    if isinstance(dtype, pd.CategoricalDtype):
+        return "Categorical"
+    if pd.api.types.is_datetime64_any_dtype(dtype):
+        return "Date/time"
+    if pd.api.types.is_timedelta64_dtype(dtype):
+        return "Duration"
+    inferred = pd.api.types.infer_dtype(series.dropna(), skipna=True)
+    return "Text" if inferred in {"string", "unicode", "bytes"} else "Mixed / object"
+
+
+def resolve_column(df: pd.DataFrame, key):
+    """Accept either a column name or a positional index like 0 or -1."""
+    if key in df.columns:
+        return key
+    try:
+        return df.columns[int(key)]
+    except (ValueError, TypeError, IndexError):
+        raise KeyError(f"no column {key!r} in this table")
+
+
+def row_series(df: pd.DataFrame, row: int, label_col=None) -> pd.Series:
+    """One row as a signal: numeric columns only, label dropped."""
+    cols = numeric_columns(df, exclude=label_col)
+    return df[cols].iloc[row]
+
+
+def describe(df: pd.DataFrame) -> str:
+    """One-paragraph summary of the table, for printing above the chart."""
+    label_col = find_label_column(df)
+    lines = [f"{df.shape[0]} rows x {df.shape[1]} columns"]
+    if label_col is None:
+        lines.append("no label column detected")
+    else:
+        counts = df[label_col].value_counts().sort_index()
+        shown = ", ".join(f"{k}: {v}" for k, v in list(counts.items())[:8])
+        if len(counts) > 8:
+            shown += ", ..."
+        lines.append(f"label column {label_name(label_col)!r} -> {shown}")
+    return "\n".join(lines)
+
+
+def summary_stats(values) -> pd.DataFrame:
+    """One series as a one-row table of the numbers a chart cannot be read off.
+
+    A chart shows shape and order; the quartiles, the spread and the skew are
+    what someone squints at a chart trying to estimate, so they are printed
+    alongside it rather than guessed.
+    """
+    s = pd.Series(values).astype(float)
+    clean = s.dropna()
+    q1, med, q3 = (clean.quantile(q) for q in (0.25, 0.5, 0.75))
+    return pd.DataFrame([{
+        "n": len(clean),
+        "missing": int(s.isna().sum()),
+        "mean": clean.mean(),
+        "std": clean.std(),
+        "min": clean.min(),
+        "25%": q1,
+        "median": med,
+        "75%": q3,
+        "max": clean.max(),
+        "IQR": q3 - q1,
+        "skew": clean.skew(),
+        "kurtosis": clean.kurt(),
+    }])

tablelab-0.5.0.dist-info/METADATA

@@ -0,0 +1,465 @@
+Metadata-Version: 2.5
+Name: tablelab
+Version: 0.5.0
+Summary: Notebook GUI for table inspection, query pipelines, charts, and Pandas/PySpark/Spark SQL code generation
+Project-URL: Homepage, https://github.com/rberangi/tablelab
+Project-URL: Source, https://github.com/rberangi/tablelab
+Project-URL: Issues, https://github.com/rberangi/tablelab/issues
+Author-email: Reza Berangi <rberangi@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data inspection,ipywidgets,jupyter,pandas,pyspark,query,sql,table,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Requires-Dist: certifi>=2024.2.2
+Requires-Dist: ipywidgets>=8.0
+Requires-Dist: matplotlib>=3.9
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: sqlglot>=25
+Provides-Extra: all
+Requires-Dist: ipympl>=0.9; extra == 'all'
+Requires-Dist: openpyxl; extra == 'all'
+Requires-Dist: pyarrow; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: duckdb>=1; extra == 'dev'
+Requires-Dist: jupyterlab; extra == 'dev'
+Requires-Dist: nbconvert; extra == 'dev'
+Requires-Dist: nbformat; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: sqlglot>=25; extra == 'dev'
+Provides-Extra: excel
+Requires-Dist: openpyxl; extra == 'excel'
+Provides-Extra: parquet
+Requires-Dist: pyarrow; extra == 'parquet'
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == 'release'
+Requires-Dist: twine>=5; extra == 'release'
+Provides-Extra: zoom
+Requires-Dist: ipympl>=0.9; extra == 'zoom'
+Description-Content-Type: text/markdown
+
+# tablelab
+
+Current release: **0.5.0**.
+
+TableLab is a notebook GUI for exploring and transforming tables. Select columns,
+filter rows, join tables, create grouped summaries, handle missing values, and
+build saved query pipelines. Inspect columns with statistics and plots, then
+export pandas, PySpark, or SQL code from the same settings.
+
+Start with `examples/tablelab_queries.ipynb` or launch `query_main()` below.
+The separate `main()` API remains available for column and row chart inspection.
+
+## New in 0.5.0
+
+- Join previews colour left columns blue, right columns orange, and shared keys
+  purple, with a visible legend. Key selections survive pipeline refreshes when
+  their columns still exist.
+- Saving a Join switches to Select with all result columns selected, preventing
+  the next preview from repeating the same join accidentally.
+- Select shows **Input rows** and **Distinct rows** beside Ascending. Distinct
+  counts use the selected columns and calculations, before Limit and Offset.
+- **Inspect a column → Encode categories** displays a category-to-code mapping
+  and supports individual plots, scatter comparisons, and two curves versus
+  samples. Codes follow first appearance in the full source and remain stable
+  when changing the inspection range. Missing values stay missing; source data
+  is unchanged. Codes are labels, so their distances and averages have no
+  statistical interpretation.
+- Green **Run pipeline** and blue preview buttons distinguish saved-pipeline
+  execution from the current settings. Fill value appears beside Action.
+- `examples/data/test_table1.csv` and `test_table2.csv` demonstrate all four joins;
+  select `order_id` as the key in both tables.
+
+## Preview and save steps
+
+| Control | Behaviour |
+|---|---|
+| **Apply and preview result** | Apply the current tab settings to the current pipeline input, without saving a step. |
+| **Add step** | Save the current operation and use its result as the input for the next operation. |
+| **Preview up to this step** | Run saved steps from the beginning through the highlighted step. |
+| **Run pipeline** | Run all saved steps, ignoring unsaved tab settings. |
+| **Edit step** | Restore a saved step's tab and settings; use Save changes or Cancel edit afterward. |
+
+Selecting an entry in the step list highlights it; use **Edit step** to restore
+its settings. Previews do not change the original source tables. After installing
+an update, restart the notebook kernel and rerun the launcher to replace an old GUI.
+
+## Install
+
+Install the local 0.5.0 release from the project folder:
+
+```bash
+python -m pip install dist/tablelab-0.5.0-py3-none-any.whl
+```
+
+In a notebook, use `%pip install /full/path/to/tablelab-0.5.0-py3-none-any.whl`
+in the selected kernel, then restart it. Launch the query GUI with:
+
+```python
+import tablelab
+from tablelab import query_main
+
+print(tablelab.__version__)
+app = query_main()
+```
+
+`from tablelab import main` continues to launch the column/row chart GUI.
+For installation from the package index, use:
+
+```bash
+pip install tablelab
+```
+
+Optional readers and the pan/zoom toolbar are extras:
+
+```bash
+pip install "tablelab[all]"
+```
+
+SQL code generation dependencies, including `sqlglot`, are installed automatically
+with TableLab. In Jupyter, use `%pip` so installation targets the active notebook
+kernel. To install the current source checkout and its dependencies, run:
+
+```python
+%pip install -e /full/path/to/tablelab
+```
+
+Restart the kernel after installation and relaunch TableLab. Existing release
+wheels keep the dependencies recorded when they were built; rebuild the wheel
+after changing `pyproject.toml` before distributing the updated package.
+
+**Inspect a column** has independent Start row and End row controls (inclusive,
+starting at 1). It initially inspects the first 100 rows; **Show all** selects the
+full source. Statistics, categorical counts, and comparison plots use this range.
+This reduces inspection work; the full source table remains loaded in memory.
+
+| Extra | Adds |
+|---|---|
+| `excel` | `.xlsx`, `.xls` |
+| `parquet` | `.parquet`, `.feather`, `.arrow` |
+| `zoom` | pan/zoom toolbar on the run chart |
+| `all` | all of the above |
+
+## After installing
+
+tablelab is a widget app, so it runs inside a notebook — not in a plain Python
+script.
+
+**1. Open a notebook** in the same Python environment you installed into:
+
+```bash
+pip install jupyterlab      # skip if you already have Jupyter
+jupyter lab
+```
+
+VS Code works too: create a `.ipynb` file and select that Python as the kernel.
+
+**2. Start the app** in a notebook cell:
+
+```python
+from tablelab import main
+
+app = main()                      # load a file from the UI
+# app = main("data/ecg.csv")      # or open on a file
+```
+
+`app.df` is the active DataFrame, so you can keep working on it in the next cell.
+Each load adds a table to the **table:** menu. Switch between loaded tables
+without reading them again, or use **Remove table** to remove the selected one.
+Adding the same disk path again selects its existing table. Uploads are kept
+separately, even when their filenames match. Switching tables resets the column,
+label filter, and row selection. Loaded tables stay in memory for the app session.
+
+For the shortest route, open `examples/tablelab_queries.ipynb` and run its GUI
+cell. The release example is a portable notebook with no saved outputs.
+
+For joins and queries, use the same `examples/tablelab_queries.ipynb`.
+Its GUI supports left/inner/right/outer joins (including multiple matching keys),
+column filters, and grouped counts, sums, means, medians, minima, and maxima.
+The **Select** tab beside **Join** provides SQL-like column selection,
+**Distinct rows**, **Order by** (ascending or descending), **Limit**, and **Offset**.
+All columns are selected initially; limit 0 keeps all remaining rows. Sorting
+columns must be included in the output. Use **Add step** to combine filtering,
+joining, selection, grouping, and missing-value handling in a pipeline.
+**Show code** includes file loading and the matching pandas selection.
+In **Select**, click **Add column alias** to rename an output column. Click
+**Add calculated column** to enter a new name and an expression such as
+`price * quantity` or `total * (1 - 0.1)`. Calculations run in row order, can
+reference earlier calculated columns, and are included in the output. Use
+`col('unit price')` for a column name with spaces, or `col(0)` for an integer
+column name. Expressions support numbers, parentheses, `+`, `-`, `*`, `/`,
+`//`, and `%`. Choose sorting columns by their original or calculated names;
+aliases are applied after sorting. Duplicate output names are rejected.
+
+In **Filter**, the original condition is number 1. Use **Add condition** for
+more rows and choose **All (AND)**, **Any (OR)**, or **Custom grouping**.
+Only **Custom grouping** enables the **Grouping** field, which requires an
+expression such as `1 AND (2 OR 3)`. All/Any ignores the inactive field. Removing a condition
+renumbers the remaining rows, so update explicit grouping if necessary.
+All three additions are included in **Show code**. Source tables are
+unchanged; changing editor input resets draft aliases, calculations, and extra
+conditions. Saved pipeline steps keep their settings.
+
+The **Missing values** tab previews missing counts and percentages for selected
+columns. Choose **Remove rows** to drop rows where any or all selected values
+are missing, **Fill with a fixed value**, or **Fill with median**. These actions
+preserve the source and are included in **Show code**. Median filling
+requires numeric columns and leaves entirely missing columns unchanged; nullable
+integer columns are promoted to nullable floating point when the median is
+fractional. Fixed values are converted to each affected column's type (use
+`true`/`false` for Boolean columns); blank strings are ordinary values. Only
+selected columns are cleaned. Use **Add step** to continue querying the cleaned
+result, or **Add as new table** to keep a separate table.
+
+The **Query pipeline** panel stores operations in order. Configure a tab, then
+click **Add step**: its output becomes the input for the next operation, without
+creating an intermediate table. **Apply and preview result** previews the current
+unsaved settings; **Run pipeline** previews all saved steps. Select a step and
+use **Preview selected step** to inspect that stage. **Edit step** loads its saved
+settings against the preceding stage; **Save changes** recomputes later steps,
+and **Cancel edit** restores the saved pipeline. You can move steps up/down,
+remove them, or clear the pipeline. If an upstream change removes a column used
+later, the affected steps are marked **needs update** with a specific error;
+edit the first failing step to choose available columns.
+
+**Show pipeline code** generates code in the selected output language for saved steps,
+including the original source and right-table reads. **Show code** includes
+the saved prefix and the current draft (while editing, through the edited step).
+Pipelines are kept separately for each loaded source for the current app session.
+Saved joins retain their right input if it is removed from the table menu.
+**View source table**, **Inspect a column**, and **Save source as CSV** continue
+to use the original source. The operation controls and `app.df` use the current
+pipeline input. **Add as new table** keeps whichever result is being previewed.
+
+The shared **Column** selector chooses the column for filtering and grouped
+summaries. The selected column is shaded in the result preview; grouped summaries
+shade the calculated column. Numeric summaries require a numeric column.
+Preview the result, then add it as a new table to chain operations. A **Remove table**
+button sits beside the source selector. To export the selected source, click **Save source as CSV**, browse to a
+destination folder, enter a filename, and click **Save**. This saves all rows
+and columns as UTF-8 CSV without the DataFrame index, regardless of the preview
+range. Paths refer to the notebook kernel’s filesystem; existing files are kept
+and require a different destination name. The notebook includes optional Customers
+and Orders sample tables. Source tables stay unchanged;
+the full previewed result is available as `app.result`.
+Expand **View source table** to browse source rows. Open the separate
+**Inspect a column** section to inspect individual columns with the chart GUI's numeric charts, data type selector, summary statistics, and
+categorical value counts. Column inspection uses the full source table and does
+not change the query settings or result. The standalone chart notebook also
+supports inspecting rows as signals.
+The **Source table** panel lets you browse the entire selected source using
+Start row and End row fields that show the current page boundaries and update
+with Previous/Next. Page size is End row − Start row + 1, initially up to 100.
+Editing either field resizes the page; Previous/Next retains that size, including
+after a shorter final page. It shares the loaded table and renders only the
+current page; collapsed panels render no table
+HTML. The selected source range only controls the preview, not the query input.
+After applying a query, use the Start row and End row fields to choose which
+result rows to preview, or use Previous/Next to page through the result.
+Paging retains the selected page size, including after a shorter final page.
+Positions start at 1 and include
+both endpoints. The initial preview shows up to 100 rows so large results appear
+quickly. Column headers stay visible at the top while scrolling source and result
+previews. Change the row range to view other rows; adding the result as a table
+retains every result row, regardless of the preview range.
+
+The implementation helpers are also available under `tablelab.helpers` for a
+notebook that needs to build on the supplied GUI:
+
+```python
+from tablelab.helpers import load_table, run_chart, summary_stats
+```
+
+## The UI
+
+| control | what it does |
+|---|---|
+| **Browse...** | a file dialog over the folders the kernel can see |
+| path box + **Add table** | the same, by typing, when the path is already known |
+| **table:** | switch between loaded tables |
+| **Remove table** | remove the selected table |
+| **Upload** | for a file on your machine when the kernel is on another one |
+| **Column / Row** | which direction the series runs in |
+| **column:** | the menu of all the table's columns; the data type box sits after it |
+| **Data type** | automatically selects Numeric or Categorical; numeric columns can be viewed as categories |
+| drawing tabs | run chart, sorted run chart, histogram, box plot or ECDF; numeric data only |
+| **centre:** | the dashed reference line — median, mean, or none |
+| **grid lines** | vertical grid lines as well as the horizontal ones |
+
+Above the chart is a toolbar that pans and zooms. **First rows** folds out above
+the column and row selections; **Summary statistics** folds out below the chart.
+The data type selector automatically chooses Numeric or Categorical when you
+select a column, and shows its pandas dtype. For numeric columns such as class
+codes, choose Categorical to see value counts, or switch back to Numeric for
+drawings. This changes the view without changing the underlying data. Selecting
+another column or table restores automatic detection. Other data uses the
+categorical view; the tooltip shows its detected type.
+Numeric data offers drawing tabs for Run chart, Sorted run chart, Histogram,
+Box plot, and ECDF. Other data shows value counts and hides the drawing controls.
+
+The toolbar comes from `ipympl` (`pip install "tablelab[zoom]"`). Without it the
+chart is a static image and everything else still works. Because switching
+matplotlib backends affects the whole notebook, `main(zoom=False)` leaves it
+alone.
+
+Ticking **grid lines** applies the grid to the figure on screen rather than
+redrawing it, so it does not throw away a zoom you are in the middle of.
+
+### Browse or Upload
+
+**Browse...** lists the filesystem the *kernel* can see, which is the right one
+for local work and for a notebook on a server — the file is read where it
+already is, at any size. **Upload** copies a file through the browser instead,
+for when the kernel is somewhere the file is not. The dialog is built from
+widgets rather than a native file chooser on purpose: a native one opens on the
+machine running the kernel, which over SSH or in a container is not the machine
+you are looking at.
+
+## Label detection
+
+tablelab looks for the label column in two passes:
+
+1. A column named `label`, `class`, `target`, `y`, `activity` or `diagnosis`
+   (case-insensitive).
+2. Failing that, and only for a **headerless** table: the last column, if it has
+   at most 20 distinct values. Headerless tables name their columns by position,
+   so nothing else can say which one is the label.
+
+`describe(df)` prints which column it picked and the class counts, so the guess
+is always visible rather than silent. In the CLI, `--label-col` overrides it.
+
+Headerless files are detected too: if every field in the first row parses as a
+number, that row is data, and pandas is told not to take it for column names.
+Without this, ECG5000 quietly loses its first beat.
+
+## Without widgets
+
+The reading, the label detection and the chart are plain functions — the app is
+only a shell around them:
+
+```python
+from tablelab import load_table, find_label_column, describe, summary_stats
+from tablelab import run_chart, sorted_run_chart, histogram, box_plot, ecdf, draw
+
+df = load_table("data/ecg.csv")
+print(describe(df))                       # 4998 rows x 141 columns, label -> ...
+run_chart(df.iloc[0, :-1], title="beat 0")
+histogram(df["rr"], ylabel="rr", grid=True)
+draw("ecdf", df["rr"], ylabel="rr")       # by the key the chart menu uses
+summary_stats(df["rr"])                   # quartiles, spread, skew, as a table
+```
+
+There is a command line front end for the same thing:
+
+```bash
+python -m tablelab data/ecg.csv --list
+python -m tablelab data/ecg.csv --row 0
+python -m tablelab data/ecg.csv --col temperature --chart histogram --grid
+python -m tablelab data/ecg.csv --col temperature --out chart.png
+```
+
+## The charts
+
+Five views of the one series, all with the same furniture:
+
+| chart | what it answers |
+|---|---|
+| Run chart | how the values move in order — drift, steps, cycles |
+| Sorted run chart | the range, the gaps, how far the extremes sit from the body |
+| Histogram | where the values sit, order thrown away |
+| Box plot | median, quartiles, whiskers and the points outside them |
+| ECDF | the proportion at or below each value, with nothing binned away |
+
+One series, so one hue and no legend — the title names the series, and the
+median line is labelled where it sits. `centre="mean"` switches the reference
+line; `centre=None` removes it; a box plot draws its own median and ignores it.
+Markers appear only when there are at most 60 points, past which they stop
+carrying information and only thicken the line.
+
+`grid` is three-valued rather than a flag: `"y"` is the run chart's own grid and
+the default, `True` adds the vertical lines the app's checkbox asks for, and
+`False` takes both away.
+
+## License
+
+MIT
+
+Choose **Code output: Pandas / PySpark / Spark SQL / MySQL / PostgreSQL / SQLite / DuckDB**, then **Show code** for the
+saved prefix plus current settings, or **Show pipeline code** for saved steps only.
+Generated code appears in the preview window with instructions for where to run it.
+Use **Copy code** to copy the displayed code. If your notebook blocks clipboard
+access or JavaScript output, select the code and copy it manually. Changing the
+output language or query settings clears old code so it cannot be copied by mistake.
+PySpark exports include a Spark
+session, file reads with schemas, transformations, and result display. SQL exports
+include temporary input views and a query with named steps. Both cover Select,
+Join, Filter, Group & summarise, and Missing values.
+
+Database SQL exports target **MySQL 8+**, **PostgreSQL**, **SQLite 3.39+**, or
+**DuckDB**. Import each listed source file into its named `tablelab_input_0`,
+`tablelab_input_1`, etc. table before running the generated query in a SQL editor.
+Keep the original column names and types, and load missing values as SQL NULL.
+These exports include projections, aliases, calculations, DISTINCT, sorting,
+pagination, joins, filters, grouped summaries, and missing-value handling, composed
+as named query steps (CTEs). They do not connect to a database or import files.
+MySQL full outer joins and median operations in MySQL, PostgreSQL, and SQLite
+currently report an export error; use DuckDB or Spark SQL for those settings.
+Database sorting/collation, arithmetic, and timestamps can differ from pandas.
+
+Previews still run locally with pandas; exporting code does not run Spark or
+require PySpark to be installed in TableLab. Run exports in a **Spark 3.5+**
+environment and review file paths, schema types, CSV null tokens, and timezone
+settings. CSV/TSV, Parquet, and line-delimited JSON have native readers. Other
+formats and in-memory tables include instructions to export a CSV first. Spark
+has no pandas index or guaranteed row order; use unique sorting keys when
+LIMIT/OFFSET must be reproducible. Inputs normalize numeric NaN to NULL and joins
+use null-safe equality. Arithmetic, overflow, and division by zero follow Spark
+settings. Unsupported mixed/nested or timedelta columns report an export error.
+
+The file path field also accepts direct **HTTP/HTTPS table download URLs**, such as
+`https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv`.
+Paste the URL and click **Add table**. With an empty field, **Add table** opens the
+file picker. Web page links are rejected with a message requesting a direct file
+link. URL data is downloaded into memory, like a local source. Pandas exports
+retain the URL; Spark exports instruct you to download the file first.
+
+HTTPS loading supplements Python's default trusted certificates with the
+`certifi` bundle while retaining certificate and hostname verification. If an
+older notebook environment reports `CERTIFICATE_VERIFY_FAILED`, run
+`%pip install --upgrade certifi` in that notebook and restart its kernel.
+Networks using private CAs can supply a trusted bundle through `SSL_CERT_FILE`.
+
+In **Group & summarise**, select the grouping columns, then select a column in
+**Key order** and click **Move up** or **Move down**. The chosen sequence controls
+the grouping columns in the result and in Pandas, PySpark, and Spark SQL exports;
+saved steps retain it when edited. Grouping-key order does not sort result rows.
+To sort a grouped result, add the grouping step, then add a **Select** step with
+**Order by** configured.
+
+**Group & summarise** also has an optional **Summary alias** field. For example,
+group by `sex`, choose **Sum** on `total_bill`, and enter `total_bills` to produce
+one total per sex with that column name. Leave the alias blank to use the default
+name (`total_bill_sum` or `row_count`). Aliases are preserved in saved steps and
+all code exports, and must differ from grouping column names.
+
+To explore a relationship, open **Inspect a column** and enable **Compare columns**.
+The existing column selector becomes **Column (Y)** and **Against (X)** selects
+the second numeric column. For the tips data, select `tip` on Y and `total_bill`
+on X. Choose **Scatter (Y vs X)** or **Two curves vs samples** in **View**.
+Both replace the single-column view in the same chart area; disable the switch
+to return to the usual charts and statistics. The two-curve view uses sample
+positions starting at 1 in source row order, with a legend and a shared value
+axis. Missing values leave gaps independently in each curve. Each scatter point
+is one source row. Missing or infinite pairs are skipped; large plots show up to
+5,000 points sampled evenly by row position, with counts displayed above the
+plot. Comparing columns does not change query settings or results.
+
+Version information is available through `tablelab.__version__` and
+`python -m tablelab --version` (or `tablelab --version`). See
+[CHANGELOG.md](CHANGELOG.md) for release changes and
+[RELEASING.md](RELEASING.md) for versioning and build instructions.