Custom Plotting

Village provides three plot classes you can subclass to add custom visualizations. Each one is triggered at a different point in the data lifecycle:

Class

When it runs

Data available

OnlinePlotBase

During the session, in the window opened with ONLINE PLOTS

Current session trials so far

SessionPlotBase

With PLOT SESSION on a session of DATA → SESSIONS_SUMMARY

Full session CSV

SubjectPlotBase

With PLOT SUBJECT on a subject of the SUBJECTS screen

All sessions for that subject

Create a file anywhere inside your project’s code directory and define a subclass of the base class (e.g. OnlinePlot in online_plot.py; the file and class names are up to you). The system detects it automatically at startup and uses it instead of the default. Only one subclass of each base class is used per project.

The example project already includes the three of them: online_plot.py, session_plot.py and subject_plot.py. They work with every task of the example project, without naming any: each panel is drawn only if the task registered the column it needs (outcome, water, response_side, p…), and shows “no outcome data” or “not applicable” otherwise.


OnlinePlotBase

OnlinePlotBase lets you monitor the session in real time. The plot is shown in a separate window, opened with the ONLINE PLOTS button of the toolbar, and updated when new trials have finished (at most every UPDATE_TIME_TABLE seconds).

To redraw it periodically instead, also in the middle of a trial (e.g. to show data that change during long trials), set self.refresh_period to the number of seconds between redraws in __init__, after super().__init__():

def __init__(self) -> None:
    super().__init__()
    self.refresh_period = 1  # redraw every second

Override two methods:

  • create_figure_and_axes() — called once when the figure is first needed. Create self.fig and any axes you need (store them as instance attributes).

  • update_plot(df) — called when the plot is updated, with the growing session DataFrame. Clear and redraw your axes here.

Note

Do not call plt.show() or fig.savefig() — the figure is managed by the GUI. Always clear the axes at the start of update_plot to avoid stacking traces.

df columns (one row per completed trial, grows after each trial):

Fixed columns (always present)

  • trial — trial number (1-based integer).

  • date — session start timestamp string.

  • subject — subject name.

  • task — task class name.

  • system_name — name of the Village system.

  • TRIAL_START / TRIAL_END — absolute timestamps of the start and end of the trial.

  • ordered_list_of_events — event names in the order they occurred.

State and event columns

  • One column per state (STATE_<name>_START / STATE_<name>_END) and per event (e.g. Port1In, Port1Out, Tup, …): the ones Bpod records automatically, or the ones the task registers itself without Bpod. Each cell is a list of the timestamps of that trial (see the trial data in Tasks (Bpod)).

Custom columns

Any value registered with self.register_value(name, value) inside after_trial appears as an additional column, e.g. outcome and water in all the tasks of the example project.

Example — plot accuracy and reaction time trial by trial, for a task that registers outcome ("correct", "incorrect"…) and response_time:

import matplotlib.pyplot as plt

from village.custom_classes.online_plot_base import OnlinePlotBase


class OnlinePlot(OnlinePlotBase):

    def create_figure_and_axes(self) -> None:
        self.fig, (self.ax_acc, self.ax_rt) = plt.subplots(
            2, 1, figsize=(10, 6), sharex=True
        )
        self.fig.tight_layout(pad=2)

    def update_plot(self, df) -> None:
        self.ax_acc.clear()
        self.ax_rt.clear()

        if df.empty or "outcome" not in df.columns:
            return

        correct = (df["outcome"] == "correct").astype(float)
        self.ax_acc.plot(df["trial"], correct.rolling(10, min_periods=1).mean())
        self.ax_acc.set_ylabel("Accuracy (10-trial rolling mean)")
        self.ax_acc.set_ylim(0, 1)

        if "response_time" in df.columns:
            self.ax_rt.plot(df["trial"], df["response_time"], "o", color="salmon", ms=4)
            self.ax_rt.set_ylabel("Response time (s)")
            self.ax_rt.set_xlabel("Trial")

SessionPlotBase

SessionPlotBase produces a static figure shown in the GUI when the user selects a finished session in DATA → SESSIONS_SUMMARY and clicks PLOT SESSION.

Override create_plot(df, weight, width, height) and return a matplotlib.figure.Figure.

Arguments:

  • df — the session CSV as a DataFrame, with all its trials: the same columns as the df of OnlinePlotBase (see above), plus run_mode ("Manual" or "Auto").

  • weight — body weight of the subject at the time of the session (float, grams). 0.0 if not recorded.

  • width, height — figure size in inches requested by the GUI.

The state and event columns are text in the saved files

The df of SessionPlotBase and SubjectPlotBase is read from the saved CSV files, where the lists of the state and event columns are saved as text: a cell of Port1In is the string "[1793961057.5, 1793961059.2]", not a list. Convert it before using it:

import ast

pokes = df["Port1In"].dropna().apply(ast.literal_eval)  # now lists of floats

The columns registered with register_value (numbers, strings) are read normally.

Example — plot the accuracy over the session with body weight in the title:

import matplotlib.pyplot as plt
from matplotlib.figure import Figure

from village.custom_classes.session_plot_base import SessionPlotBase


class SessionPlot(SessionPlotBase):

    def create_plot(self, df, weight, width=10, height=8) -> Figure:
        fig, ax = plt.subplots(figsize=(width, height))

        if "outcome" in df.columns:
            correct = (df["outcome"] == "correct").astype(float)
            ax.plot(df["trial"], correct.rolling(10, min_periods=1).mean())
            ax.set_ylabel("Accuracy (10-trial rolling mean)")
            ax.set_ylim(0, 1)

        title = f"Session — {df['task'].iloc[0]}"
        if weight:
            title += f"  |  weight: {weight:.1f} g"
        ax.set_title(title)
        ax.set_xlabel("Trial")
        return fig

SubjectPlotBase

SubjectPlotBase produces a static figure shown when the user selects a subject in the SUBJECTS screen and clicks PLOT SUBJECT. It has access to the subject’s full history across all sessions.

Override create_plot(df, summary_df, width, height) and return a matplotlib.figure.Figure.

Arguments:

  • df — all trials for this subject, concatenated across sessions, read from the subject’s CSV file. Same columns as the df of SessionPlotBase (the state and event columns are text too), plus a session column (integer, 1-based) that identifies which session each trial belongs to.

  • summary_df — one row per session for this subject, from sessions_summary.csv. Columns:

    Column

    Description

    date

    Session start timestamp

    subject

    Subject name

    tag

    RFID tag

    weight

    Body weight (g) at session start

    task

    Task name

    duration

    Session duration in seconds

    trials

    Number of completed trials

    water

    Water delivered (µL)

    settings

    JSON string of the settings used

  • width, height — figure size in inches.

Example — accuracy per session and weight evolution:

import matplotlib.pyplot as plt
from matplotlib.figure import Figure

from village.custom_classes.subject_plot_base import SubjectPlotBase


class SubjectPlot(SubjectPlotBase):

    def create_plot(self, df, summary_df, width=10, height=8) -> Figure:
        fig, (ax_acc, ax_w) = plt.subplots(2, 1, figsize=(width, height))

        if "outcome" in df.columns:
            df = df.assign(correct=(df["outcome"] == "correct").astype(float))
            acc = df.groupby("session")["correct"].mean()
            ax_acc.plot(acc.index, acc.values, "o-", color="steelblue")
            ax_acc.set_ylabel("Mean accuracy per session")
            ax_acc.set_xlabel("Session")
            ax_acc.set_ylim(0, 1)

        if not summary_df.empty and "weight" in summary_df.columns:
            ax_w.plot(
                range(1, len(summary_df) + 1),
                summary_df["weight"].values,
                "s-",
                color="salmon",
            )
            ax_w.set_ylabel("Weight (g)")
            ax_w.set_xlabel("Session")

        fig.suptitle(df["subject"].iloc[0])
        fig.tight_layout()
        return fig