trendify2 2.0.4__py3-none-any.whl

trendify/__about__.py

@@ -0,0 +1,14 @@
+"""Looks up the installed version of this package."""
+
+from datetime import date
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("trendify2")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"
+
+__license__ = "MIT"
+__summary__ = "Tools for generating data products, storing, and interacting with them."
+__copyright__ = f"© {date.today().year} Talbot Knighton and David Gable"
+__url__ = "https://github.com/Hydrowelder/trendify"

trendify/__init__.py

@@ -0,0 +1,250 @@
+"""
+Tools for generating, storing, and interacting with tagged records (points, traces, tables,
+histograms) produced by batch-processing many run directories.
+
+Write a `RecordGenerator` that returns records for one run directory, run it over many runs
+with [`TrendifyPipeline`][trendify.pipeline.TrendifyPipeline] or the `trendify` CLI, then browse
+the results in the viewer or render them as plots and tables.
+"""
+
+from trendify import (
+    base,
+    cli,
+    color,
+    examples,
+    formats,
+    generator,
+    log,
+    pipeline,
+    plotting,
+    store,
+    styling,
+    typing,
+    viewer,
+)
+from trendify.base import (
+    HashableBase,
+    Pen,
+    R,
+    Record,
+    RecordGenerator,
+    RecordList,
+    RecordType,
+    Tag,
+    Tags,
+    helpers,
+    pen,
+    record,
+)
+from trendify.cli import (
+    app as cli_app,
+)
+from trendify.color import (
+    Color,
+)
+from trendify.examples import (
+    example_record_generator,
+    make_example_data,
+)
+from trendify.formats import (
+    AxisScale,
+    Format2D,
+    PlottableData2D,
+    Rastered,
+    TableEntry,
+    Vector,
+    XYData,
+    format2d,
+    table,
+)
+from trendify.generator import (
+    Histogrammer,
+    TableBuilder,
+    XYDataPlotter,
+    generate,
+    generate_records,
+    get_sorted_dirs,
+    histogrammer,
+    render,
+    render_assets,
+    table_builder,
+    xy_data_plotter,
+)
+from trendify.log import (
+    create_queue_listener,
+    get_logger,
+    set_log_level,
+    setup_logger,
+    worker_init,
+)
+from trendify.pipeline import (
+    TrendifyPipeline,
+)
+from trendify.plotting import (
+    AxLine,
+    HistogramEntry,
+    HistogramStyle,
+    LineOrientation,
+    PlotlyFigure,
+    Point2D,
+    Scatter2D,
+    SingleAxisFigure,
+    Trace2D,
+    axline,
+    figure,
+    histogram,
+    point,
+    scatter,
+    trace,
+)
+from trendify.store import (
+    SCHEMA_VERSION,
+    RecordStore,
+    connect,
+    db,
+    decode_tag,
+    encode_tag,
+    record_store,
+    tag_to_path_parts,
+    tags,
+)
+from trendify.styling import (
+    Grid,
+    GridAxis,
+    GridTheme,
+    Legend,
+    LegendLocation,
+    Marker,
+    grid,
+    legend,
+    marker,
+)
+from trendify.typing import (
+    MatN,
+    VecN,
+)
+from trendify.viewer import (
+    HoverMode,
+    InterpMode,
+    LineMode,
+    PlotConfig,
+    TagNode,
+    api,
+    build_tag_tree,
+    camel_case_dict,
+    create_app,
+    create_app_from_env,
+    pages,
+    plot_config,
+    routes,
+    tag_tree,
+    viewer_app,
+)
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "AxLine",
+    "AxisScale",
+    "Color",
+    "Format2D",
+    "Grid",
+    "GridAxis",
+    "GridTheme",
+    "HashableBase",
+    "HistogramEntry",
+    "HistogramStyle",
+    "Histogrammer",
+    "HoverMode",
+    "InterpMode",
+    "Legend",
+    "LegendLocation",
+    "LineMode",
+    "LineOrientation",
+    "Marker",
+    "MatN",
+    "Pen",
+    "PlotConfig",
+    "PlotlyFigure",
+    "PlottableData2D",
+    "Point2D",
+    "R",
+    "Rastered",
+    "Record",
+    "RecordGenerator",
+    "RecordList",
+    "RecordStore",
+    "RecordType",
+    "Scatter2D",
+    "SingleAxisFigure",
+    "TableBuilder",
+    "TableEntry",
+    "Tag",
+    "TagNode",
+    "Tags",
+    "Trace2D",
+    "TrendifyPipeline",
+    "VecN",
+    "Vector",
+    "XYData",
+    "XYDataPlotter",
+    "api",
+    "axline",
+    "base",
+    "build_tag_tree",
+    "camel_case_dict",
+    "cli",
+    "cli_app",
+    "color",
+    "connect",
+    "create_app",
+    "create_app_from_env",
+    "create_queue_listener",
+    "db",
+    "decode_tag",
+    "encode_tag",
+    "example_record_generator",
+    "examples",
+    "figure",
+    "format2d",
+    "formats",
+    "generate",
+    "generate_records",
+    "generator",
+    "get_logger",
+    "get_sorted_dirs",
+    "grid",
+    "helpers",
+    "histogram",
+    "histogrammer",
+    "legend",
+    "log",
+    "make_example_data",
+    "marker",
+    "pages",
+    "pen",
+    "pipeline",
+    "plot_config",
+    "plotting",
+    "point",
+    "record",
+    "record_store",
+    "render",
+    "render_assets",
+    "routes",
+    "scatter",
+    "set_log_level",
+    "setup_logger",
+    "store",
+    "styling",
+    "table",
+    "table_builder",
+    "tag_to_path_parts",
+    "tag_tree",
+    "tags",
+    "trace",
+    "typing",
+    "viewer",
+    "viewer_app",
+    "worker_init",
+    "xy_data_plotter",
+]

trendify/base/__init__.py

@@ -0,0 +1,36 @@
+"""Core building blocks: the `Record` base class, `Pen` styling, and shared type helpers."""
+
+from trendify.base import helpers
+from trendify.base import pen
+from trendify.base import record
+
+from trendify.base.helpers import (
+    HashableBase,
+    R,
+    RecordType,
+    Tag,
+    Tags,
+)
+from trendify.base.pen import (
+    Pen,
+)
+from trendify.base.record import (
+    Record,
+    RecordGenerator,
+    RecordList,
+)
+
+__all__ = [
+    "HashableBase",
+    "Pen",
+    "R",
+    "Record",
+    "RecordGenerator",
+    "RecordList",
+    "RecordType",
+    "Tag",
+    "Tags",
+    "helpers",
+    "pen",
+    "record",
+]

trendify/base/helpers.py

@@ -0,0 +1,76 @@
+"""
+Small shared building blocks used across the rest of the package: the `Tag`/`Tags` type
+aliases every `Record` and the store's tag-encoding logic build on, `HashableBase` for
+pydantic models that need to go in a `set`, and the `RecordType` enum.
+"""
+
+from __future__ import annotations
+
+import logging
+from enum import StrEnum
+from typing import TYPE_CHECKING, TypeVar
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from trendify.base.record import Record
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "HashableBase",
+    "R",
+    "RecordType",
+    "Tag",
+    "Tags",
+]
+
+R = TypeVar("R", bound="Record")
+"""Bound to `Record`: used by `RecordStore.get_records`/`get_records_of_type` so a
+call like `get_records_of_type(Point2D)` returns `list[Point2D]` rather than `list[Record]`.
+"""
+
+Tag = str | int | tuple[str | int, ...]
+"""
+Determines what types can be used to define a tag.
+
+Tags must be reliably JSON-encodable (str/int, or tuples thereof) because the store
+canonicalizes a tag into a `tag_key` via `json.dumps` for indexed lookup (see
+`trendify.store.tags`).
+"""
+
+Tags = list[Tag]
+"""
+List of tags
+"""
+
+
+class HashableBase(BaseModel):
+    """
+    Defines a base for hashable pydantic data classes so that they can be reduced to a minimal set through type-casting.
+    """
+
+    def __hash__(self):
+        """
+        Defines hash function
+        """
+        return hash((type(self), *tuple(self.__dict__.values())))
+
+
+class RecordType(StrEnum):
+    """Defines all record types.  Used to type-cast URL info in server to validate."""
+
+    XY_DATA = "xy_data"
+    """XY_DATA name"""
+
+    TRACE_2D = "trace_2d"
+    """TRACE_2D name"""
+
+    POINT_2D = "point_2d"
+    """POINT_2D name"""
+
+    TABLE_ENTRY = "table_entry"
+    """TABLE_ENTRY name"""
+
+    HISTOGRAM_ENTRY = "histogram_entry"
+    """HISTOGRAM_ENTRY name"""

trendify/base/pen.py

@@ -0,0 +1,161 @@
+"""
+`Pen`: shared line/marker styling (color, size, alpha, linestyle, zorder, label) used by
+`Trace2D`, `AxLine`, and anything else that draws a line to matplotlib or Plotly.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from matplotlib.colors import to_rgba
+from pydantic import ConfigDict
+
+from trendify.base.helpers import HashableBase
+
+__all__ = ["Pen"]
+
+
+class Pen(HashableBase):
+    """Defines the pen drawing style."""
+
+    color: tuple[float, float, float] | tuple[float, float, float, float] | str = "k"
+    """Color of line"""
+
+    size: float = 1
+    """Line width"""
+
+    alpha: float = 1
+    """Opacity from 0 to 1 (inclusive)"""
+
+    zorder: float = 0
+    """Prioritization of trace line relative to other plotted data"""
+
+    linestyle: str | tuple[int, tuple[int, ...]] | None = "-"
+    """Linestyle to plot. Supports `str` or `tuple` definition ([matplotlib documentation](https://matplotlib.org/stable/gallery/lines_bars_and_markers/linestyles.html)).
+    Use `None` to draw no line at all, for a markers-only trace."""
+
+    label: str | None = None
+    """Legend label"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    def as_scatter_plot_kwargs(self) -> dict[str, Any]:
+        """
+        Returns kwargs dictionary for passing to [matplotlib plot][matplotlib.axes.Axes.plot] method
+        """
+        return {
+            "color": self.color,
+            "linewidth": self.size,
+            # matplotlib's `Line2D` treats `linestyle=None` as "use the default style", not
+            # "no line" (only the string "none" means that), so `None` is translated here to
+            # keep `Pen.linestyle = None` meaning "no line" from `has_line`'s point of view.
+            "linestyle": self.linestyle if self.linestyle is not None else "none",
+            "alpha": self.alpha,
+            "zorder": self.zorder,
+            "label": self.label,
+        }
+
+    @property
+    def has_line(self) -> bool:
+        """
+        Whether this pen draws a visible line. `False` when `linestyle` is `None`, which
+        callers like `Trace2D.add_to_plotly` use to render markers only, with no connecting
+        line.
+        """
+        return self.linestyle is not None
+
+    def _convert_linestyle_to_plotly(self) -> str:
+        """Convert matplotlib linestyle to plotly dash style"""
+        # `None` means "no line" (see `has_line`); callers exclude "lines" from the Plotly
+        # trace's `mode` in that case, so this value is never actually rendered, but return
+        # something valid regardless.
+        if self.linestyle is None:
+            return "solid"
+
+        # Handle string styles
+        style_map = {
+            "-": "solid",
+            "--": "dash",
+            ":": "dot",
+            "-.": "dashdot",
+        }
+        if isinstance(self.linestyle, str):
+            return style_map.get(self.linestyle, "solid")
+
+        # Handle tuple styles - convert to 'dash' as approximation
+        return "dash"
+
+    @property
+    def rgba(self) -> str:
+        """
+        Convert the pen's color to rgba string format.
+
+        Returns:
+            str: Color in 'rgba(r,g,b,a)' format where r,g,b are 0-255 and a is 0-1
+
+        """
+        # Handle different color input formats
+        if isinstance(self.color, tuple):
+            if len(self.color) == 3:  # RGB tuple
+                r, g, b = self.color
+                a = self.alpha
+            else:  # RGBA tuple
+                r, g, b, a = self.color
+            # Convert 0-1 range to 0-255 for RGB
+            r, g, b = int(r * 255), int(g * 255), int(b * 255)
+        else:  # String color (name or hex)
+            # Use matplotlib's color converter
+            rgba_vals = to_rgba(self.color, self.alpha)
+            # Convert 0-1 range to 0-255 for RGB
+            r, g, b = [int(x * 255) for x in rgba_vals[:3]]
+            a = rgba_vals[3]
+
+        return f"rgba({r}, {g}, {b}, {a})"
+
+    @property
+    def rgb(self) -> str:
+        return ", ".join(self.rgba.split(",")[0:-1]) + ")"
+
+    def get_contrast_color(self, background_luminance: float = 1.0) -> str:
+        """
+        Returns 'white' or 'black' to provide the best contrast against the pen's color,
+        taking into account the alpha (transparency) value of the line.
+
+        Args:
+            background_luminance (float): The luminance of the background (default is 1.0 for white).
+
+        Returns:
+            str: 'white' or 'black'
+
+        """
+        # Convert the pen's color to RGB (0-255 range) and get alpha
+        if isinstance(self.color, tuple):
+            if len(self.color) == 3:  # RGB tuple
+                r, g, b = self.color
+                a = self.alpha
+            else:  # RGBA tuple
+                r, g, b, a = self.color
+            r, g, b = int(r * 255), int(g * 255), int(b * 255)
+        else:  # String color (name or hex)
+            rgba_vals = to_rgba(self.color, self.alpha)
+            r, g, b = [int(x * 255) for x in rgba_vals[:3]]
+            a = rgba_vals[3]
+
+        # Calculate relative luminance of the pen's color
+        def luminance(channel: float) -> float:
+            channel /= 255.0
+            return (
+                channel / 12.92
+                if channel <= 0.03928
+                else ((channel + 0.055) / 1.055) ** 2.4
+            )
+
+        color_luminance = (
+            0.2126 * luminance(r) + 0.7152 * luminance(g) + 0.0722 * luminance(b)
+        )
+
+        # Blend the color luminance with the background luminance based on alpha
+        blended_luminance = (1 - a) * background_luminance + a * color_luminance
+
+        # Return white for dark blended colors, black for light blended colors
+        return "white" if blended_luminance < 0.5 else "black"

trendify/base/record.py

@@ -0,0 +1,148 @@
+"""
+Base `Record` pydantic model, the `RecordGenerator`/`RecordList` type aliases user code
+implements against, and the subclass registry `RecordStore` uses to deserialize a stored
+`record_type` string back into its concrete pydantic class.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Self
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    InstanceOf,
+    SerializeAsAny,
+    computed_field,
+    model_validator,
+)
+
+from trendify.base.helpers import Tags
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["Record", "RecordGenerator", "RecordList"]
+
+_record_subclass_registry: dict[str, type[Record]] = {}
+
+
+class Record(BaseModel):
+    """
+    Base class for records to be generated and handled.
+    """
+
+    tags: Tags
+    """Tags to be used for sorting data."""
+
+    metadata: dict[str, str] = {}
+    """A dictionary of metadata to be used as a tool tip for mouseover in Grafana."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _remove_computed_fields(cls, data: dict[str, Any]) -> dict[str, Any]:
+        """
+        Removes computed fields before passing data to constructor.
+
+        Args:
+            data (dict[str, Any]): Raw data to be validated before passing to pydantic class constructor.
+
+        Returns:
+            (dict[str, Any]): Sanitized data to be passed to class constructor.
+
+        """
+        for f in cls.model_computed_fields:
+            data.pop(f, None)
+        return data
+
+    @computed_field
+    @property
+    def record_type(self) -> str:
+        """
+        Returns:
+            (str): Record type should be the same as the class name.
+                The record type is used to search for records from the store.
+
+        """
+        return type(self).__name__
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """
+        Registers child subclasses to be able to parse them from JSON payloads using the
+        [deserialize][trendify.base.record.Record.deserialize] method
+        """
+        super().__init_subclass__(**kwargs)
+        _record_subclass_registry[cls.__name__] = cls
+        logger.debug(f"Registered Record subclass {cls.__name__!r}")
+
+    model_config = ConfigDict(extra="allow")
+
+    def append_to_list(self, to_add_to: list) -> Self:
+        """
+        Appends self to list.
+
+        Args:
+            to_add_to (List): list to which `self` will be appended
+
+        Returns:
+            (Self): returns instance of `self`
+
+        """
+        to_add_to.append(self)
+        return self
+
+    @classmethod
+    def registry(cls) -> dict[str, type[Record]]:
+        """
+        Returns:
+            (dict[str, type[Record]]): a copy of the record_type -> class registry,
+                used by the store to resolve which leaf `record_type` names correspond to a
+                given (possibly non-leaf) type when filtering by `object_type`.
+
+        """
+        return dict(_record_subclass_registry)
+
+    @classmethod
+    def deserialize(cls, record_type: str, payload: str) -> Record:
+        """
+        Loads a stored JSON payload into the pydantic dataclass registered under `record_type`.
+
+        Args:
+            record_type (str): the `record_type` discriminator string (same as the class name)
+            payload (str): the raw JSON text (e.g. from the store's `records.payload` column)
+
+        Returns:
+            (Record): the reconstructed, correctly-typed record instance
+
+        """
+        try:
+            duck_type = _record_subclass_registry[record_type]
+        except KeyError:
+            logger.error(
+                f"No registered Record subclass named {record_type!r}. Known types: "
+                f"{sorted(_record_subclass_registry)}. This usually means the module "
+                f"defining that subclass hasn't been imported in this process."
+            )
+            raise
+        return duck_type.model_validate_json(payload)
+
+    def set_metadata(self, new: dict[str, str]) -> Self:
+        self.metadata = new
+        return self
+
+
+RecordList = list[SerializeAsAny[InstanceOf[Record]]]
+"""List of serializable [Record][trendify.base.record.Record] or child classes thereof"""
+
+RecordGenerator = Callable[[Path], RecordList]
+"""
+Callable method type.  Users must provide a `RecordGenerator` to map over raw data.
+
+Args:
+    path (Path): Workdir holding raw data (Should be one per run from a batch)
+
+Returns:
+    (RecordList): List of records to be sorted and used to produce assets
+"""