Plotting
========



Interactive 3D Plots
--------------------

The easiest method of plotting 3D PEPT-like data is using the ``pept.plots.PlotlyGrapher``
interactive grapher:


::

    # Plotting some example 3D lines
    import pept
    from pept.plots import PlotlyGrapher
    import numpy as np

    lines_raw = np.arange(70).reshape((10, 7))
    lines = pept.LineData(lines_raw)

    PlotlyGrapher().add_lines(lines).show()


::

    # Plotting some example 3D points
    import pept
    from pept.plots import PlotlyGrapher
    import numpy as np

    points_raw = np.arange(40).reshape((10, 4))
    points = pept.PointData(points_raw)

    PlotlyGrapher().add_points(points).show()


The ``PlotlyGrapher`` object allows straightforward subplots creation:


::

    # Plot the example 3D lines and points on separate subplots
    grapher = PlotlyGrapher(cols = 2)

    grapher.add_lines(lines)                        # col = 1 by default
    grapher.add_points(points, col = 2)

    grapher.show()


::

    # Plot the example 3D lines and points on separate subplots
    grapher = PlotlyGrapher(rows = 2, cols = 2)

    grapher.add_lines(lines, col = 2)               # row = 1 by default
    grapher.add_points(points, row = 2, col = 2)

    grapher.show()




Adding Colourbars
-----------------

By default, the last column of a dataset is used to colour-code the resulting points:

::

    from pept.plots import PlotlyGrapher
    PlotlyGrapher().add_points(point_data).show()   # Colour-codes by the last column


You can change the column used to colour-code points using a numeric index (e.g. first column
``colorbar_col = 0``, second to last column ``colorbar_col = -2``) or named column (e.g.
``colorbar_col = "error"``):

::

    PlotlyGrapher().add_points(point_data, colorbar_col = -2).show()
    PlotlyGrapher().add_points(point_data, colorbar_col = "label").show()   # Coloured by trajectory
    PlotlyGrapher().add_points(point_data, colorbar_col = "v").show()       # Coloured by velocity


As a ``PlotlyGrapher`` will often manage multiple subplots, one shouldn't include explicit
colourbars on the sides *for each dataset plotted*. Therefore, colourbars are hidden by default;
add a colourbar by setting its title:

::

    PlotlyGrapher().add_points(points, colorbar_title = "Velocity").show()




Histogram of Tracking Errors
----------------------------

The ``Centroids(error = True)`` filter appends a column "error" representing the relative error
in the tracked position. You can select a named column via indexing, e.g. ``trajectories["error"]``;
you can then plot a histogram of the relative errors with:

::

    import plotly.express as px
    px.histogram(trajectories["error"]).show()          # Large values are noise
    px.histogram(trajectories["cluster_size"]).show()   # Small values are noise


It is often useful to remove points with an error higher than a certain value, e.g. 20 mm:

::

    trajectories = Condition("error < 20").fit(trajectories)

    # Or simply append the `Condition` to the `pept.Pipeline`
    pipeline = pept.Pipeline([
        ...
        Condition("cluster_size > 30, error < 20"),
        ...
    ])




Exporting Plotly Graphs as Images
---------------------------------

The standard output of the Plotly grapher is an interactive HTML webpage; however, this can lead to large file sizes or memory overflows. Plotly allows for graphs to be exported as images to alleviate some of these issues.

Ensure you have imported:

::

    import plotly.express as px
    import kaleido
    import plotly.io as pio


There are two main ways of exporting as images:

::

    # Save the inner plotly.Figure attribute of a `grapher`
    # Format can be changed to other image formats
    # Width and height can be adjusted to give the desired image size
    grapher.fig.write_image("figure.png", width=2560, height=1440)




Modifying the Underlying Figure
-------------------------------

You can access the Plotly figure wrapped and managed by a PlotlyGrapher using the ``.fig``
attribute:

::

    grapher.fig.update_layout(xaxis_title = "Pipe Length (mm)")