3. Interactive Programs

Project 3: Interactive Programs #

Introduction #

Almost all of the code that you have seen in the course so far has been non-interactive. Though you may have interactively executed code in a Jupyter notebook, the code itself typically did not request input from you as it was running. In this final project of the course, we’d like you to build a substantial piece of software that is interactive in some way. As you do this, you will also get the chance to practice your skills at object-oriented design, organizing your project idea into a series of classes that work together to achieve complex functionality.

Project Summary #

In this project, you will be applying your Python knowledge (and hopefully learning a new library or two along the way) to build a program that interacts with users as part of its behavior. In terms of design, interactivity is essentially the only constraint for this project - you can use interactivity in a huge range of applications, and you can choose any kind of program you’d like (within reason).

As with the previous project, you can work individually or in groups - up to three students are permitted on a single team. Scoping your idea will be even more important than for Project 2, and you should be careful not to attempt too little or too much for this project. The milestones throughout the month-long span of this project are intended to provide you with appropriate scaffolding to help you find an interesting and appropriately scoped project to work on.

We hope that this project is a chance for you to demonstrate what you have learned over the semester and to get a deeper insight into what you can do with a knowledge of software design, as well as the process that it takes to get there.

Project Category Suggestions #

Below are a few broad categories of interactive programs that you might consider building for this project. While you do not have to do a project that fits into one of the categories below, we have found that most of the past projects in this course fit into one of these categories.

Please note that the student projects you see here were done over a significantly longer time frame (around 2 months) due to schedule changes arising from the COVID-19 pandemic.

Interactive Data Visualizations #

If you enjoyed visualizing data in Project 2, you should consider creating an interactive data visualization, which will give you an opportunity to further explore the world of telling stories with data.

An excellent and currently relevant example of a project in this area (though one that is likely beyond the scope of a one-month project) is the article What Happens Next? COVID-19 Futures, Explained with Playable Simulations by Marcel Salathé and Nicky Case. In this article, the authors provide a series of simulations to model the spread of COVID-19 under various scenarios. The interactivity comes from the fact that in many of these simulations, you can adjust various parameters (even while the simulation is running) to see how they effect outcomes such as peak cases, deaths, or times to reach herd immunity.

Note that unlike in Project 2, you do not need to fetch your data from a source on the Web - you can instead choose to generate some of your own data. For example, you could get real-time data from a sensor (such as your laptop’s CPU temperature) and provide a continually updated visualization of this data that the user could interact with in various ways.

Video Games #

Video games are interactive by nature. If you have been curious about what it would be like to design a game of your own, this project could be your chance to try it out. Previous students have taken this opportunity to make a clone of The Legend of Zelda:

Medieval Quest
screenshot

As well as the racing game Out Run:

PyRacer gameplay clip

Credits to Oscar de la Garza and Nabih Estefan Diaz for Medieval Quest (above), and to Patrick Ogunbufunmi and Tolu Oshinowo for PyRacer (below).

You do not have to make a real-time game, either. You could instead make a turn-based game, like a software version of the educational card game Phylo:

Copepod Phylo card

Interactive Art #

Creating an interactive piece of artwork offers a wide range of possibilities. By using a computer vision library (described more below), you could create a series of filters that can be applied to a webcam feed, or allow someone to remotely play an instrument like a synthesizer by simply pressing their fingers at the right spot on a nearby flat surface.

If you want to see some impressive (and certainly out-of-scope) examples for inspiration, we encourage you to check out screenshots and videos of the exhibits at the teamLab Borderless Museum in Tokyo.

Tools and Applications #

Another possibility you can explore is to build an interactive tool or application. This may be an interactive script (for example, a flight search tool that you can run from the command line) or a full-fledged Web application. The scope of this category can vary based on what technologies you are already familiar with (for example, a Web application would require some preexisting knowledge of Web development), but it is an opportunity for you to build something that is functional and useful for you or those around you. Here is a Craigslist-like site that previous students built:

Frank’s List item page

Credits to Jasper Katzban, Jonas Kazlauskas, and Kelly Yen for developing Frank’s List.

Project Deliverables #

There are seven deliverables for this project:

  1. Implementation
  2. Architecture Review
  3. Code Review
  4. Technical Documentation
  5. Code Quality
  6. Website
  7. Presentation

Below, we explain what each component involves.

Implementation #

Your implementation simply consists of your project code. Your code should be structured using an object-oriented approach (i.e., based on classes), but you do not necessarily need to follow the MVC architecture that we discussed in Reading 6.

Your implementation should be reasonably scoped and follow an appropriate design. Because you are expected to use an object-oriented design, if you find that your code has only one class, you may want to rescope or redesign your idea. (Consider the difference between the starter code and final code for Assignment 6.)

As with Project 2, you have the opportunity to learn a new library or design paradigm in this project, and you should consider the overhead of doing so when scoping your project. When evaluating your project, we will consider the scope of your project in the context of any new libraries or designs your code uses: a project that uses no new material beyond what appears in the readings and assignments will be expected to be more ambitiously scoped than one that heavily uses a library not taught so far.

As always, you are strongly encouraged to come talk to a NINJA or instructor if you have any questions or concerns about the scoping of your implementation.

Architecture Review #

The architecture review is a formal check-in that serves as an early milestone of the project. In this review, you will meet with an instructor and NINJA to discuss your project’s architecture, which may include the following:

  • The high-level components of your project
  • Specific classes that you have defined, including what attributes and/or methods they will have
  • The parameter and return types for functions and methods
  • Interactions among methods, classes, or components of your project

Because the architecture review is primarily about your project design, we will not discuss anything related to debugging your code. We will simply assume that any function or method you present works as intended. We are specifically looking to answer some (but not all) of the following questions:

  • How do the components of your software work together to achieve its functionality?
  • What are the risks or unknowns that you may face as you work through your project, and how can you address them?
  • What are the primary technical problems that you will tackle in this project, and how are you approaching those problems?
  • How do you envision the user interacting with your software, and how does the design of your project facilitate this interaction?

The architecture review is scheduled to last 5-10 minutes, and thus efficient use of time will be extremely important. Before the review, you should submit any materials you want us to review and any context necessary for us to understand your work, along with any questions or topics you want to cover during the meeting. You should also come to the meeting prepared to facilitate the review, including having the appropriate materials ready to screen-share (if necessary) and taking notes to help you in the remainder of the project.

Code Review #

The code review is a second formal check-in that serves as an additional milestone later in the project. In this review, you will again meet with an instructor and NINJA to discuss your implementation. In this review, it is expected that you will have already finalized the design of your project, and thus will focus mostly on your code itself. Among the questions we will be looking to answer are the following:

  • What parts of the implementation still need to be done, and what barriers still exist to completing the implementation?
  • What bugs or technical problems have been particularly tricky to tackle, and is there an insight or approach that would help address this?
  • Is the code working as intended? How do we know?
  • How is the code’s performance? Is this acceptable for the ways in which it is intended to be used, and if not, what are possible workarounds?

Similarly to the architecture review, you should submit any materials you want us to review, with accompanying context and topics you want to discuss in the meeting. You should also come prepared to facilitate and take notes. While debugging can be a part of this discussion, we would encourage you to make efficient use of the limited time for the code review (5-10 minutes) by only discussing debugging problems that have proved particularly tricky.

Technical Documentation #

As with the previous projects, to help both your future self and others who may want to use and/or extend your work, you should ensure that your code is well-documented. The technical documentation of your project should consist of docstrings for all functions, methods, and classes, as well as a brief README that explains the dependencies and usage instructions of your project.

Documentation #

Each function, method, and class that you write should be well-documented. At a minimum, this means having a docstring that explains what each function, method, or class does. For functions and methods, if applicable, the docstring should list the type and description of each parameter and return value, as well as any assumptions made by the function about its inputs. For classes, the docstring should list the type and description of each class and instance attribute.

As a reminder, a docstring should consist of the following:

  • A one-sentence description of what the function does, written in the imperative (“Return…” instead of “Returns…").
  • If applicable, one or more paragraphs that provide more detail, such as assumptions made or special behavior in certain cases.
  • The types of each parameter, return type, or attributes, along with what each variable represents. )this can be omitted where obvious or non-applicable.

Additionally, any part of your code that requires additional explanation or justification should have a line comment with the relevant details.

README #

Your submission repository should have a file called README.md written in Markdown. This file should briefly summarize your project and explain how to use your code. By following the instructions in the README, anyone else should be able to run your project, provided they are also running Ubuntu 20.04.

If you installed any additional packages or libraries, you must mention them in the README. Ideally, you should also include installation instructions for these libraries, such as by using the conda or pip commands (which are often found in the documentation for other libraries).

Beyond these requirements, the structure and content of the README is up to you, but we expect that your README should be relatively easy to follow and understand.

Code Quality #

As with all of the projects in this course, your code is expected to be polished and of high quality. This means that your code should be written with proper style and with a suitable set of unit tests to confirm that the code works as intended.

Code Style #

Your code, including both your implementation and testing files, should be written with proper style. This means that running pycodestyle on these files should produce no output indicating a style warning or error. Additionally, your code should use reasonably clear and precise variable names, and if you write helper functions for any part of your code, the names of these functions and their parameters should also be clear.

Additionally, your functions and methods should be appropriately scoped. As an approximate rule of thumb, you should avoid writing functions that are more than 50 lines or so, breaking such functions into several smaller functions instead. Ideally, each of your functions should do one thing, and do it well. If in doubt, talk to a NINJA or instructor.

Unit Tests #

You should thoroughly test as much of your implementation as is feasible. As in the previous project, it is not necessary to test parts of your implementation that depend on features such as network connections or databases.

You will need to create your own test file(s) for this project. You can use the testing files for previous assignments as a starting point for your tests. You are free to write tests in whatever way you choose, as long as you are clear about why you are running each test.

As you write your unit tests, you may find the pytest documentation helpful. If you want a helpful starting point for writing your own unit tests, we would recommend starting with the Installation and Getting Started guide. You are also allowed to use previous testing files from this class as a starting point.

Presentation #

You should summarize your project and its highlights in a presentation that you will share with the class during our final events period on Wednesday, 12/16. You should expect to have 7-10 minutes for your presentation.

The presentation should clearly state the following five pieces of information:

  1. What was the main goal of your project, and why did you choose this project? This should be presented in a way that is broadly accessible, even to someone who does not know about your project topic.
  2. How is your project designed? This may involve showing the breakdown of your project into components and how those components interact.
  3. What were the major design decisions and insights you had while developing this project?
  4. How does your project work? You may communicate this by showing a demo, explaining the features of your project in an organized way, or in some other way that makes sense for your project.
  5. What are the key takeaways of your project? This might include lessons that you learned from doing the work, insights that the audience should get from your project, or a call to action.

As with the previous project, this can be quite a lot of information to condense into a short amount of time, so what you do not present is just as important as what you do present. You will likely have many details that you want to talk about, but do not have time for. We suggest that you practice the presentation with only the key elements required to tell your story, and then add other material as time allows.

Your presentation should be visually appealing, and your presentation should not simply be a description of your project. You should think of your presentation as a way to present the highlights of your project, including the aspects of your work that you are most proud of and most excited by. Think of it as a sales pitch for people to check out your project in more detail.

If time allows, there will be a short opportunity for the audience to ask a question or two after your presentation. You should be prepared to answer such questions about your code, results, or overall story.

Professionalism is important in public presentations. You should stay on time - timing will be strictly enforced. Additionally, while humor and other methods of telling a more compelling or understandable story may be helpful, inappropriate language or disparaging others will not be tolerated. A potentially useful question you may want to ask yourself is the following: if this presentation circulated on social media at the height of my career, how comfortable would I be with that?

As the presentation date near, we will provide a shared slide deck in which you can add your presentation slides.

Website #

Your should also create a simple website that highlights the important aspects of your project. You should do this via GitHub Pages, which has a number of tutorials and guides that you can use to get started. The core of the website content is written in Markdown, so you should not worry if you have not designed a website before. We will also likely run a more in-depth walkthrough for anyone who is interested during one of the open studio days.

The website should explain your project to a broader audience and draw attention to core features or important findings of the project. This may include information such as the following:

  • The big idea or goal of the project
  • Unique features of your project
  • Screenshots or demos of your project
  • Installation instructions (or link to the relevant portion of the README)
  • Download links for your project
  • A link to your project’s GitHub page
  • Information about you (to the extent you are comfortable)
  • Attribution for any external resources you used

You do not have to include all of the above information, provided that your website communicates sufficient details of your project to a broad audience.

As examples of this type of site design (though with more content than we might expect), take a look at the project pages for HandBrake, Signal, or Joplin.

Roadmap #

Important Due Dates #

As a reminder, all deadlines are at 10AM Eastern.

  • Saturday, 11/21: email teaching team with project partners
  • Saturday, 11/21 (optional): email teaching team with proposed idea
  • Monday, 11/30: submit architecture review materials on Canvas
  • Monday, 12/7: submit code review materials on Canvas
  • Wednesday, 12/16: have slides ready to present in shared deck
  • Thursday, 12/17: submit all project materials (URL to GitHub repository) on Canvas

Project Proposal #

If you would like feedback on your project idea, we will be happy to provide this, either synchronously during a class meeting or asynchronously in response to an email describing your proposed idea. While this step is optional, we highly recommend that you do so to get feedback on your project scope before the architecture review.

Suggested Milestones #

Because this project is open-ended, we suggest the following rough milestones for your project. Note that these are all the latest days by which you should aim to have things done to avoid having a huge workload near the end of your project; getting things done a day or two earlier is even better.

  • By Monday, 11/23, you should have a clear idea of your project topic and have a few possible approaches for how to design the architecture for your project.
  • By the end of Thursday, 12/3, you should finalize your software architecture and transition to implementing your project.
  • By the end of Thursday, 12/10, you should finalize all features and focus solely on implementing the current set of features you have current planned.
  • By Sunday, 12/13, you should be more or less done with the implementation and focus your efforts on the remaining deliverables.

Submission #

With the exception of the presentation, which should be given in class on Wednesday, 12/16, all project deliverables should be submitted and available in GitHub by 10 am Eastern on Thursday, 12/17.

To submit your project, add, commit, and push any files that you changed to GitHub. Ensure your files are visible on GitHub by visiting the repository page and checking your files. For this project, your repository can be called anything you like. To help us find your code, then, you must submit a URL to your project GitHub repository on Canvas.

Barring any emergencies, there are no late days for this project. If something comes up that will prevent you from submitting the project on time, contact us as soon as possible.

Assessment and Grading #

The project is worth a total of 360 points. Again, there is no specific, detailed rubric for this project, but here is the breakdown of how each deliverable factors into your grade.

  • Implementation: 90 points
  • Architecture Review: 50 points
  • Code Review : 50 points
  • Technical Documentation (Docstrings and README): 45 points
  • Code Quality (Style and Unit Test): 45 points
  • Presentation: 40 points
  • Website: 40 points

As with the previous project, we may award extra credit in any of these categories for exceptional work.

Resources #

Below are a few resources you might find helpful for certain project ideas.

Pygame #

If you plan to develop a game, we strongly recommend using pygame, which provides a variety of useful features that are common in game design, such as detecting collisions between objects and refreshing the screen. It is particularly helpful that pygame provides extensive documentation and tutorials for you to use as you learn the library.

OpenCV #

If you plan to work with images (including live data from webcams), the OpenCV library will provide almost everything you need. It is a powerful computer vision library written in C++, but has a Python library to enable you to access its functionality from Python code. Their Python tutorials page has guides for most of the functionality that you would likely look for.