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:

  1. 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.
  2. The Layout (event_position_df): This tells vidigi 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).
  3. 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.
  4. 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'}
]
event_log_df = pd.DataFrame(event_data)

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
]
event_pos_df = pd.DataFrame(position_data)

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!
my_animation = animate_activity_log(
    event_log=event_log_df,
    event_position_df=event_pos_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
fancy_animation = animate_activity_log(
    event_log=event_log_df,
    event_position_df=event_pos_df,
    icon_and_text_size=30, # Bigger icons!
    display_stage_labels=True, # Show the 'label' from event_pos_df
    plotly_height=400 # Make the plot shorter
)

# 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:

  1. Receive Inputs: The function takes your event_log, event_position_df, and any other parameters you provided.
  2. Snapshot Prep Part 1 (reshape_for_animations): It calls a helper function (reshape_for_animations) to process the raw event_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.
  3. Snapshot Prep Part 2 (generate_animation_df): It then calls another helper (generate_animation_df) which takes those snapshots and uses your event_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.
  4. 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.
  5. Return the Final Cut: The generate_animation function returns the finished Plotly figure, and animate_activity_log passes it back to you.

Here’s a diagram showing this flow:

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!

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.
    full_patient_df = reshape_for_animations(event_log, ...)
    # Status report: Got the snapshots!

    # Step 2: Add positions (call another specialist)
    # Input: Snapshots + Layout. Output: Snapshots with X, Y coordinates.
    full_patient_df_plus_pos = generate_animation_df(
        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.
    animation = generate_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