Laboratory Write-Up and Submission

CSC 262 - Computer Vision - Weinman

Summary:: Information about expectations for laboratory exercises and methods for preparing to submit them.

english 1 Overview
2 Laboratory write-ups
3 Laboratory programs: scripts and functions
    3.1 Lab script
    3.2 Functions
4 References and Academic Honesty Certification
    4.1 Note on Image Credits
5 Submitting your work
6 Notes on grading
    6.1 Requirements
    6.2 Style

1 Overview

This course features weekly laboratory exercises, as listed on the course schedule.

Unless otherwise stated:

Collaboration with anyone other than the students your lab group is not allowed on laboratory exercises.
You may use the MathWorks' Matlab language reference (i.e. documentation) to determine relevant Matlab syntax and semantics. This will be considered "general knowledge", and you need not cite reference sources. However, if you use approaches found in the examples or elsewhere, such use requires citation.
In working on the labs, you may consult only our lab manual, textbooks, and MathWorks references for information. All non-syntax consultations (including the textbook and Matlab references) require formal citation within the related program or writeup.
If you copy and paste code snippets from a lab web page, you must cite the source of the code.
You always may consult the instructor.

Laboratory submissions will generally consist of two parts:

A complete prose write-up consisting of complete sentences and accompanying images or figures, with headings as appropriate.
The Matlab script and any additional function .m files used to produce your results or required by the lab manual.

These are to be written and submitted using the guidelines below.

2 Laboratory write-ups

Matlab features a convenient way to integrate writing and code via a function called publish, which you will use to create a write-up for each lab. For the specific contents of a lab writeup, please follow the directions within that lab on what is to be included. In general, your write-up must consist of:

Headings to easily separate the various sections of your write-up. Please do not use the lab manual's section headings and letter labels. Instead, use headings that naturally guide the reader through the story you are telling.
A brief introduction to the lab summarizing the technique(s) and subject(s) being explored as well as your purpose or objective. A good introduction will also highlight/preview/summarize the forthcoming conclusion.
As appropriate to the lab (its exercises and deliverables), prose descriptions of your approach to solving the problem at hand.
- Include the values of any model parameters you used (even if the manual specifies them).
Figures (images and/or graphs) inlined at appropriate places in the text. Your text should refer to the figures where appropriate. Note also that:
- Almost every figure should have a title (i.e., using title).
- Graphs should always have axis labels (i.e., using xlabel and ylabel).
- Many graphs should use curve legends (i.e., using legend).
As directed by the lab assignment, a section describing your observations about the behavior of the algorithm (i.e., stability, uniqueness, reliability, etc.).
- When making observations, be sure to tell the reader not only what the phenomena are, but where they should look for themselves to confirm them
A brief conclusion summarizing your results and analysis. A good conclusion will also suggest an actionable lesson or take-away.
Acknowledgments or citations for the source of any code or raw image data (even if they are provided with the lab), ideas, assistance, etc.

Because most of our labs are tightly focused, the overall text you may need to write will not be great, though the reports may seem longer due to the inclusion of many images.

You must also submit your write-up as a (generated) PDF file.

DO NOT INCLUDE YOUR NAMES unless otherwise directed. Because your submission will be graded anonymously, you must not place your name in any file except the references/honesty file, below. Failure to heed this guideline will result in a one-letter grade deduction penalty for the assignment.

3 Laboratory programs: scripts and functions

In preparing any scripts or programs for the course, please follow these formatting guidelines.

3.1 Lab script

The first line of your Matlab lab file should be comments giving the title of the lab as a section header. For example,

: %% CSC 262 Lab: Hough Transforms

You should read and bookmark the Publishing Markup guide on how to format inline comments for integration in your write up.

Inline comments are expected for explaining your code, but these should not be included in as part of your writeup. For example

: %% E. Section Header
% This text is included with the narrative

% This comment is for the code, but is not published
plot(sin(linspace(0,2*pi,50)); % This plot *is* published!

%%
% This comment is published without a new section header in a paragraph
% immediately below the plot.

Note that the Matlab editor will auto-format (i.e., line wrap) your comments with the keyboard command Alt+Q, and will auto-indent your code with the keyboard command Ctl+Alt+/.

The file houghlab.m gives a terse example of a Matlab script for an imaginary lab conforming to these guidelines. You can run and publish the script on the MathLAN.

Publish your file to PDF without including the code in the report as follows:

: publish('labfilename.m','format','pdf','showCode',false);

This creates the file html/labfilename.pdf under the folder containing labfilename.m.

3.2 Functions

In addition to the corresponding course lab title, formal documentation is required for every definition of a Matlab function, stating in English what that program unit is supposed to do. Documenting before you write a procedure can help you plan and clarify the requirements of your implementation. For example,

: function N = estimateNoise(X,Y,Z)
% ESTIMATENOISE Estimates the noise in a sequence of three images
%
% N = ESTIMATENOISE(X,Y,Z) where X, Y, and Z are grayscale images
% (all of the same dimensions) and N is a matrix of the same size
% containing the noise estimate -- a standard deviation
% of the values at each pixel in the sequence.
%
%
% CSC 262 Lab: Image Formation

As shown above, formal documention should include the summary line, the signature line(s), where the type, dimension, and meaning are given for each parameter and return value, as well as any additional information about the function's operation.

4 References and Academic Honesty Certification

Each and every lab write-up must include a single file, references.txt, with the following information (sources, help, certification) completed.

: Academic honesty certification:
  Written/online sources used:
    [include textbook(s), CSC 262 labs or readings;
     use complete citations for Web or other written sources;
     write none if no sources used]
  Help obtained
    [indicate names of instructor, class mentors
     or evening tutors, consulted according to class policy;
     write none if none of these sources used]
  Our initials below confirm that the above list of sources
  is complete AND that I/we have not talked to anyone else
  (e.g., CSC 262 students) about the solution to this problem
  Initials:  ABC, DEF

4.1 Note on Image Credits

Please note, I have seen enough lab reports with copy and pasted text from the lab to keep the Committee on Academic Standing's subcommittee on Academic Honesty busy for the rest of the academic year.

Let us be clear: if you EVER copy and paste anything into your work, you MUST give direct attribution to the source AND use quotation marks! That's not just for this class, that's the rest of your professional career.

If you have forgotten this important lesson in tutorial and literally copy the lab manual prose about the provenance of the images and paste it into your own lab work, the casual reader would think you wrote these words.

Even though giving an acknowledgment (thanks!), it still does not mean you can or should plagiarize.

The lab manual pages have been careful to state the terms under which we have used the images in the lab; this is not only the correct legal thing to do, but also helps you understand what you are able to do with them.

You might or might not want to give full legal terms in your own report, but you do still need to give some form of credit for the images, either by direct quotation (yes, that's laborious), or by giving the credit in your own words. You are relaying information, not an argument, so in my opinion that would not be the sort of paraphrase (a term you should have learned about in tutorial) that warrants citation.

I want you to become accustomed to citing the sources of your images, because too few computer vision researchers are in the habit of doing so, and it's an intellectual shortcoming our field.

In sum: A generic nod in the references.txt isn't sufficient when you directly copy/paste. For example, by the same token, if you lift a quote from a book and written it into your paper, including that book in your bibliography is not enough. You must also use quotation marks and a direct citation.

5 Submitting your work

You will have multiple files to submit (at the very least a PDF and a Matlab file along with your references.txt). One group member should submit your files online to the corresponding assignment on Gradescope by the due date. Submit each file individually; do not create an archive or zip file.

Only one submission per project group is required; please be sure to add all group member's names to the submission. Although only a single submission is required, all group members are jointly responsible for ensuring a submission is made. For example, if your partner told you they would submit the project but forgets to do so, all group members will incur late penalties. For this reason, I recommend submitting work while you are sitting together.

The assignment drop-box is configured to accept re-submissions. Only the last submission will be downloaded, but if you repeat a submission all required files must be re-uploaded (even if only one changed). The timestamp of the last submission will be used to determine when the assignment was completed (for assessing any late penalties).

6 Notes on grading

6.1 Requirements

When a lab write-up is submitted according to the format specified above, it should be understood that the images and figures accurately reflect the output from the accompanying program. Anything otherwise may raise questions of academic honesty; and, by College policy, any evidence of academic dishonesty must be turned over to the Academic Standing Committee for action.

6.2 Style

Every programming task should yield readable and tested code. Because code maintainability is an important part of development, your labs' code will be graded in part on style, as well as correctness. After all, if I cannot understand your code (or it takes me too long to), I cannot give it a grade regarding its correctness.

Some style matters I care about:

Indentation and whitespace that help delineate code blocks. (Most editors will help you with this.)
Helpful comments on blocks of code or particularly complicated expressions
Functions that are reasonably short. A very good guideline I try to follow is getting an entire procedure to fit on much less than one screen; this makes interpreting a function's action more readable by forcing you to break it down into named steps that can be seen at once. It also promotes easier debugging and unit testing.
Code and comment lines that are no wider than 80 characters. This makes them easier to read both on screen and on paper. The built-in Matlab editor gives you a helpful gray line that your code should not extend past.
Using reasonably meaningful variable names and no hard-coded "magic" numbers.

Failure to incorporate these style considerations will lower your grade.

You should also generate the habit of using the linter checkcode to assess potential problems with and clean up your scripts/programs.

Acknowledgments

Adapted from Assignments for Computer Science 213, Henry Walker; and CSC213, Fall 2006 : Laboratory exercises, Janet Davis. Some of the style considerations were adapted from Marge Coahran's.