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 |
|---|---|---|
|
During the session, in the window opened with |
Current session trials so far |
|
With |
Full session CSV |
|
With |
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. Createself.figand 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 thedfofOnlinePlotBase(see above), plusrun_mode("Manual"or"Auto").weight— body weight of the subject at the time of the session (float, grams).0.0if 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 thedfofSessionPlotBase(the state and event columns are text too), plus asessioncolumn (integer, 1-based) that identifies which session each trial belongs to.summary_df— one row per session for this subject, fromsessions_summary.csv. Columns:Column
Description
dateSession start timestamp
subjectSubject name
tagRFID tag
weightBody weight (g) at session start
taskTask name
durationSession duration in seconds
trialsNumber of completed trials
waterWater delivered (µL)
settingsJSON 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