Deliverables - Code/Report

Submission¶

*Deliverables - Code/Report due Wednesday 08/16 at 11:59 pm *

The following components are required:

• Report Your full report (5-15 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.

The following components are not required but highly recommended: * 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.

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 Wednesday 8/16. We recommend finding a time to meet with your mentor before Monday, August 14.

Report¶

Submit a roughly 5+ 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. 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.

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 must have the title report.pdf (exactly as such!) in order to be counted on Gradescope.
• The report is not to exceed 15 pages. This is a hard limit. 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.

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 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.

Instructions¶

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

• 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.

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 6 points.

The project will be graded on the following rubric:

• 3 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: Video Presentation
• 3 points - Project Quality. 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?
  • Does the video presentation effectively communicate the methodology and analysis described in the report?

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.

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