caf.viz 0.1.1__tar.gz

caf.viz-0.1.1/LICENSE

@@ -0,0 +1,22 @@
+Copyright © Transport for the North (“TfN”) (2024).
+
+
+Use of this software and associated documentation files (“the Software”) by you indicates your acceptance of the terms and conditions below (“the Licence”).
+We make available the Software to you on the basis of this Licence. We do not sell the Software to you. We remain the owners of the Software at all times. 
+
+We grant you a non-exclusive, worldwide, royalty-free, perpetual licence:
+(a)	to use the Software;
+(b)	to develop, modify and maintain the Software;
+(c)	copy, publish, distribute and transmit the Software;
+(d)	adapt the Software.
+
+Where you do any of the above you must acknowledge the source of the Software in your product or application by including or linking the following attribution statement in a prominent and noticeable location in or in the context of your product or application:
+“Outputs derived from CAF.Viz (the Common Analytical Framework Visualisation Suite), developed by Transport for the North [https://github.com/Transport-for-the-North/caf.viz]”
+
+Any adaptations applied to the Software before application should be briefly described alongside the above citation. We encourage you to submit to us any adaptations to the Software and where you choose to do so your submissions will be considered for integration into the Software.
+
+The above are important conditions of this Licence and if you fail to comply with them the rights granted to you under this Licence will end automatically. 
+This Licence does not grant you any right to use the Software in a way that suggests any official status or that we endorse you or your use of the Software.
+The Software is licenced 'as is' and we exclude all representations, warranties, obligations and liabilities in relation to the Software to the maximum extent permitted by law.
+We are not liable for any errors or omissions in the Software and shall not be liable for any loss, injury or damage of any kind caused by its use. We do not guarantee the continued supply of the Software.
+This Licence is governed by the laws of the jurisdiction in which we have our principal place of business.

caf.viz-0.1.1/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.1
+Name: caf.viz
+Version: 0.1.1
+Summary: Python-based visualisation tools for transport data
+Author: Transport for the North
+License: Copyright © Transport for the North (“TfN”) (2024).
+        
+        
+        Use of this software and associated documentation files (“the Software”) by you indicates your acceptance of the terms and conditions below (“the Licence”).
+        We make available the Software to you on the basis of this Licence. We do not sell the Software to you. We remain the owners of the Software at all times. 
+        
+        We grant you a non-exclusive, worldwide, royalty-free, perpetual licence:
+        (a)	to use the Software;
+        (b)	to develop, modify and maintain the Software;
+        (c)	copy, publish, distribute and transmit the Software;
+        (d)	adapt the Software.
+        
+        Where you do any of the above you must acknowledge the source of the Software in your product or application by including or linking the following attribution statement in a prominent and noticeable location in or in the context of your product or application:
+        “Outputs derived from CAF.Viz (the Common Analytical Framework Visualisation Suite), developed by Transport for the North [https://github.com/Transport-for-the-North/caf.viz]”
+        
+        Any adaptations applied to the Software before application should be briefly described alongside the above citation. We encourage you to submit to us any adaptations to the Software and where you choose to do so your submissions will be considered for integration into the Software.
+        
+        The above are important conditions of this Licence and if you fail to comply with them the rights granted to you under this Licence will end automatically. 
+        This Licence does not grant you any right to use the Software in a way that suggests any official status or that we endorse you or your use of the Software.
+        The Software is licenced 'as is' and we exclude all representations, warranties, obligations and liabilities in relation to the Software to the maximum extent permitted by law.
+        We are not liable for any errors or omissions in the Software and shall not be liable for any loss, injury or damage of any kind caused by its use. We do not guarantee the continued supply of the Software.
+        This Licence is governed by the laws of the jurisdiction in which we have our principal place of business.
+        
+Project-URL: Bug Tracker, https://github.com/Transport-for-the-North/caf.viz/issues
+Project-URL: Homepage, https://github.com/Transport-for-the-North/caf.viz
+Project-URL: Source, https://github.com/Transport-for-the-North/caf.viz
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.19.0
+Requires-Dist: pandas>=1.4.0
+Requires-Dist: matplotlib>=3.8.2
+Requires-Dist: scipy>=1.11.4
+Requires-Dist: pydantic>=2.0
+Provides-Extra: lint
+Requires-Dist: black>=22.6.0; extra == "lint"
+Requires-Dist: isort>=5.12.0; extra == "lint"
+Requires-Dist: mypy>=1.0.0; extra == "lint"
+Requires-Dist: mypy_extensions>=1.0.0; extra == "lint"
+Requires-Dist: pydocstyle[toml]>=6.1.1; extra == "lint"
+Requires-Dist: pylint>=2.14.5; extra == "lint"
+Provides-Extra: test
+Requires-Dist: pytest>=7.4.0; extra == "test"
+Requires-Dist: pytest-cov>=4.1.0; extra == "test"
+Requires-Dist: pytest-xdist>=3.3.1; extra == "test"
+
+![Transport for the North Logo](https://github.com/Transport-for-the-North/caf.toolkit/blob/main/docs/TFN_Landscape_Colour_CMYK.png)
+
+<h1 align="center">CAF Viz</h1>
+
+<p align="center">
+<a href="https://github.com/PyCQA/pylint"><img alt="linting: pylint" src="https://img.shields.io/badge/linting-pylint-yellowgreen"></a>
+<a href="https://google.github.io/styleguide/pyguide.html"><img alt="code format: Google Style Guide" src="https://img.shields.io/badge/code%20style-Google%20Style%20Guide-blue"></a>
+<a href="https://github.com/psf/black"><img alt="code style: black" src="https://img.shields.io/badge/code%20format-black-000000.svg"></a>
+</p>
+
+Python-based visualisation tools for transport data.

caf.viz-0.1.1/README.md

@@ -0,0 +1,11 @@
+![Transport for the North Logo](https://github.com/Transport-for-the-North/caf.toolkit/blob/main/docs/TFN_Landscape_Colour_CMYK.png)
+
+<h1 align="center">CAF Viz</h1>
+
+<p align="center">
+<a href="https://github.com/PyCQA/pylint"><img alt="linting: pylint" src="https://img.shields.io/badge/linting-pylint-yellowgreen"></a>
+<a href="https://google.github.io/styleguide/pyguide.html"><img alt="code format: Google Style Guide" src="https://img.shields.io/badge/code%20style-Google%20Style%20Guide-blue"></a>
+<a href="https://github.com/psf/black"><img alt="code style: black" src="https://img.shields.io/badge/code%20format-black-000000.svg"></a>
+</p>
+
+Python-based visualisation tools for transport data.

caf.viz-0.1.1/pyproject.toml

@@ -0,0 +1,133 @@
+[build-system]
+requires = ["setuptools>=64.0.0", "versioningit"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "caf.viz"
+dynamic = ["version"]
+description = "Python-based visualisation tools for transport data"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [{ name = "Transport for the North" }]
+classifiers = [
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "numpy>=1.19.0",
+  "pandas>=1.4.0",
+  "matplotlib>=3.8.2",
+  "scipy>=1.11.4",
+  "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+lint = [
+  "black>=22.6.0",
+  "isort>=5.12.0",
+  "mypy>=1.0.0",
+  "mypy_extensions>=1.0.0",
+  "pydocstyle[toml]>=6.1.1",
+  "pylint>=2.14.5",
+]
+
+test = [
+  "pytest>=7.4.0",
+  "pytest-cov>=4.1.0",
+  "pytest-xdist>=3.3.1",
+]
+
+[project.urls]
+"Bug Tracker" = "https://github.com/Transport-for-the-North/caf.viz/issues"
+Homepage = "https://github.com/Transport-for-the-North/caf.viz"
+Source = "https://github.com/Transport-for-the-North/caf.viz"
+
+# Packaging options
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"caf.viz" = ["py.typed"]
+
+# Linters
+[tool.black]
+line-length = 95
+target-version = ['py310']
+
+[tool.pylint.messages_control]
+disable = [
+  "line-too-long",    # Compatibility with black
+  "too-many-lines",
+  "use-dict-literal",
+  "use-list-literal",
+]
+
+[tool.isort]
+profile = "black"
+src_paths = ["src", "tests"]
+
+skip = ["__init__.py", "_version.py"]
+skip_glob = [".*"]
+
+# Section commenting
+import_heading_stdlib = "Built-Ins"
+import_heading_thirdparty = "Third Party"
+import_heading_firstparty = "Local Imports"
+
+# Pylint settings
+[tool.pylint.basic]
+good-names = ["df", "fn", "ca", "tp", "to", "x", "x1", "x2", "i", "f", "q"]
+extension-pkg-allow-list = ["pydantic"]
+
+[tool.pylint.main]
+ignore = ["__init__.py", "_version.py", "versioneer.py"]
+
+[tool.pylint.design]
+max-args = 10
+max-attributes = 15
+max-statements = 100
+
+[tool.mypy]
+packages = ["caf.viz"]
+ignore_missing_imports = true
+allow_redefinition = true
+
+[tool.pydocstyle]
+convention = "numpy"
+match = '(?!_test)(?!test_)(?!__init__).*\.py'
+add-ignore = [
+  "D202", # Temporary compatibility with black
+]
+
+# Tests
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+addopts = '--cov=caf --cov-report=xml --doctest-modules -n auto'
+doctest_optionflags = "NORMALIZE_WHITESPACE"
+markers = [
+  "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+  "integration: integration tests, these may require manual checks of the outputs",
+  "serial: marks tests to not run in parallel",
+]
+
+[tool.coverage.report]
+include_namespace_packages = true
+
+# Versioning
+[tool.versioningit.vcs]
+method = "git"
+match = ["v*"]
+default-tag = "0.0.1"
+
+[tool.versioningit.onbuild]
+source-file = "src/caf/viz/_version.py"
+build-file = "caf/viz/_version.py"
+
+[tool.versioningit.format]
+distance = "{base_version}+{distance}.{vcs}{rev}"
+dirty = "{base_version}+{distance}.{vcs}{rev}.dirty"
+
+distance-dirty = "{base_version}+{distance}.{vcs}{rev}.dirty"

caf.viz-0.1.1/setup.cfg

@@ -0,0 +1,9 @@
+[options]
+cmdclass = 
+	sdist = versioningit.cmdclass.sdist
+	build_py = versioningit.cmdclass.build_py
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

caf.viz-0.1.1/src/caf/viz/__init__.py

@@ -0,0 +1,5 @@
+"""CAF package containing functionality for transport related visualisations."""
+
+from ._version import __version__
+
+# Aliases

caf.viz-0.1.1/src/caf/viz/_version.py

@@ -0,0 +1,14 @@
+# Always get the current version in "editable" installs
+# `pip install -e .` / `python setup.py develop`
+def _get_version() -> str:
+    from pathlib import Path
+    from versioningit import get_version
+
+    return get_version(
+        project_dir=Path(__file__).parents[3],
+    )
+
+
+# The following _get_version() call will get replaced by versioningit with a
+# static version string during a build
+__version__ = "0.1.1"

caf.viz-0.1.1/src/caf/viz/subplots.py

@@ -0,0 +1,157 @@
+# -*- coding: utf-8 -*-
+"""Functionality for helping creating figures with subplots."""
+
+##### IMPORTS #####
+from __future__ import annotations
+
+# Built-Ins
+import itertools
+import logging
+import math
+import sys
+from typing import Any, Callable, Concatenate, TypeAlias
+
+# Third Party
+import numpy as np
+from matplotlib import axes, figure
+from matplotlib import pyplot as plt
+
+##### CONSTANTS #####
+
+LOG = logging.getLogger(__name__)
+_FIGURE_WIDTH_FACTOR = 5
+_FIGURE_HEIGHT_FACTOR = 4
+
+# Python 3.10 raises an error when Concatenate ends with ellipsis,
+# although this should be allowed according to the Python docs
+if sys.version_info.major == 3 and sys.version_info.minor > 10:
+    PlotFunction: TypeAlias = Callable[Concatenate[figure.Figure, axes.Axes, ...], None]
+
+##### FUNCTIONS & CLASSES #####
+
+
+def subplotter(
+    func: PlotFunction,
+    plot_args: list[dict[str, Any]],
+    nrows: int,
+    ncols: int,
+    **subplots_kwargs,
+) -> figure.Figure:
+    """Plot subplots in a grid, axes plots are created using `func`.
+
+    A roughly square grid of subplots will be created, with a figure
+    size calculated based on the number of subplots in the grid.
+
+    Parameters
+    ----------
+    func : (figure.Figure, axes.Axes, ...) -> None
+        Function to plot data onto the individual subplot axes,
+        this will be call once with a single axes for each set of
+        arguments in `plot_args`.
+    plot_args : list[dict[str, Any]]
+        List of arguments for plotting `func`, the length of
+        this defines the number of subplot axes generated.
+    nrows : int
+        Number of rows of subplots to create.
+    ncols : int
+        Number of columns of subplots to create.
+    **subplots_kwargs : Keyword arguments
+        Any other keyword arguments are passed to `plt.subplots`.
+        This cannot contain the parameter: 'squeeze'.
+
+    Returns
+    -------
+    figure.Figure
+        The plotted figure.
+
+    Raises
+    ------
+    ValueError
+        - If length of `plot_args` is 0, or not enough Axes are created
+        to contain all the subplots i.e. ncols * nrows < len(plot_args).
+        - If one of 'squeeze' is given in `subplots_kwargs`.
+    """
+    if len(plot_args) == 0:
+        raise ValueError("no arguments given for plotting")
+
+    n_subplots = len(plot_args)
+    if nrows * ncols < n_subplots:
+        raise ValueError(f"not enough Axes rows and columns to fit all {n_subplots} subplots")
+
+    if "squeeze" in subplots_kwargs:
+        raise ValueError("squeeze cannot be defined in `subplot_kwargs` when using subplotter")
+
+    subplots_kwargs = subplots_kwargs.copy()
+    figsize = subplots_kwargs.pop(
+        "figsize",
+        (math.ceil(_FIGURE_WIDTH_FACTOR * ncols), math.ceil(_FIGURE_HEIGHT_FACTOR * nrows)),
+    )
+
+    axs: list[list[axes.Axes]]
+    fig, axs = plt.subplots(
+        nrows=nrows,
+        ncols=ncols,
+        squeeze=False,
+        figsize=figsize,
+        **subplots_kwargs,
+    )
+
+    grid_iter = itertools.product(range(nrows), range(ncols))
+    for (i, j), args in itertools.zip_longest(grid_iter, plot_args):
+        if args is None:
+            # Turn off axes if no more data to plot
+            axs[i][j].set_axis_off()
+            continue
+
+        func(fig, axs[i][j], **args)
+
+    return fig
+
+
+def grid_plot(
+    func: PlotFunction, plot_args: list[dict[str, Any]], **subplots_kwargs
+) -> figure.Figure:
+    """Plot subplots in a grid, axes plots are created using `func`.
+
+    A roughly square grid of subplots will be created, with a figure
+    size calculated based on the number of subplots in the grid.
+
+    Parameters
+    ----------
+    func : (figure.Figure, axes.Axes, ...) -> None
+        Function to plot data onto the individual subplot axes,
+        this will be call once with a single axes for each set of
+        arguments in `plot_args`.
+    plot_args : list[dict[str, Any]]
+        List of arguments for plotting `func`, the length of
+        this defines the number of subplot axes generated.
+    **subplots_kwargs : Keyword arguments
+        Any other keyword arguments are passed to `plt.subplots`.
+        This cannot contain the parameters:
+        'squeeze', 'nrows' or 'ncols'.
+
+    Returns
+    -------
+    figure.Figure
+        The plotted figure.
+
+    Raises
+    ------
+    ValueError
+        - If length of `plot_args` is 0.
+        - If one of 'squeeze', 'nrows' or 'ncols' is given in `subplots_kwargs`.
+    """
+    if len(plot_args) == 0:
+        raise ValueError("no arguments given for plotting")
+
+    n_subplots = len(plot_args)
+    ncols = int(np.ceil(np.sqrt(n_subplots)))
+    nrows = int(np.ceil(n_subplots / ncols))
+
+    for param in ("squeeze", "nrows", "ncols"):
+        if param in subplots_kwargs:
+            raise ValueError(
+                f"{param} cannot be defined in `subplot_kwargs` when using grid_plot"
+            )
+
+    return subplotter(func, plot_args, nrows=nrows, ncols=ncols, **subplots_kwargs)

caf.viz-0.1.1/src/caf/viz/utils.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+"""Miscellaneous utility functions for visualisation."""
+
+##### IMPORTS #####
+
+# Built-Ins
+import logging
+import re
+
+##### CONSTANTS #####
+
+LOG = logging.getLogger(__name__)
+
+
+##### CLASSES & FUNCTIONS #####
+
+
+def normalise_name(name: str) -> str:
+    """Convert name to lowercase and replace spaces with underscore."""
+    name = name.lower().strip()
+    return re.sub(r"\s+", "_", name)

caf.viz-0.1.1/src/caf/viz/xy_plot.py

@@ -0,0 +1,368 @@
+# -*- coding: utf-8 -*-
+"""Functionality for plotting of general X / Y data."""
+
+##### IMPORTS #####
+
+from __future__ import annotations
+
+# Built-Ins
+import enum
+import logging
+import warnings
+from typing import Sequence
+
+# Third Party
+import matplotlib as mpl
+import numpy as np
+import pandas as pd
+from matplotlib import axes, figure, ticker
+from pydantic import dataclasses
+from scipy import stats
+
+# Local Imports
+from caf.viz import subplots, utils
+
+##### CONSTANTS #####
+
+LOG = logging.getLogger(__name__)
+
+
+##### FUNCTIONS & CLASSES #####
+
+
+@dataclasses.dataclass(config={"arbitrary_types_allowed": True})
+class BasicData:
+    """Basic data for XY plots."""
+
+    data: pd.DataFrame
+    x_column: str
+    y_column: str
+    x_label: str | None = None
+    y_label: str | None = None
+    title: str | None = None
+    auto_label: bool = True
+
+
+@dataclasses.dataclass
+class CmapData:
+    """Colormap parameters."""
+
+    column: str
+    label: str | None = None
+    auto_label: bool = True
+    cmap: str = mpl.rcParams.get("image.cmap")  # type: ignore
+
+    def get_label(self) -> str | None:
+        """Return label for colorbar."""
+        if self.label is not None:
+            return self.label
+        if self.auto_label:
+            return self.column
+        return None
+
+
+class XYPlotType(enum.Enum):
+    """Types of 2D XY plots."""
+
+    SCATTER = "scatter"
+    SCATTER_DENSITY = "scatter_density"
+    HEXBIN = "hexbin"
+
+    @classmethod
+    def _missing_(cls, value) -> XYPlotType | None:
+        normal = utils.normalise_name(str(value))
+        for member in cls:
+            if member.value == normal:
+                return member
+
+        raise ValueError(
+            f"'{value}' is not a valid XYPlotType should be one of: "
+            + ", ".join(f"'{i.value}'" for i in cls)
+        )
+
+
+def hexbin(
+    fig: figure.Figure,
+    ax: axes.Axes,
+    data: BasicData,
+    cmap: CmapData | None = None,
+    gridsize: int = 50,
+    colorbar: bool = True,
+) -> None:
+    """Add hexbin plot to given `ax` and add colorbar to `fig`.
+
+    Parameters
+    ----------
+    fig : figure.Figure
+        Figure containing the plot Axes.
+    ax : axes.Axes
+        Axes to add hexbin plot to.
+    data : BasicData
+        Data for creating the hexbin plot.
+    cmap : CmapData, optional
+        Data for defining the hexbin colormap.
+    gridsize : int, default 50
+        Number of hexagons in the x-direction, i.e.
+        width of the hexbin grid.
+    colorbar : bool, default True
+        If True add colorbar to `fig`.
+
+    Raises
+    ------
+    KeyError
+        If colormap data column isn't present in `data.data`.
+    """
+    weights = None
+    if cmap is not None:
+        if cmap.column not in data.data.columns:
+            raise KeyError(f"colormap data column ('{cmap.column}') not present")
+        weights = cmap.column
+
+    hb = ax.hexbin(
+        data.x_column,
+        data.y_column,
+        C=weights,
+        data=data.data,
+        mincnt=1,
+        gridsize=gridsize,
+        linewidths=0.1,
+    )
+
+    if not colorbar:
+        return
+
+    if cmap is None:
+        label: str | None = "Count"
+    else:
+        label = cmap.get_label()
+
+    fig.colorbar(hb, ax=ax, label=label)
+
+
+def scatter(
+    fig: figure.Figure,
+    ax: axes.Axes,
+    data: BasicData,
+    density: bool = False,
+    cmap: CmapData | None = None,
+    colorbar: bool = True,
+    **kwargs,
+) -> None:
+    """Add scatter plot to given `ax`, with optional density colormap.
+
+    Parameters
+    ----------
+    fig : figure.Figure
+        Figure containing plot Axes.
+    ax : axes.Axes
+        Axes to add scatter plot to.
+    data : BasicData
+        DataFrame and columns containing data to be plotted.
+    density : bool, default False
+        Color scatter plot points based on the desntity,
+        uses gaussian_kde to estimate density.
+    cmap : CmapData, optional
+        Data for colouring scatter plot points,
+        cannot be used if `density` is True.
+    colorbar : bool, default True
+        If True and `density` is True add colour bar to `fig`.
+    kwargs : Keyword arguments
+        Additional keyword arguments to pass to `ax.scatter`,
+        'c' parameter will be ignored if `density` or `cmap`
+        are used.
+
+    Raises
+    ------
+    ValueError
+        If `cmap` is given and `density` is True.
+
+    See Also
+    --------
+    axes.Axes.scatter: base matplotlib method for creating scatter plots.
+    """
+    xy_data = data.data[[data.x_column, data.y_column]].values.T
+    z_data = None
+
+    if cmap is not None and density:
+        raise ValueError(
+            "cmap and density shouldn't both be given,"
+            " unsure which to use for colouring scatter plot"
+        )
+
+    if cmap is not None:
+        z_data = data.data[cmap.column]
+    elif density:
+        # Calculate point density
+        kernel = stats.gaussian_kde(xy_data)
+        z_data = kernel(xy_data)
+
+    if z_data is not None:
+        # Sort the points by density, so that the densest points are plotted last
+        idx = z_data.argsort()
+        z_data = z_data[idx]
+        xy_data = np.take(xy_data, idx, axis=1)
+
+        if "c" in kwargs:
+            warnings.warn("`c` parameter cannot be used if `cmap` or `density` is provided")
+            kwargs.pop("c")
+
+    else:
+        z_data = kwargs.pop("c", None)
+
+    points = ax.scatter(xy_data[0], xy_data[1], c=z_data)
+
+    if not colorbar or z_data is None:
+        return
+
+    if cmap is not None:
+        fig.colorbar(points, ax=ax, label=cmap.get_label())
+    else:
+        fig.colorbar(points, ax=ax, label="Density", ticks=ticker.NullLocator())
+
+
+def axes_plot_xy(
+    fig: figure.Figure,
+    ax: axes.Axes,
+    type_: XYPlotType,
+    data: BasicData,
+    cmap: CmapData | None = None,
+    **plot_kwargs,
+) -> None:
+    """Add plot to given `ax` based on `type_`.
+
+    Parameters
+    ----------
+    fig : figure.Figure
+        Figure containing the Axes being plotted on.
+    ax : axes.Axes
+        Axes to create plot on.
+    type_ : XYPlotType
+        Type of plot to create
+    data : BasicData
+        Data for creating the plot.
+    cmap : CmapData, optional
+        Data for defining any colormaps used in the plot.
+
+    Raises
+    ------
+    NotImplementedError
+        For any plot types which haven't been implemented.
+
+    See Also
+    --------
+    XYPlotType: for plot types which can be used.
+    hexbin, scatter
+    """
+    if type_ == XYPlotType.HEXBIN:
+        hexbin(fig, ax, data, cmap, **plot_kwargs)
+
+    elif type_ in (XYPlotType.SCATTER, XYPlotType.SCATTER_DENSITY):
+        if len(data.data) > 1_000_000:
+            warnings.warn(
+                "scatter plots may take a long time with "
+                "a lot of data, try hexbin plots instead",
+                RuntimeWarning,
+            )
+        scatter(
+            fig,
+            ax,
+            data,
+            density=type_ == XYPlotType.SCATTER_DENSITY,
+            cmap=cmap,
+            **plot_kwargs,
+        )
+
+    else:
+        raise NotImplementedError(f"unknown plot type {type_}")
+
+    if data.title is not None:
+        ax.set_title(data.title)
+
+    if data.x_label is not None:
+        ax.set_xlabel(data.x_label)
+    elif data.auto_label:
+        ax.set_xlabel(data.x_column)
+
+    if data.y_label is not None:
+        ax.set_ylabel(data.y_label)
+    elif data.auto_label:
+        ax.set_ylabel(data.y_column)
+
+
+def plot_xy(
+    data: pd.DataFrame,
+    x_column: str | Sequence[str],
+    y_column: str | Sequence[str],
+    type_: XYPlotType = XYPlotType.SCATTER,
+    title: str | None = None,
+    weight_column: None | str | Sequence[str] = None,
+) -> figure.Figure:
+    """Create a graph of `data` based on given columns.
+
+    Multiple subplots may be produced on the same figure
+    if multiple values are given for the columns.
+
+    Parameters
+    ----------
+    data : pd.DataFrame
+        Data to be plotted.
+    x_column, y_column : str | Sequence[str]
+        Name(s) of columns containing x (or y) values. If multiple
+        are given the figure will contain different subplots for each.
+    type_ : XYPlotType, default XYPlotType.SCATTER
+        Type of plot to add to axes.
+    title : str, optional
+        Title to add to figure.
+    weight_column : str | Sequence[str], optional
+        Column(s) containing data for creating colormaps
+        on the plots.
+
+    Returns
+    -------
+    figure.Figure
+        Figure with plots.
+
+    Raises
+    ------
+    ValueError
+        If `x_column` and `y_column` are sequences of different lengths.
+        If `weight_column` doesn't contain the same number of columns
+        as `x_column`.
+    """
+    type_ = XYPlotType(type_)
+
+    if isinstance(x_column, str) and isinstance(y_column, str):
+        x_column, y_column = (x_column,), (y_column,)
+
+    x_column, y_column = tuple(x_column), tuple(y_column)
+    if len(x_column) != len(y_column):
+        raise ValueError(
+            f"number of x column names ({len(x_column)}) and "
+            f"y column names ({len(y_column)}) should be the same"
+        )
+
+    if weight_column is not None:
+        if isinstance(weight_column, str):
+            weight_column = (weight_column,)
+        weight_column = tuple(weight_column)
+        if len(weight_column) != len(x_column):
+            raise ValueError(
+                f"number of weight column names ({len(weight_column)}) should "
+                f"be the same as the x and y column names ({len(x_column)})"
+            )
+
+    plot_data = []
+    for i, (x, y) in enumerate(zip(x_column, y_column)):
+        plot_data.append(
+            dict(
+                type_=type_,
+                data=BasicData(data, x, y),
+                cmap=None if weight_column is None else CmapData(weight_column[i]),
+            )
+        )
+
+    fig = subplots.grid_plot(axes_plot_xy, plot_data)
+    if title is not None:
+        fig.suptitle(title)
+
+    return fig

caf.viz-0.1.1/src/caf.viz.egg-info/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.1
+Name: caf.viz
+Version: 0.1.1
+Summary: Python-based visualisation tools for transport data
+Author: Transport for the North
+License: Copyright © Transport for the North (“TfN”) (2024).
+        
+        
+        Use of this software and associated documentation files (“the Software”) by you indicates your acceptance of the terms and conditions below (“the Licence”).
+        We make available the Software to you on the basis of this Licence. We do not sell the Software to you. We remain the owners of the Software at all times. 
+        
+        We grant you a non-exclusive, worldwide, royalty-free, perpetual licence:
+        (a)	to use the Software;
+        (b)	to develop, modify and maintain the Software;
+        (c)	copy, publish, distribute and transmit the Software;
+        (d)	adapt the Software.
+        
+        Where you do any of the above you must acknowledge the source of the Software in your product or application by including or linking the following attribution statement in a prominent and noticeable location in or in the context of your product or application:
+        “Outputs derived from CAF.Viz (the Common Analytical Framework Visualisation Suite), developed by Transport for the North [https://github.com/Transport-for-the-North/caf.viz]”
+        
+        Any adaptations applied to the Software before application should be briefly described alongside the above citation. We encourage you to submit to us any adaptations to the Software and where you choose to do so your submissions will be considered for integration into the Software.
+        
+        The above are important conditions of this Licence and if you fail to comply with them the rights granted to you under this Licence will end automatically. 
+        This Licence does not grant you any right to use the Software in a way that suggests any official status or that we endorse you or your use of the Software.
+        The Software is licenced 'as is' and we exclude all representations, warranties, obligations and liabilities in relation to the Software to the maximum extent permitted by law.
+        We are not liable for any errors or omissions in the Software and shall not be liable for any loss, injury or damage of any kind caused by its use. We do not guarantee the continued supply of the Software.
+        This Licence is governed by the laws of the jurisdiction in which we have our principal place of business.
+        
+Project-URL: Bug Tracker, https://github.com/Transport-for-the-North/caf.viz/issues
+Project-URL: Homepage, https://github.com/Transport-for-the-North/caf.viz
+Project-URL: Source, https://github.com/Transport-for-the-North/caf.viz
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.19.0
+Requires-Dist: pandas>=1.4.0
+Requires-Dist: matplotlib>=3.8.2
+Requires-Dist: scipy>=1.11.4
+Requires-Dist: pydantic>=2.0
+Provides-Extra: lint
+Requires-Dist: black>=22.6.0; extra == "lint"
+Requires-Dist: isort>=5.12.0; extra == "lint"
+Requires-Dist: mypy>=1.0.0; extra == "lint"
+Requires-Dist: mypy_extensions>=1.0.0; extra == "lint"
+Requires-Dist: pydocstyle[toml]>=6.1.1; extra == "lint"
+Requires-Dist: pylint>=2.14.5; extra == "lint"
+Provides-Extra: test
+Requires-Dist: pytest>=7.4.0; extra == "test"
+Requires-Dist: pytest-cov>=4.1.0; extra == "test"
+Requires-Dist: pytest-xdist>=3.3.1; extra == "test"
+
+![Transport for the North Logo](https://github.com/Transport-for-the-North/caf.toolkit/blob/main/docs/TFN_Landscape_Colour_CMYK.png)
+
+<h1 align="center">CAF Viz</h1>
+
+<p align="center">
+<a href="https://github.com/PyCQA/pylint"><img alt="linting: pylint" src="https://img.shields.io/badge/linting-pylint-yellowgreen"></a>
+<a href="https://google.github.io/styleguide/pyguide.html"><img alt="code format: Google Style Guide" src="https://img.shields.io/badge/code%20style-Google%20Style%20Guide-blue"></a>
+<a href="https://github.com/psf/black"><img alt="code style: black" src="https://img.shields.io/badge/code%20format-black-000000.svg"></a>
+</p>
+
+Python-based visualisation tools for transport data.

caf.viz-0.1.1/src/caf.viz.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+setup.cfg
+src/caf.viz.egg-info/PKG-INFO
+src/caf.viz.egg-info/SOURCES.txt
+src/caf.viz.egg-info/dependency_links.txt
+src/caf.viz.egg-info/requires.txt
+src/caf.viz.egg-info/top_level.txt
+src/caf/viz/__init__.py
+src/caf/viz/_version.py
+src/caf/viz/py.typed
+src/caf/viz/subplots.py
+src/caf/viz/utils.py
+src/caf/viz/xy_plot.py
+tests/test_example.py
+tests/test_xy_plot.py

caf.viz-0.1.1/src/caf.viz.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

caf.viz-0.1.1/src/caf.viz.egg-info/requires.txt

@@ -0,0 +1,18 @@
+numpy>=1.19.0
+pandas>=1.4.0
+matplotlib>=3.8.2
+scipy>=1.11.4
+pydantic>=2.0
+
+[lint]
+black>=22.6.0
+isort>=5.12.0
+mypy>=1.0.0
+mypy_extensions>=1.0.0
+pydocstyle[toml]>=6.1.1
+pylint>=2.14.5
+
+[test]
+pytest>=7.4.0
+pytest-cov>=4.1.0
+pytest-xdist>=3.3.1

caf.viz-0.1.1/src/caf.viz.egg-info/top_level.txt

@@ -0,0 +1 @@
+caf

caf.viz-0.1.1/tests/test_example.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+"""Tests for the caf.viz module"""
+# Built-Ins
+
+# Third Party
+
+# pylint: disable=import-error,wrong-import-position
+
+# pylint: enable=import-error,wrong-import-position
+
+# # # CONSTANTS # # #
+
+
+# # # FIXTURES # # #
+
+
+# # # TESTS # # #
+class TestFunctionName:
+    """Placeholder for test class."""
+
+    def test_something(self):
+        """Placeholder for test function."""
+        assert True

caf.viz-0.1.1/tests/test_xy_plot.py

@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+"""Tests for the `xy_plot` module."""
+
+##### IMPORTS #####
+
+# Built-Ins
+import itertools
+import pathlib
+from typing import Iterator
+
+# Third Party
+import numpy as np
+import pandas as pd
+import pytest
+from matplotlib import pyplot as plt
+from matplotlib.backends import backend_pdf
+
+# Local Imports
+from caf.viz import xy_plot
+
+##### CONSTANTS #####
+
+
+##### CLASSES & FUNCTIONS #####
+
+
+@pytest.fixture(name="random_data")
+def fix_random_data() -> tuple[pd.DataFrame, Iterator[tuple[str, str]]]:
+    """Generate DataFrame containing 10 random x / y columns.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with 10 pairs of x / y columns containing random data,
+        with columns: X1, Y1... X9, Y9.
+    Iterator[tuple[str, str]]
+        Infinite generator which returns the names of a pair of x / y
+        columns, will repeat previous column names after 9.
+    """
+    data = {}
+    columns = []
+    rng = np.random.default_rng()
+    for col in range(10):
+        names = (f"X{col}", f"Y{col}")
+        columns.append(names)
+
+        rand_data = rng.normal(10_000, 5000, 1000)
+        data[names[0]] = rand_data
+        data[names[1]] = rand_data + (rng.random(1000) * 10_000)
+
+    return pd.DataFrame(data), itertools.cycle(columns)
+
+
+@pytest.mark.integration
+@pytest.mark.parametrize("n_subplots", [1, 6, 10, 23])
+def test_plot(
+    tmp_path: pathlib.Path,
+    random_data: tuple[pd.DataFrame, Iterator[tuple[str, str]]],
+    n_subplots: int,
+):
+    """Test `plot_xy` with different number of subplots for all plot types."""
+    plt.style.use("caf.viz.tfn")
+
+    data, column_iter = random_data
+    x_columns: list[str] = []
+    y_columns: list[str] = []
+
+    while len(x_columns) < n_subplots:
+        x, y = next(column_iter)
+        x_columns.append(x)
+        y_columns.append(y)
+
+    out_file = tmp_path / "test_plots.pdf"
+    with backend_pdf.PdfPages(out_file) as pdf:
+        for type_ in xy_plot.XYPlotType:
+            fig = xy_plot.plot_xy(
+                data,
+                x_columns,
+                y_columns,
+                type_,
+                f"Test {type_.value.strip().replace('_', ' ').title()} Plots",
+            )
+            pdf.savefig(fig)
+            plt.close(fig)
+
+    assert out_file.is_file(), f"'{out_file.name}' not created"