|
Expected Preparations:
|
|||||||||||||||
|
|
|||||||||||||||
| Keywords: Course- or lab journal; Time management | |||||||||||||||
|
|
|||||||||||||||
|
Objectives:
|
Outcomes:
|
||||||||||||||
|
|
|||||||||||||||
|
Deliverables: Your Journal. |
|||||||||||||||
|
|
|||||||||||||||
|
Evaluation: Your entire journal will be evaluated at the end of the course. Refer to the marking rubrics for details. |
|||||||||||||||
Work through this unit, then make your work with the Academic Integrity Unit the first entry of your Journal!
Keeping a journal is an essential task in a laboratory. To practice keeping a technical journal, you will document your activities as you are working through the material of the course. A significant part of your term grade will be given for this Course Journal. This unit introduces components and best practice for lab- and course journals. But keep one principle in mind for this course: you are writing this journal for yourself, not for us.
Caution:
Your course journal is a deliverable of this course and it will be graded. Therefore all rules regarding plagiarism and other academic misconduct apply in full. In particular:
do not include any material from elsewhere without referencing it. We are operating a “full disclosure” policy in this course. Anything that you did not write yourself, on the spot, must be referenced. In particular you need to reference if you are copying your own material from other courses;
do not fabricate material that you are posting in your journal. Fabrication could include things like: modifying results produced by your code, describing work that you have not actually done, or claiming a time for the journal entry that is not the time/date on which it was actually written. All of these are academic offences.
Note:
Only journal entries that were written concurrently with the activity they describe will be evaluated for credit.
Note:
All journal pages — like all other submitted material — must be licensed under a CC-BY license.
Computational research embraces the same best-practice principles as any wet-lab experiment. We ensure our work is reproducible, we take great care that our conclusions are supported by data, and we keep notes to document our objectives, activities and how we arrived at our results. Those notes are more than just a handy collection of information: they need to become a robust, testable record of activities.
Paper notes are not very useful for bioinformatics work because they can’t be cross-referenced easily with computer files. Ideally, bioinformatics journals will document results, and link to data files, code repositories, webpages and other resources. Thus whatever software you use, it needs to support incorporating or linking to results, data, code, workflow scripts, documentation, and much more. In the past, we have used the open source Media Wiki software to support journal keeping in this course, now we are switching to cloud-based solutions. This follows current practice in many of our research laboratories.
Keeping a record of your activities is a habit, and habits need to be formed through practice. Is this going to be useful to you? I don’t know, but neither do you, unless this habit has been given a credible chance to form. Therefore we practice keeping journals in this course. As a welcome side effect, this creates a record of activities for future reference, and provide a basis for evaluation of your progress at the end of the course. Keeping a journal will help you work with other learning units or project components effectively, because this is all integrated over the entire course, and later units often make use of earlier results which you should have easily accessible.
Remember: you are writing a lab notebook—not a formal lab report. This is a point-form record of your actual activities.1 Write such documentation as notes to your (future) self. Record everything that’s necessary, but be light and agile about your writing.
Write your notes immediately, in parallel with your actual activities, don’t draft them elsewhere and expect to enter and revise them later. Practice shows that delayed processing of journal notes creates an unmanageable burden. Therefore notes that are not written concurrently with the activity will not be considered for credit in this course. This too is about habit forming. But writing concurrently is so easy: since all of your computational work is done with a computer, just begin every work-session by opening an editing window for its journal entry. Have the window open, and immediately record everything of importance. Your Google Doc is online, so you can even edit your journal from a library computer, or even dictate your notes into your phone.
Obviously, the first step is to create a journal in your shared Google Drive folder; you have already set up your folder in the previous unit.
The following points are suggestions. It is up to you to find out what is most useful for you.
Write a header and give it a unique number. This is useful so you can refer to the header number in later text or cross-reference easily. It is useful to add any new contents at the top of the page. Keeping the page in reverse chronological order, prevents you having to scroll to the bottom of the page every time you add new material. Note though, that the sections do not actually have to be in strict chronological order, like we would have them in a paper notebook. Typically you would number in a decimal system - like 1, 1.1, 1.2, 2, 3 etc. - so you can easily accommodate additions or insertions; the journal does not have to be organized in an exactly linear fashion, although you will probably find that you remember things in an approximately sequential way and that helps you find things.
It may be advantageous to give different subprojects their own numbering space - by adding a prefix to the section number. This depends on how related the projects are. Everything you keep on the same web page is easy to find with your browser’s search function. But if search results come from different projects, that may be inconvenient. To decide what to put on the same page and what should go in different subpages, imagine what kind of material you would search for and what search terms you might use.
Incidentally: the material in a Google Doc is “permanent”, since earlier versions of pages are always available via the version history. The versions are automatically time-stamped. And that’s actually a step beyond paper labnotes.
State the objective. In one brief sentence, restate what your activity is supposed to achieve.
Estimate duration. The learning units in this course require you to estimate beforehand how long you will take, and to record how much time you actually took. Record your initial estimate (work-hours), how many hours you took, and how much time elapsed between start and end of your task. Make this a habit in your future coursework as well as in your future labwork. You will quickly note that you will become much better at time-management. See the sample journal.
Note what you have done, as concisely as possible but with sufficient detail. “What is sufficient detail?” The answer is easy: detailed enough so that someone can reproduce what you have done. In practice that “someone” will usually be you, yourself, in the future, at a time when you have forgotten what exactly you were thinking when you wrote the journal. If you think about this, you will realize that it is important to write your entries so they can largely stand on their own: you won’t be reading the entire journal when you need to look up something. It is a bit of a challenge to find the right belance between being redundant, and being too brief.
You can distinguish different types of results - * Static data does not change over time and it may be sufficient to note a reference to the result. For example, there is usually no need to copy a GenBank record into your documentation, it is sufficient to note the accession number, the refSeq ID, or the UniProt ID, or even better, to link to the relevant page on the external database server. Of course, there are exceptions, e.g. when you want to annotate the record. * Variable data can change over time. For example the results of a BLAST search depend on the sequences that have been deposited in the database. A list of similar structures may change as new structures get solved and deposited in the PDB database. In principle you want to record such data, to be able to reproduce at a later time what your conclusions were based on. But be selective in what you record. For example you should not paste the entire set of results of a BLAST search into your document, but only those matches that were important for your conclusions. Indiscriminate pasting of irrelevant information will make your notes unusable. You may want to keep such material in an appendix, or in a seperate document that you link to. * Analysis results, such as the results of sequence analyses, alignments etc., in general get recorded in your documentation. Again: be selective. Record what is important.
Note your conclusions. An analysis is not complete unless you conclude something from the results. * Are two sequences likely homologues, or not? Just pasting the BLAST output is not enough. It’s your call - record it. * Does your protein contain a signal-sequence or does it not? SignalP will give you a probability, but you must make the final call. * Is a binding site conserved, or not? The programs can only point out sections of similarity or dissimilarity. You are the one who interprets these numbers in their biological context.
The analysis provides the data. In your conclusion you provide the interpretation of what the data means in the context of your objective. Were you expecting a signal-sequence but there isn’t one? What could that mean? Sometimes your task will explicitly include to elaborate on an analysis and conclusion. But this does not mean that when analysis is not explicitly mentioned, you can skip the interpretation. In general you can never expect full marks if analysis and conclusions are missing.
Write a brief outlook. What’s the next step? Write this down to remind you of your thinking at that point. But again: avoid being formulaic. You are writing for yourself, not fo us. And we can tell the difference.
Use discretion when uploading images. Don’t upload irrelevant images, don’t upload copyrighted images.
Image dimensions and resolution. Stereo images should have equivalent points displayed approximately 6cm apart. You can rescale the image in yourt document to achieve this. If your assigment or learning unit ask you to prepare stero images: adjust your images to this separation. Also, scale your molecules so they fill the available window and - if you have depth cueing enabled - move them close to the front clipping plane so the molecule is not just a dim blob, fading into murky shadows. When assignments or learning units ask you to create images of molecules, always create stereo views.
Keep your images uncluttered and expressive. Scale the molecular model to fill the available space of your image well. Orient views so they illustrate a point you are trying to make. Emphasize residues that you are writing about with a contrasting colouring scheme. Add labels, where residue identities are not otherwise obvious. Turn off side-chains for residues that are not important. The more you practice these small details, the more efficient you will become in the use of your tools.
To keep code samples readable, your code must be formatted in a fixed-width font (never use a proportionally spaced font for code!), and you must use syntax highlighting. But how? Discuss on the Forum.
I have prepared an example folder that you may access, and from which you can copy or download material to reuse for your own files (and improve upon).
You should be familiar with the following:
If in doubt, ask! If anything about this contents is not clear to you, do not proceed but ask for clarification. If you have ideas about how to make this material better, let’s hear them. We are aiming to compile a list of FAQs for all learning units, and your contributions will count towards your participation marks.
[END]
I have come across “journal entries” that consist only of copy/pasted learning unit objectives… I was not impressed.↩︎