Deliverables - Code/Report

Submission¶

Deliverables - Report/Code: due Monday 08/15 at 11:59 pm

• Meet with Mentor Meet with your TA mentor to discuss your Proposal feedback and plans for the main project deliverables sometime before this due date.
• Report Your full report (5+ pages) written document as a PDF and name it report.pdf. Do not turn in a Word Document or plain text file.
• Code All code and test files, including documentation.
  • Instructions Including relevant instructions to run your program in a file called README.md.

All submissions will use Gradescope. Due to grading restrictions, we are unable to accept late submissions or resubmissions. If you are not done by the due date, you will need to submit what you have before the due date passes.

When submitting, we recommend making a zip file of your whole project folder and submitting that to Gradescope so you only have to submit one file. Most operating systems come with a built-in feature to make a zip archive of a folder on your computer, so you should search how to do so on your computer. As mentioned before, we do not require that you submit your data to Gradescope if it is too large to upload; but if you don’t include your data in your submission your report needs to have clear instructions on how to get your data.

Note: If you are using git to help manage your project, please do not submit the hidden .git folder in your project; one way to do this is to copy your project files to another folder and make a zip of this new folder when you submit.

Meet with Mentor¶

At some point before turning in your project, you should reach out to your TA mentor to discuss their feedback on your Proposal and any plans you might have to change your project. This is a very valuable time to get a second-opinion on any planned changes to your work.

You should meet with your mentor sooner than later to give you the most time to plan your work for the final project before the due date. There is no formal due date to meet with your mentor except before the deliverables due date of Monday 08/15. We recommend finding a time to meet with your mentor before Monday, August 8.

Report¶

Submit a roughly 5+ page report documenting your findings. Annotate and explain how your visualizations were produced and contribute to the narrative or analysis. 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. 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. If you plotted by hand, explain why it was not possible to create the plot you wanted in Python and what you have tried.
7. 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.
8. 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.
9. 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?
10. 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!
11. Collaboration State the other people and resources that you consulted during the project aside from the course staff and team members.

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.
• 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 important details.
• Your code will need to be broken up into at least two Python modules (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.

Instructions¶

Along with your code, you should submit 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:

• You should write instructions for us to run your project to reproduce your results. Tell us which Python modules to run to get your results and anything else we need to do to run them.
• If there is anything we need to do to set up your project, like install libraries or how to download your data (if you did not submit it), give us instructions for how to do so.
• 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 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 so make sure your instructions are clear and unambiguous.

Grading¶

As this is the main part of the project, we outline the grading of the whole project here. The entire project (including the Proposal, Presentation, and Feedback components) will be graded on a scale of 8 points.

The project will be graded on the following rubric:

• 4 points - Completion. Making an non-trivial effort to complete all of the project requirements on-time.
  • 1 point: Proposal
  • 1 point: Deliverables - Code/Report
  • 1 point: Meet with TA mentor
  • 1 point: In-Person/Video Presentation & Peer Feedback
• 4 points - Project Quality. Based on the quality of the code written, analysis done, and quality of the report overall. Here are some areas your projects are assessed:
  • Does your report have all of the required components?
  • Does the code you wrote adequately demonstrate a challenge from the perspective of our challenge goals?
  • Are the conclusion drawn from the results valid and explained well?
  • Does the report articulate well the limitations and impact of the work?

The criteria for the project is designed such that a project that “meets expectations” (according to the requirements in the specification) will receive a score of 6 points out of the 8 possible. 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 very well designed code that solves a complex problem, a report that is written extremely well, an analysis that accurately conveys depth of the research area, or discussion that conveys depth in consideration for the limitations and impacts of the results.

Note that we don’t use percentages at all in this course, so it is incorrect to interpret a 6/8 as 75%. We use the score of 6/8 as a default for a project well done! The points above 6/8 are intended to provide reward for very high quality projects.