Skip to content

Instantly share code, notes, and snippets.

@decagondev

decagondev/DS-Bandersnatch-Ticket2.md

Created July 26, 2025 15:18
Show Gist options
  • Save decagondev/39a70a5eb0b680876e95fdd6942ef8c4 to your computer and use it in GitHub Desktop.
Save decagondev/39a70a5eb0b680876e95fdd6942ef8c4 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
DS-Bandersnatch-Ticket2.md

Sprint 2: Dynamic Visualizations Guide for Data Scientists

Overview

This guide covers the second ticket of the BandersnatchStarter project, titled "Dynamic Visualizations," as outlined in BandersnatchStarter/tickets/secondTicket.md. The objective of Sprint 2 is to create interactive visualizations of the monster data (generated in Sprint 1 using MonsterLab) by exploring visualizations in a Jupyter Notebook, implementing a chart() function in app/graph.py using Altair, and integrating the chart into the Flask web application. This guide is designed for someone with a beginner data science background, familiar with Python, pandas, and Jupyter Notebooks, but new to Flask and Git. You’ll learn to use Altair (like matplotlib or seaborn but for web charts), integrate visualizations with Flask (like sharing notebook plots online), and manage code with Git (like notebook checkpoints). The guide relates tasks to your notebook experience, guiding you toward a solution without providing complete code to encourage learning.

Ticket Objectives

The second ticket focuses on:

  1. Notebook Exploration: Create a Jupyter Notebook to experiment with visualizations of monster data.
  2. Implement Chart Function: Develop a chart() function in app/graph.py that creates an Altair scatter plot with specified parameters.
  3. API Graph Integration: Serialize the chart for Flask and ensure it displays correctly with the Bandersnatch dark theme.
  4. Using Git: Track changes with Git for collaboration and version control.

This is like moving from plotting data in a notebook to creating interactive web visualizations, using the monster data (from MonsterLab) stored in MongoDB, and sharing your work with Git.

Prerequisites

Before starting, ensure you’ve completed the setup and Sprint 1:

  • Install Python 3, Git (git-scm.com), and Jupyter Notebook (pip install jupyter).
  • Fork and clone the repository: 
    git clone https://github.com/your-username/BandersnatchStarter.git
cd BandersnatchStarter
  • Set up a virtual environment:
    • Windows: python -m venv venv and venv\Scripts\activate.
    • macOS/Linux: python3 -m venv venv and source venv/bin/activate.
  • Install dependencies: python -m pip install -r requirements.txt. Ensure altair, pandas, MonsterLab, and pymongo are installed.
  • Complete Sprint 1, with a MongoDB database populated with at least 1,000 monsters using MonsterLab.
  • Set the SPRINT variable in app/main.py to 2: 
    SPRINT = 2
  • Test the Flask app: python -m app.main (Windows) or python3 -m app.main (macOS/Linux), and visit http://127.0.0.1:5000.
  • Complete the onboarding module in your course.

You’ll need familiarity with pandas DataFrames, Python dictionaries, and Jupyter Notebooks from your data science course.

Step-by-Step Guide

Below are the steps to complete Sprint 2, with explanations relating tasks to your Jupyter Notebook and pandas experience, incorporating the monster data from Sprint 1 and the specific requirements for the chart() function.

Step 1: Create a Jupyter Notebook for Visualization Exploration

Goal: Use a Jupyter Notebook to experiment with Altair visualizations, like exploring plots in a notebook.

What to Do:

  1. Start a Jupyter Notebook:

    • In the project root, run: 
      jupyter notebook
    • Create a new notebook (e.g., visualization_exploration.ipynb), like starting a new notebook for data analysis.

  2. Load Monster Data:

    • Use the MongoDB class from Sprint 1 (app/data.py) to fetch monster data: 
      from app.data import MongoDB
import pandas as pd
db = MongoDB("monsters")
df = db.dataframe()
    • This is like loading a CSV into a DataFrame: df = pd.read_csv("monsters.csv").
    • Inspect the DataFrame: df.head() to see attributes like name, strength, type, speed.

  3. Experiment with Altair:

    • Import Altair and create a simple scatter plot: 
      import altair as alt
chart = alt.Chart(df).mark_circle().encode(
    x="strength",
    y="speed",
    color="type"
)
chart.display()
    • This is like sns.scatterplot(x="strength", y="speed", hue="type", data=df) in seaborn.
    • Explore different chart types (e.g., mark_bar(), mark_line()) and encodings (e.g., size, tooltip) in the Altair Documentation.

  4. Test Visualizations:

    • Try different combinations, e.g., strength vs. speed colored by type, or bar charts of type counts.
    • Save the notebook to document your experiments, like saving a notebook with exploratory plots.

Notebook Analogy:

  • The notebook is like your usual Jupyter environment for plotting with matplotlib or seaborn.
  • Altair is like seaborn but creates interactive web charts, perfect for Flask integration.
  • The MongoDB.dataframe() method is like pd.read_csv() to load your dataset.

Tips:

  • Use df.columns to check available columns (e.g., strength, speed, type).
  • Save charts as HTML for testing: chart.save("test_chart.html"), and open in a browser.
  • Explore the Altair Gallery for inspiration.

Step 2: Implement the chart() Function in app/graph.py

Goal: Create a chart() function in app/graph.py to generate a scatter plot, like a reusable plotting function in a notebook.

What to Do:

  1. Open app/graph.py:

    • This is where you’ll define the chart() function, like writing a plotting function in a notebook.

  2. Define the Function Signature:

    • Create the function with the required parameters: 
      from altair import Chart
from pandas import DataFrame
def chart(df: DataFrame, x: str, y: str, target: str) -> Chart:
    pass  # Replace with your code
    • Parameters:
      • df: A pandas DataFrame (from MongoDB.dataframe()).
      • x: A column name for the x-axis (e.g., strength).
      • y: A column name for the y-axis (e.g., speed).
      • target: A column name for coloring (e.g., type).

  3. Create the Scatter Plot:

    • Use mark_circle() for a scatter plot, like the example: 
      graph = Chart(df, title=f"{y} by {x} for {target}").mark_circle(size=100).encode(
    x=x,
    y=y,
    color=target,
    tooltip=Tooltip(df.columns.to_list())
)
    • This is like sns.scatterplot(x=x, y=y, hue=target, data=df) but with tooltips listing all columns.

  4. Add Properties:

    • Define a properties dictionary with four keys: width, height, background, and padding. Example: 
      properties = {
    "width": 600,
    "height": 400,
    "background": "#1a1a1a",  # Dark theme for Bandersnatch
    "padding": 20
}
    • Apply with graph.properties(**properties), like setting plot size and style in seaborn.

  5. Add Configuration:

    • Create a configuration dictionary to style the chart for the Bandersnatch dark theme (e.g., text color, axis styles). Example: 
      config = {
    "axis": {"labelColor": "#ffffff", "titleColor": "#ffffff"},
    "title": {"color": "#ffffff"}
}
    • Apply with graph.configure(**config).

  6. Test the Function:

    • Test in a notebook: 
      from app.graph import chart
df = MongoDB("monsters").dataframe()
graph = chart(df, "strength", "speed", "type")
graph.display()
    • Save as HTML: graph.save("chart.html") and open in a browser.

Notebook Analogy:

  • The chart() function is like a notebook function that creates a seaborn plot with customizable axes and styles.
  • Altair’s encode() is like specifying x, y, and hue in sns.scatterplot().
  • Properties and configuration are like plt.figure(figsize=(...)) or seaborn’s set_style().

Tips:

  • Ensure x, y, and target are valid DataFrame columns (check df.columns).
  • Use a dark background (e.g., #1a1a1a) and light text (e.g., #ffffff) for the Bandersnatch theme.
  • Add a docstring explaining the function’s purpose, per PEP 8.
  • Remove print statements from the final code, per PEP style.

Step 3: Integrate the Chart into Flask

Goal: Serialize the chart and display it in the Flask app, like sharing a notebook plot online.

What to Do:

  1. Serialize the Chart:

    • In app/main.py, use the chart() function to generate a chart and serialize it: 
      from app.graph import chart
from app.data import MongoDB
from flask import render_template
@app.route("/view")
def view():
    df = MongoDB("monsters").dataframe()
    graph = chart(df, "strength", "speed", "type")
    return render_template("view.html", chart=graph.to_json())
    • graph.to_json() converts the chart to a JSON string for web display, like df.to_json() in a notebook.

  2. Create the Jinja2 Template:

    • Create templates/view.html to render the chart: 
      <!DOCTYPE html>
<html>
<head>
    <title>Monster Visualizations</title>
    <script src="https://cdn.jsdelivr.net/npm/vega@5"></script>
    <script src="https://cdn.jsdelivr.net/npm/vega-lite@5"></script>
    <script src="https://cdn.jsdelivr.net/npm/vega-embed@6"></script>
    <style>
        body { background-color: #1a1a1a; color: #ffffff; }
    </style>
</head>
<body>
    <h1>Monster Visualizations</h1>
    <div id="chart"></div>
    <script>
        vegaEmbed("#chart", {{ chart | safe }});
    </script>
</body>
</html>
    • This is like displaying a notebook plot in HTML, but interactive via Vega-Lite.

  3. Test the Integration:

    • Run the Flask app: python -m app.main (Windows) or python3 -m app.main (macOS/Linux).
    • Visit http://127.0.0.1:5000/view and compare to the deployed site (https://bandersnatch.herokuapp.com/view).
    • Check that the chart looks good with the dark Bandersnatch theme (e.g., dark background, light text).

Notebook Analogy:

  • The /view route is like a notebook cell that outputs a plot to HTML.
  • graph.to_json() is like df.to_html() or plt.savefig() for web sharing.
  • The Jinja2 template is like a markdown cell formatting a plot for display.

Tips:

  • Ensure Vega-Lite scripts are included (check URLs in the Altair documentation).
  • Use the safe filter in {{ chart | safe }} to render JSON correctly.
  • Check browser developer tools (F12) for JavaScript errors if the chart doesn’t display.

Step 4: Use Git to Track Changes

Goal: Use Git to manage code, like saving notebook checkpoints.

What to Do:

  1. Create a Branch:

    • Create a branch for Sprint 2: 
      git checkout -b sprint-2

  2. Commit Changes:

    • After editing app/graph.py, app/main.py, templates/view.html, and your notebook: 
      git add .
git commit -m "Implement chart function and Flask integration for Sprint 2"

  3. Push to GitHub:

    • Push your branch: 
      git push origin sprint-2
    • Create a pull request on your GitHub fork, like submitting a notebook for review.

Notebook Analogy:

  • A Git branch is like a separate notebook for a task.
  • Committing is like saving a notebook, and pushing is like uploading it.

Tips:

  • Run git status to check changes, like inspecting modified notebook cells.
  • Use clear commit messages (e.g., “Add Altair chart function”).
  • Check GitHub’s documentation for help.

Step 5: Prepare Deliverables

Goal: Submit the required deliverables for the ticket.

What to Do:

  1. Forked Repository Link:

    • Ensure changes are pushed to your GitHub fork.
    • Copy the repository URL (e.g., https://github.com/your-username/BandersnatchStarter).

  2. Loom Video:

    • Record a Loom video answering the prompt in the Submit Your Deliverables assignment.
    • Demonstrate:
      • The Jupyter Notebook with visualization experiments.
      • The /view route showing the chart locally.
      • Explaining the chart() function in app/graph.py and its styling.
      • Confirming the chart matches the Bandersnatch dark theme.

  3. Submit in Course:

    • Submit the repository link and Loom video link in your course platform.

Notebook Analogy:

  • The Loom video is like presenting your notebook plots in a class.
  • Submitting links is like sharing a notebook file and a recorded demo.

Tips:

  • Test the /view route locally to match the deployed site.
  • Keep the video concise, focusing on notebook exploration, the chart() function, and web integration.

Learning Tips for Data Scientists

  • Altair vs. Seaborn/Matplotlib: Altair is like seaborn but creates interactive web charts. Use mark_circle() like sns.scatterplot().
  • MongoDB vs. pandas: Use MongoDB.dataframe() like pd.read_csv() to load data.
  • Flask vs. Notebooks: The /view route is like a notebook cell outputting a plot to HTML. Jinja2 templates are like markdown cells for web display.
  • Git vs. Checkpoints: Git tracks changes across files, like notebook checkpoints. Branch per sprint, commit often.
  • Code Style:
    • Add docstrings for the chart() function, like comments in a notebook.
    • Follow PEP 8 (e.g., no inline print() statements in final code).
    • Remove extraneous comments, like cleaning notebook cells.
  • Debugging:
    • Use print(df.head()) in the notebook to inspect data, but remove from app/graph.py.
    • Use try-except in chart() for invalid columns: 
      try:
    # Chart code
except Exception as e:
    print(f"Error: {e}")
    • Check browser developer tools (F12) for Vega-Lite errors.
  • Resources:

Potential Challenges and Solutions

  • Invalid DataFrame Columns: Ensure x, y, and target are in df.columns. Print df.columns in the notebook to verify.
  • Chart Not Rendering: Check Vega-Lite script URLs in view.html and browser console (F12) for errors.
  • Theme Mismatch: Adjust background, labelColor, and titleColor in properties/config to match the dark theme (e.g., #1a1a1a background, #ffffff text).
  • Git Errors: If git push fails, ensure you’re on sprint-2 (git branch) and pushing to your fork.
  • Notebook Data Issues: If df is empty, verify the MongoDB class and database connection from Sprint 1.

Next Steps

  • Test Your Work:
    • Experiment with multiple charts in the notebook and save results.
    • Test the chart() function with different x, y, and target values.
    • Verify the /view route matches the deployed site’s appearance.
  • Prepare for Sprint 3: Ensure monster data has varied attributes for machine learning.
  • Git Workflow: Commit and push changes, create a pull request for sprint-2.
  • Deliverables: Submit your repository link and Loom video in your course.

Example Workflow

  1. Create a Jupyter Notebook and load monster data with MongoDB.dataframe().
  2. Experiment with Altair scatter plots, bar charts, and tooltips.
  3. Implement the chart() function in app/graph.py with properties and configuration for the Bandersnatch theme.
  4. Update app/main.py and templates/view.html to display the chart.
  5. Test at http://127.0.0.1:5000/view.
  6. Commit changes to a sprint-2 branch and push to GitHub.
  7. Record a Loom video and submit deliverables.

Conclusion

Sprint 2 builds on your pandas and notebook skills to create interactive visualizations with Altair, using monster data from Sprint 1. By exploring in a notebook, implementing a chart() function, and integrating with Flask, you’ll create a web-based visualization, like sharing a notebook plot online. Treat Altair like seaborn, Flask routes like notebook outputs, and Git like checkpoints. Work through each step, test frequently, and leverage your data science experience to succeed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment