plotaviz 0.1.0__py3-none-any.whl

plotaviz/ui/export_dialog.py

@@ -0,0 +1,228 @@
+"""The export dialog — image formats, size, DPI, or the generated Python code.
+
+Exporting code sits in the same dialog as exporting an image on purpose. Reproducibility is a
+headline feature, not a hidden menu item, and putting the two side by side makes "you can take
+the script with you" discoverable.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PySide6.QtWidgets import (
+    QCheckBox,
+    QComboBox,
+    QDialog,
+    QDialogButtonBox,
+    QDoubleSpinBox,
+    QFileDialog,
+    QFormLayout,
+    QGroupBox,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QPushButton,
+    QRadioButton,
+    QSpinBox,
+    QVBoxLayout,
+    QWidget,
+)
+
+from ..core.exporter import DEFAULT_DPI, ExportOptions
+
+#: Image formats offered, with a note on when each is the right choice.
+_FORMATS = (
+    ("png", "PNG — raster, good for slides and documents"),
+    ("svg", "SVG — vector, scales without blurring"),
+    ("pdf", "PDF — vector, best for print and LaTeX"),
+    ("jpg", "JPEG — smaller files, lossy"),
+    ("webp", "WebP — small raster files for the web"),
+)
+
+
+class ExportDialog(QDialog):
+    """Collects export settings.
+
+    Args:
+        parent: Parent widget.
+        default_name: Suggested file stem, usually derived from the dataset name.
+        start_dir: Directory the file picker opens in.
+    """
+
+    def __init__(
+        self,
+        parent: QWidget | None = None,
+        *,
+        default_name: str = "chart",
+        start_dir: str | Path = ".",
+    ) -> None:
+        super().__init__(parent)
+        self.setWindowTitle("Export")
+        self.setMinimumWidth(520)
+        self._start_dir = Path(start_dir)
+        self._default_name = default_name
+
+        layout = QVBoxLayout(self)
+
+        # --- what to export
+        what = QGroupBox("What to export", self)
+        what_layout = QVBoxLayout(what)
+        self.image_radio = QRadioButton("Image of the chart", what)
+        self.image_radio.setChecked(True)
+        self.code_radio = QRadioButton("Python code that reproduces it", what)
+        self.html_radio = QRadioButton("Interactive HTML page", what)
+        for radio in (self.image_radio, self.code_radio, self.html_radio):
+            radio.toggled.connect(self._sync_enabled)
+            what_layout.addWidget(radio)
+        code_note = QLabel(
+            "The generated script is standalone — it reads your data file, replays the exact "
+            "cleaning steps, and draws the chart. It does not import PlotaViz.",
+            what,
+        )
+        code_note.setWordWrap(True)
+        code_note.setStyleSheet("color: palette(mid); font-size: 11px;")
+        what_layout.addWidget(code_note)
+        layout.addWidget(what)
+
+        # --- image settings
+        self.image_box = QGroupBox("Image settings", self)
+        image_form = QFormLayout(self.image_box)
+
+        self.format_combo = QComboBox(self.image_box)
+        for value, label in _FORMATS:
+            self.format_combo.addItem(label, value)
+        self.format_combo.currentIndexChanged.connect(self._sync_enabled)
+        image_form.addRow("Format", self.format_combo)
+
+        self.dpi_spin = QSpinBox(self.image_box)
+        self.dpi_spin.setRange(72, 1200)
+        self.dpi_spin.setSingleStep(50)
+        self.dpi_spin.setValue(DEFAULT_DPI)
+        self.dpi_spin.setSuffix(" dpi")
+        image_form.addRow("Resolution", self.dpi_spin)
+
+        size_row = QHBoxLayout()
+        self.width_spin = QDoubleSpinBox(self.image_box)
+        self.width_spin.setRange(2.0, 40.0)
+        self.width_spin.setValue(10.0)
+        self.width_spin.setSuffix(" in")
+        self.height_spin = QDoubleSpinBox(self.image_box)
+        self.height_spin.setRange(2.0, 40.0)
+        self.height_spin.setValue(6.0)
+        self.height_spin.setSuffix(" in")
+        size_row.addWidget(self.width_spin)
+        size_row.addWidget(QLabel("×", self.image_box))
+        size_row.addWidget(self.height_spin)
+        size_row.addStretch(1)
+        image_form.addRow("Size", size_row)
+
+        self.transparent_check = QCheckBox("Transparent background", self.image_box)
+        image_form.addRow("", self.transparent_check)
+
+        self.notice_check = QCheckBox(
+            "Include the sampling notice when data was downsampled", self.image_box
+        )
+        self.notice_check.setChecked(True)
+        self.notice_check.setToolTip(
+            "An exported chart that hides its own sampling misleads whoever reads it. "
+            "Leave this on unless you have a reason not to."
+        )
+        image_form.addRow("", self.notice_check)
+        layout.addWidget(self.image_box)
+
+        # --- code settings
+        self.code_box = QGroupBox("Code settings", self)
+        code_form = QFormLayout(self.code_box)
+        self.flavour_combo = QComboBox(self.code_box)
+        self.flavour_combo.addItem("matplotlib — static figure, best for reports", "matplotlib")
+        self.flavour_combo.addItem("Plotly — interactive figure, best for notebooks", "plotly")
+        code_form.addRow("Library", self.flavour_combo)
+        layout.addWidget(self.code_box)
+
+        # --- destination
+        destination = QGroupBox("Save to", self)
+        dest_layout = QHBoxLayout(destination)
+        self.path_edit = QLineEdit(destination)
+        browse = QPushButton("Browse…", destination)
+        browse.clicked.connect(self._browse)
+        dest_layout.addWidget(self.path_edit, stretch=1)
+        dest_layout.addWidget(browse)
+        layout.addWidget(destination)
+
+        buttons = QDialogButtonBox(
+            QDialogButtonBox.StandardButton.Save | QDialogButtonBox.StandardButton.Cancel, self
+        )
+        buttons.accepted.connect(self.accept)
+        buttons.rejected.connect(self.reject)
+        layout.addWidget(buttons)
+
+        self._sync_enabled()
+
+    # ------------------------------------------------------------------ behaviour
+
+    @property
+    def mode(self) -> str:
+        """``"image"``, ``"code"``, or ``"html"``."""
+        if self.code_radio.isChecked():
+            return "code"
+        if self.html_radio.isChecked():
+            return "html"
+        return "image"
+
+    def _suggested_suffix(self) -> str:
+        """The extension implied by the current mode and format."""
+        if self.mode == "code":
+            return ".py"
+        if self.mode == "html":
+            return ".html"
+        return "." + str(self.format_combo.currentData())
+
+    def _sync_enabled(self, *_: object) -> None:
+        """Enable only the settings that apply to the selected mode, and fix the extension."""
+        is_image = self.mode == "image"
+        self.image_box.setEnabled(is_image)
+        self.code_box.setEnabled(self.mode == "code")
+
+        raster = str(self.format_combo.currentData()) in {"png", "jpg", "jpeg", "webp", "tiff"}
+        self.dpi_spin.setEnabled(is_image and raster)
+
+        current = self.path_edit.text().strip()
+        stem = Path(current).stem if current else self._default_name
+        parent = Path(current).parent if current else self._start_dir
+        self.path_edit.setText(str(Path(parent) / f"{stem}{self._suggested_suffix()}"))
+
+    def _browse(self) -> None:
+        """Open a save dialog seeded with the current path."""
+        suffix = self._suggested_suffix()
+        chosen, _ = QFileDialog.getSaveFileName(
+            self,
+            "Export",
+            self.path_edit.text() or str(self._start_dir / f"{self._default_name}{suffix}"),
+            f"*{suffix}",
+        )
+        if chosen:
+            self.path_edit.setText(chosen)
+
+    # ------------------------------------------------------------------ results
+
+    def path(self) -> Path:
+        """The destination the user chose, with the right extension enforced."""
+        raw = self.path_edit.text().strip() or f"{self._default_name}{self._suggested_suffix()}"
+        target = Path(raw).expanduser()
+        if target.suffix.lower() != self._suggested_suffix():
+            target = target.with_suffix(self._suggested_suffix())
+        return target
+
+    def options(self) -> ExportOptions:
+        """Image settings as an :class:`~plotaviz.core.exporter.ExportOptions`."""
+        return ExportOptions(
+            dpi=self.dpi_spin.value(),
+            width=self.width_spin.value(),
+            height=self.height_spin.value(),
+            transparent=self.transparent_check.isChecked(),
+            include_notice=self.notice_check.isChecked(),
+        )
+
+    def flavour(self) -> str:
+        """``"matplotlib"`` or ``"plotly"`` for code export."""
+        return str(self.flavour_combo.currentData())

plotaviz/ui/filter_panel.py

@@ -0,0 +1,273 @@
+"""The filter panel — per-column widgets plus a raw pandas-query bar.
+
+Filters are :class:`~plotaviz.core.preprocess.Step` objects, exactly like the cleaning steps.
+That is not a detail: because a filter *is* a pipeline step, it serializes into sessions and
+appears in generated code for free, with no separate code path and no chance of the exported
+script disagreeing with what is on screen.
+
+Re-rendering is debounced. Dragging a range slider fires continuously, and re-running a pipeline
+plus a chart on every pixel is how an app earns a reputation for being slow.
+"""
+
+from __future__ import annotations
+
+from PySide6.QtCore import QTimer, Signal
+from PySide6.QtWidgets import (
+    QCheckBox,
+    QDateEdit,
+    QDoubleSpinBox,
+    QFormLayout,
+    QGroupBox,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QListWidget,
+    QListWidgetItem,
+    QPushButton,
+    QScrollArea,
+    QVBoxLayout,
+    QWidget,
+)
+
+from ..core.preprocess import ColumnFilter, QueryFilter, Step
+from ..core.profiler import BOOLEAN, CATEGORICAL, DATETIME, NUMERIC, DatasetProfile
+
+#: Milliseconds of quiet before a filter change triggers a re-render.
+DEBOUNCE_MS = 350
+
+#: Categorical columns with more distinct values than this get a search box instead of a list.
+MAX_LISTED_CATEGORIES = 200
+
+
+class FilterPanel(QWidget):
+    """Builds filter widgets from a dataset profile.
+
+    Signals:
+        filters_changed: Emitted with a list of filter steps after the debounce interval.
+    """
+
+    filters_changed = Signal(list)
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        super().__init__(parent)
+        self._profile: DatasetProfile | None = None
+        self._numeric: dict[str, tuple[QDoubleSpinBox, QDoubleSpinBox]] = {}
+        self._categorical: dict[str, QListWidget] = {}
+        self._datetime: dict[str, tuple[QDateEdit, QDateEdit]] = {}
+        self._boolean: dict[str, QCheckBox] = {}
+
+        self._debounce = QTimer(self)
+        self._debounce.setSingleShot(True)
+        self._debounce.setInterval(DEBOUNCE_MS)
+        self._debounce.timeout.connect(self._emit_filters)
+
+        outer = QVBoxLayout(self)
+        outer.setContentsMargins(8, 8, 8, 8)
+
+        # --- free-text pandas query
+        query_box = QGroupBox("Query", self)
+        query_layout = QVBoxLayout(query_box)
+        self.query_edit = QLineEdit(self)
+        self.query_edit.setPlaceholderText("revenue > 1000 and region == 'EMEA'")
+        self.query_edit.setClearButtonEnabled(True)
+        self.query_edit.returnPressed.connect(self._emit_filters)
+        query_layout.addWidget(self.query_edit)
+        hint = QLabel("pandas query syntax. Press Enter to apply.", self)
+        hint.setStyleSheet("color: palette(mid); font-size: 11px;")
+        query_layout.addWidget(hint)
+        self.query_error = QLabel("", self)
+        self.query_error.setWordWrap(True)
+        self.query_error.setStyleSheet("color: #C0392B; font-size: 11px;")
+        self.query_error.hide()
+        query_layout.addWidget(self.query_error)
+        outer.addWidget(query_box)
+
+        # --- per-column widgets, scrollable
+        self._scroll = QScrollArea(self)
+        self._scroll.setWidgetResizable(True)
+        self._container = QWidget()
+        self._container_layout = QVBoxLayout(self._container)
+        self._container_layout.setContentsMargins(0, 0, 0, 0)
+        self._container_layout.addStretch(1)
+        self._scroll.setWidget(self._container)
+        outer.addWidget(self._scroll, stretch=1)
+
+        buttons = QHBoxLayout()
+        self.clear_button = QPushButton("Clear all filters", self)
+        self.clear_button.clicked.connect(self.clear)
+        buttons.addWidget(self.clear_button)
+        buttons.addStretch(1)
+        outer.addLayout(buttons)
+
+    # ------------------------------------------------------------------ population
+
+    def set_profile(self, profile: DatasetProfile) -> None:
+        """Rebuild the per-column widgets for a dataset."""
+        self._profile = profile
+        self._numeric.clear()
+        self._categorical.clear()
+        self._datetime.clear()
+        self._boolean.clear()
+
+        while self._container_layout.count():
+            item = self._container_layout.takeAt(0)
+            widget = item.widget()
+            if widget is not None:
+                widget.deleteLater()
+
+        for name, prof in profile.columns.items():
+            if prof.is_derived or prof.is_identifier:
+                continue
+            if prof.role == NUMERIC:
+                self._container_layout.addWidget(self._numeric_widget(name, prof))
+            elif prof.role == DATETIME:
+                self._container_layout.addWidget(self._datetime_widget(name, prof))
+            elif prof.role == BOOLEAN:
+                self._container_layout.addWidget(self._boolean_widget(name))
+            elif prof.role == CATEGORICAL and prof.n_unique <= MAX_LISTED_CATEGORIES:
+                self._container_layout.addWidget(self._categorical_widget(name, prof))
+
+        self._container_layout.addStretch(1)
+
+    def _numeric_widget(self, name: str, prof: object) -> QWidget:
+        """A low/high pair bounded by the column's actual range."""
+        stats = getattr(prof, "stats", {}) or {}
+        low_value = float(stats.get("min", 0.0))
+        high_value = float(stats.get("max", 0.0))
+        span = high_value - low_value or 1.0
+
+        box = QGroupBox(name, self)
+        form = QFormLayout(box)
+        low = QDoubleSpinBox(box)
+        high = QDoubleSpinBox(box)
+        for spin in (low, high):
+            spin.setRange(low_value - span, high_value + span)
+            spin.setDecimals(4 if span < 10 else 2)
+            spin.setSingleStep(span / 100.0)
+            spin.valueChanged.connect(self._schedule)
+        low.setValue(low_value)
+        high.setValue(high_value)
+        form.addRow("From", low)
+        form.addRow("To", high)
+        self._numeric[name] = (low, high)
+        return box
+
+    def _datetime_widget(self, name: str, prof: object) -> QWidget:
+        """A start/end date pair."""
+        box = QGroupBox(name, self)
+        form = QFormLayout(box)
+        start, end = QDateEdit(box), QDateEdit(box)
+        for edit in (start, end):
+            edit.setCalendarPopup(True)
+            edit.setDisplayFormat("yyyy-MM-dd")
+            edit.dateChanged.connect(self._schedule)
+        form.addRow("From", start)
+        form.addRow("To", end)
+        self._datetime[name] = (start, end)
+        return box
+
+    def _boolean_widget(self, name: str) -> QWidget:
+        """A single checkbox meaning "only rows where this is true"."""
+        box = QGroupBox(name, self)
+        layout = QVBoxLayout(box)
+        check = QCheckBox("Only true", box)
+        check.stateChanged.connect(self._schedule)
+        layout.addWidget(check)
+        self._boolean[name] = check
+        return box
+
+    def _categorical_widget(self, name: str, prof: object) -> QWidget:
+        """A multi-select list of the column's values, everything selected by default."""
+        box = QGroupBox(name, self)
+        layout = QVBoxLayout(box)
+        listing = QListWidget(box)
+        listing.setSelectionMode(QListWidget.SelectionMode.MultiSelection)
+        listing.setMaximumHeight(140)
+        for value, count in getattr(prof, "top_values", []) or []:
+            item = QListWidgetItem(f"{value}  ({count:,})")
+            item.setData(0x0100, value)  # Qt.UserRole
+            listing.addItem(item)
+            item.setSelected(True)
+        listing.itemSelectionChanged.connect(self._schedule)
+        layout.addWidget(listing)
+        self._categorical[name] = listing
+        return box
+
+    # ------------------------------------------------------------------ filter building
+
+    def filters(self) -> list[Step]:
+        """Build the current filter steps.
+
+        Widgets left at their full range contribute nothing, so an untouched panel produces an
+        empty list rather than a pile of no-op steps.
+        """
+        steps: list[Step] = []
+        profile = self._profile
+
+        expression = self.query_edit.text().strip()
+        if expression:
+            steps.append(QueryFilter(expression))
+
+        for name, (low, high) in self._numeric.items():
+            prof = profile.columns.get(name) if profile else None
+            stats = getattr(prof, "stats", {}) or {}
+            full_low, full_high = float(stats.get("min", 0.0)), float(stats.get("max", 0.0))
+            if low.value() > full_low or high.value() < full_high:
+                steps.append(ColumnFilter(name, "between", [low.value(), high.value()]))
+
+        for name, (start, end) in self._datetime.items():
+            if start.date() != start.minimumDate() or end.date() != end.maximumDate():
+                steps.append(
+                    ColumnFilter(
+                        name,
+                        "between",
+                        [start.date().toString("yyyy-MM-dd"), end.date().toString("yyyy-MM-dd")],
+                    )
+                )
+
+        for name, listing in self._categorical.items():
+            selected = [item.data(0x0100) for item in listing.selectedItems()]
+            if selected and len(selected) < listing.count():
+                steps.append(ColumnFilter(name, "in", selected))
+
+        for name, check in self._boolean.items():
+            if check.isChecked():
+                steps.append(ColumnFilter(name, "in", [True]))
+
+        return steps
+
+    def clear(self) -> None:
+        """Reset every widget and emit an empty filter set."""
+        self.query_edit.clear()
+        self.query_error.hide()
+        for name, (low, high) in self._numeric.items():
+            prof = self._profile.columns.get(name) if self._profile else None
+            stats = getattr(prof, "stats", {}) or {}
+            low.setValue(float(stats.get("min", low.minimum())))
+            high.setValue(float(stats.get("max", high.maximum())))
+        for listing in self._categorical.values():
+            listing.selectAll()
+        for check in self._boolean.values():
+            check.setChecked(False)
+        self._emit_filters()
+
+    def show_query_error(self, message: str) -> None:
+        """Display a failed query message under the query bar."""
+        self.query_error.setText(message)
+        self.query_error.show()
+
+    def clear_query_error(self) -> None:
+        """Hide the query error."""
+        self.query_error.hide()
+
+    # ------------------------------------------------------------------ signalling
+
+    def _schedule(self, *_: object) -> None:
+        """Restart the debounce timer. Called by every widget's change signal."""
+        self._debounce.start()
+
+    def _emit_filters(self) -> None:
+        """Emit the current filter steps."""
+        self._debounce.stop()
+        self.clear_query_error()
+        self.filters_changed.emit(self.filters())