sequenceDiagram participant User participant AAL as animate_activity_log participant RFA as reshape_for_animations participant GADF as generate_animation_df participant GA as generate_animation User->>AAL: Call with event_log, event_position_df, etc. AAL->>RFA: Process event_log (Take snapshots) RFA-->>AAL: Return reshaped_data (Patient states over time) AAL->>GADF: Add positions using event_position_df (Place patients) GADF-->>AAL: Return data_with_positions (Patient locations over time) AAL->>GA: Generate Plotly figure (Make the movie) GA-->>AAL: Return plotly_figure AAL-->>User: Return finished animation!
Chapter 1: Great Scott! Making Animations Easy with animate_activity_log
Welcome, aspiring process visualizer! Ever felt like you have tons of data about how things move through a system – like patients in a hospital, flux capacitors being assembled, or even messages zipping through a computer network – but it’s all just numbers in a table? You wish you could see it happen, like watching Marty McFly zip back to 1985?
Turning that raw data into a slick animation often feels like trying to build your own K.I.T.T. from spare parts – complicated! You need to figure out who is where at every single moment, plot them on a screen, and make it all move smoothly. It’s enough to make you want to yell, “Yippee-ki-yay… this is hard!”
That’s where vidigi
comes in, specifically our main hero function: animate_activity_log
. Think of it as the “Easy Button” or maybe the director calling “Action!” on your data movie set. It takes the essential ingredients and orchestrates the whole production, hiding the complex backstage machinery.
The Mission: Visualizing Patient Flow
Let’s imagine our mission, should we choose to accept it: we’ve simulated a busy clinic. We have a log showing when each patient (let’s call them “entities” or maybe “units” like Johnny 5) arrived, waited for a nurse, got treated, and left.
Our goal: Create an animation showing these patients moving through the clinic over time. We want to see the queues build up, watch patients being treated, and get a feel for the flow, all without needing 1.21 gigawatts of programming power!
Your Trusty Co-Pilot: animate_activity_log
The animate_activity_log
function is your primary tool in vidigi
. It acts as a Facade – a simple, high-level interface that handles a complex process behind the scenes. It’s like the main control panel for the DeLorean; you tell it where you want to go (what data to animate and how), and it handles the tricky bits (flux capacitor calibration not included… yet!).
It takes a few key pieces of information:
- The Event Log (
event_log
): This is the raw script of what happened and when. It’s a table detailing every important step each patient took. We’ll dive deep into this in Chapter 2: Event Log. - The Layout (
event_position_df
): This tellsvidigi
where each activity (like “Waiting Room” or “Treatment Bay”) should appear on the screen. Think of it as the stage layout or the map for your animation. More on this in Chapter 3: Layout Configuration (event_position_df
). - Scenario Details (
scenario
, optional): Sometimes, you need to tell the animation about the resources available, like how many nurses (or maybe Ghostbusters proton packs) are active. This helps visualize resource capacity. - Customization Knobs: Want to change the animation speed? Add a cool background image like the digital world of Tron? Change icon sizes?
animate_activity_log
has lots of parameters for tweaking the look and feel.
Let’s Get This Show on the Road: Basic Usage
Enough talk, let’s see it in action! We need two main things to start: an event_log
and an event_position_df
. We’ll use super simple placeholder data for now.
First, make sure you have vidigi
installed and import the function:
# Import the main animation function
from vidigi.animation import animate_activity_log
import pandas as pd # We use pandas DataFrames
Now, let’s create a tiny event log. Imagine two patients, Maverick and Goose, going through basic training (arrival, training, departure).
# Super simple event log (more detail in Chapter 2!)
= [
event_data 'patient': 'Maverick', 'event': 'arrival', 'time': 0, 'event_type': 'arrival_departure'},
{'patient': 'Goose', 'event': 'arrival', 'time': 5, 'event_type': 'arrival_departure'},
{'patient': 'Maverick', 'event': 'training_start', 'time': 10, 'event_type': 'resource_use'},
{'patient': 'Goose', 'event': 'training_start', 'time': 15, 'event_type': 'resource_use'},
{'patient': 'Maverick', 'event': 'training_end', 'time': 50, 'event_type': 'resource_use_end'},
{'patient': 'Goose', 'event': 'training_end', 'time': 65, 'event_type': 'resource_use_end'},
{'patient': 'Maverick', 'event': 'depart', 'time': 55, 'event_type': 'arrival_departure'},
{'patient': 'Goose', 'event': 'depart', 'time': 70, 'event_type': 'arrival_departure'}
{
]= pd.DataFrame(event_data)
event_log_df
print(event_log_df.head()) # Show first few rows
This code snippet sets up our list of events and converts it into a pandas DataFrame, which is the format vidigi
expects. The head()
function just shows us the first few rows to check it looks okay.
Next, we need to tell vidigi
where these events happen on the screen using the event_position_df
.
# Simple positions (x, y coordinates - more in Chapter 3!)
= [
position_data 'event': 'arrival', 'x': 50, 'y': 100, 'label': 'Arrival Zone'},
{'event': 'training_start', 'x': 150, 'y': 100, 'label': 'Training Area'},
{'event': 'depart', 'x': 250, 'y': 100, 'label': 'Departure Deck'}
{# Note: We don't need 'training_end' position here
]= pd.DataFrame(position_data)
event_pos_df
print(event_pos_df)
Here, we define where the ‘arrival’, ‘training_start’, and ‘depart’ activities are located using simple x and y coordinates. The ‘label’ is just for our reference (and can optionally be shown on the plot).
Now for the magic! We call animate_activity_log
with our data:
# Call the main function! It's showtime!
= animate_activity_log(
my_animation =event_log_df,
event_log=event_pos_df
event_position_df# We're using defaults for everything else for now
)
# To see the animation (usually in a Jupyter Notebook or similar)
# my_animation.show() # Uncomment this line to display!
print("Animation created! Use .show() to view it.")
This is the core call! We pass our event_log_df
and event_pos_df
. The function does its thing and returns a Plotly Figure object (which we store in my_animation
). If you were running this in an environment like a Jupyter Notebook, uncommenting my_animation.show()
would display the interactive animation! You’d see icons representing Maverick and Goose appear, move to the training area, and then depart.
Pimp My Ride: Adding Customizations
Want to make it look cooler? animate_activity_log
has many optional arguments. Let’s change the size and add stage labels.
# Let's make the icons bigger and add labels
= animate_activity_log(
fancy_animation =event_log_df,
event_log=event_pos_df,
event_position_df=30, # Bigger icons!
icon_and_text_size=True, # Show the 'label' from event_pos_df
display_stage_labels=400 # Make the plot shorter
plotly_height
)
# fancy_animation.show() # Uncomment to see the fancier version!
print("Fancier animation created!")
See? By adding a few parameters like icon_and_text_size
and display_stage_labels
, we can easily customize the output without needing to know the complex plotting commands underneath.
What’s Under the Hood? (No Need for a Mechanic!)
So how does animate_activity_log
pull this off? It doesn’t actually build the animation frame-by-frame itself. Instead, it acts like a director, calling on specialized helper functions to handle different parts of the job. It’s like how Michael Knight tells K.I.T.T. what to do, and K.I.T.T.’s internal systems handle the driving, scanning, and witty remarks.
Here’s the basic sequence of events when you call animate_activity_log
:
- Receive Inputs: The function takes your
event_log
,event_position_df
, and any other parameters you provided. - Snapshot Prep Part 1 (
reshape_for_animations
): It calls a helper function (reshape_for_animations
) to process the rawevent_log
. This function figures out who is doing what at regular time intervals (snapshots) throughout your simulation. It’s like taking still photos every few seconds during the action. - Snapshot Prep Part 2 (
generate_animation_df
): It then calls another helper (generate_animation_df
) which takes those snapshots and uses yourevent_position_df
to calculate the exact (x, y) screen coordinates for every patient in every snapshot. This is like putting markers on the floor telling the actors where to stand in each photo. - Animation Generation (
generate_animation
): Finally, it hands off this fully prepared data (snapshots with positions) to the main animation engine (generate_animation
). This function uses Plotly Express to actually build the animated plot, complete with icons moving between positions and a timeline slider. This is the final editing suite putting all the photos together into a movie. - Return the Final Cut: The
generate_animation
function returns the finished Plotly figure, andanimate_activity_log
passes it back to you.
Here’s a diagram showing this flow:
Internally, the code looks something like this (highly simplified!):
# Inside animate_activity_log function... simplified!
def animate_activity_log(event_log, event_position_df, scenario=None, ...): # ... means other parameters
# Step 1: Reshape data (call specialist function)
# Input: Raw event log. Output: Table of who is where at each time step.
= reshape_for_animations(event_log, ...)
full_patient_df # Status report: Got the snapshots!
# Step 2: Add positions (call another specialist)
# Input: Snapshots + Layout. Output: Snapshots with X, Y coordinates.
= generate_animation_df(
full_patient_df_plus_pos =full_patient_df,
full_patient_df=event_position_df,
event_position_df
...
)# Status report: Actors know their marks!
# Step 3: Create the animation (final specialist)
# Input: Snapshots with positions. Output: Interactive Plotly animation.
= generate_animation(
animation =full_patient_df_plus_pos,
full_patient_df_plus_pos=event_position_df,
event_position_df=scenario,
scenario
...
)# Status report: Rolling film... and cut! That's a wrap!
return animation # Return the final product to the user
By acting as this central coordinator, animate_activity_log
saves you from having to call each of these steps individually and pass data between them. It’s your one-stop shop for awesome process animations!
Conclusion: Your Animation Journey Begins!
You’ve just met the main command console for vidigi
: animate_activity_log
. It’s your friendly facade, your mission control, the “easy button” that takes your simulation data and layout, and turns it into a dynamic visual story. It orchestrates the behind-the-scenes work of data shaping and plot generation, letting you focus on understanding your process.
But this function needs fuel! The most crucial ingredient is the event_log
. In the next chapter, we’ll put on our flight suits and dive into exactly what this event log looks like and how to create it.
Fasten your seatbelts! Let’s head to Chapter 2: Event Log.
Generated by AI Codebase Knowledge Builder