Part 3 - Report & Code

Overview¶

Deliverables - Project Report & Code due Sunday 8/16 at 11:59 PM

The following components are required:

• Report: Your full report (10-15 pages) written document as a PDF. Do not turn in a Word Document or plain text file.

• Code: All code and test files, including documentation. You will not submit any code directly to Gradescope, but will include a link to your public repository in your report.

  • README.md: Relevant instructions to run your program in a file called README.md stored in the root directory of your repository.

All submissions will use Gradescope. If you are not done by the due date, please submit what you have before the due date passes.

Report¶

Submit a roughly 10-12 page report documenting your findings. You should update any of the previous sections based on feedback from the proposal.

Outline your report with at least the following sections (make sure to label your sections in your report):

1. Title and author(s)

2. Summary of questions and results. Repeat your research questions in a numbered list. After each research question, clearly state the answer you determined. Don’t give any details or justifications yet — just a brief summary of the answer.

3. Motivation Same as Proposal, updated according to feedback.

4. Dataset Same as Proposal, updated according to feedback.

5. Method Same as Proposal, updated with any changes made during implementation.

6. EDA Summarize your findings from the EDA. What steps did you take during your EDA that prepared the work you conducted for the rest of your analysis? What did you learn about your data from doing the EDA? You do not have to repeat your entire EDA here; just give us the highlights!

7. Results

   • Present and discuss your research results. Treat each of your research questions separately. Include additional discussions for results that are most interesting, surprising, or important. Discuss the consequences or implications.

   • Interpret the results. If the answers are unexpected, try to offer an explanation. A good report not only presents the results, but provides an argument or interpretation based on the data analysis.

   • Include any visualizations you have made. In general, these should be generated programmatically as part of your project code.

8. Impact and Limitations What are the potential implications of your results? Who might be benefit from your analysis and who might be excluded, or worse, harmed by it. Are there any biases in your data that might impact your results? Explicitly outline the limitations of your analysis and how others should or shouldn’t use your conclusions.

9. Challenge Goals Same as Proposal, updated with any changes made during implementation. If the challenge goals were scaled back or expanded, explain why the task turned out differently than initially estimated.

10. Work Plan Evaluation Evaluate your proposed work plan. How accurate were your proposed work plan estimates? Why were your estimates close to reality or far from reality?

11. Testing Describe how you tested your code and why you tested in that way to ensure your report was correct. Did you use assert statements? Smaller data files? You should submit your tests and any testing files along with your code. Make sure you tell us why we should trust your results!

12. Citations and Collaboration State the other people and/or resources that you consulted during the project aside from the course staff and team members. These do not need to adhere to a formal citation style, but you should be consistent in your references!

Some additional formatting guidelines are as follows:

• All visualizations must be captioned and titled AND be described or referenced in the body of the report. Make sure to explain how your visualizations were produced and contribute to the narrative or analysis. Any visualization which is not referenced in the body of the report should be excluded or moved to an appendix.

• All pages must be numbered. If you choose to include a title page, it must also have the page number. All other headers and footers are optional.

• The report is not to exceed 15 pages. This is a hard limit, as even professional journals and conferences also have page limits! Not even one word or one line over! Optional title page and appendix do not count towards the 15 pages.

• Do not single-space your report. Font size must be 11 or above. Beyond this, you are free to use whatever font, spacing, and margins you’d like.

• You may choose to include additional information or references in an appendix that follows the report. There is no limit to how long your appendix may be, but its contents will neither be assessed for quality nor read in detail.

• You may optionally include brief code snippets in your report to provide context for written sections, however you should keep the inclusion of project code to a minimum in the report itself. Feel free to highlight specific files you would like course staff to pay particular attention to when reviewing your repository contents!

Code¶

Your code should meet the following requirements.

• Your project must be a Python script (.py files). You are more than welcome to experiment and/or develop in a Jupyter Notebook, but your end result must be a runnable Python script to output all your results. Your project should use the main method pattern for modules that can be run. Feel free to include any experimental files, including Jupyter notebooks, in your repository.

• Your code must pass flake8 and should follow the CSE 163 Code Quality Guide. Your source code documentation can assume that the reader has already read your report — you do not need to repeat any of those details, but it doesn’t hurt to restate the highlights.

• Your code will need to be broken up into at least two Python modules (.py files). You can decide how to break up your code, but it helps to separate them by the part of the project they concern. A very common split is to have one module that does all the data processing (loading in data, cleaning it, etc.) while the other module is the actual runnable program that does the analysis. You can break up your code however you see fit and could have more modules if you want, but you must have at least two Python modules that you submit.

• You should write a testing Python program to test the code that you wrote for the project. Remember that testing is a way for you to ensure your results are valid by checking that the code you wrote is correct. Your testing programs do not count as one of the two required modules.

Note: Just for reference, most projects that adequately meet two challenge goals will be at least 120 lines of Python code long. This is not a strict requirement, and we do not count lines, but this is a very good heuristic to tell if your project has enough depth.

README.md¶

Along with your code in your repository, you will include a file named README.md that contains instructions on how to run your project. The .md file type is a Markdown file which is like a plain .txt but allows some special formatting that many websites render into a nice display. You can see what an example README.md looks like here. You can view the file that creates this page here.

Your README.md should include:

• Information about necessary downloads or installations, which may include libraries, environments, or data.

• A description of each submitted file that is relevant to running your project. All .py files must have descriptions in the README.md.

• Step-by-step instructions for us to run your project to reproduce your results, including (but not limited to) any relevant setup, terminal commands, or changing relative paths.

• Anything else we need to know about running your project!

Your instructions should be detailed enough that your mentor can run your code to reproduce any of the results in your report. You can assume the reader of your instructions is familiar with programming environments in Python and that they have read your report. You should not assume your mentor will spend time “figuring out” how to run your project with anything outside of your instructions. Make sure your instructions are clear and unambiguous.

You may optionally include an environment setup file (such as environment.yml or requirements.txt) in your repository if you used a virtual environment for your development. Be sure to highlight this in your README.md so it is clear how to setup this environment!

Submissions and Grading¶

You will be graded on the quality and thoughtfulness of your report and code, so make sure you are giving adequate time to each section.

There will be no resubmissions or late work accepted since this assignment is a project component. Make sure that you are managing your time wisely!

Submit your work on Gradescope by August 16th 2026, 11:59pm PST. Make sure to submit your report as a PDF, which should include a link to your repository containing your README as a Markdown file titled README.md, and at least three Python modules (two for your analysis, and one for your testing file)! Feel free to include any other development files as you see fit.

We will grade based on the quality of the code written, analysis done, and quality of the report overall. The following are not comprehensive but encompass the major areas in which your projects are assessed:

• Does the report have all of the required components?

• Is the report comprehensive and coherent?

• Are the conclusion drawn from the results valid and explained well, with clearly articulated limitations and impacts of the work?

• Does the code meet the requirements and include appropriate forms of testing?

• Does the code you wrote demonstrate a sufficient challenge from the perspective of our challenge goals?

We will reward projects that go above and beyond the assignment requirements to produce outstanding results and reflection. Examples of ways that projects can exceed expectations include:

• Exceptionally well-designed code that solves a complex problem

• An exceptionally sophisticated and/or engaging report

• An analysis that accurately conveys depth of the research area and engages with current scholarship in that area

• Nuanced discussion that conveys in-depth consideration for the limitations and impacts of the results

Such projects may earn up to 2 bonus points for quality and complexity of the report and code.

Note: “Above and beyond” does not mean more. Writing more code or adding more research questions or text to your report doesn’t necessarily make it a better project. This is more about the quality of the project and the depth that it solves the problem.

Submit Report & Code