Chapter 3 Your Course Journal

(How to keep a course- or lab journal)

3.1 Overview

3.1.1 Abstract:

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 and includes a wiki-source template to begin your own journal on the Student Wiki.

3.1.2 Objectives:

  • Introducing components and best practice of lab- and course journals
  • Presenting sample wiki-text for Journal entries

3.1.3 Outcomes:

Upon concluding this unit you should be able to …

  • Begin a structured course journal on the Student Wiki using proper wiki text;
  • Write your own journal entries, including media images and code as required;
  • Cross-reference journal entries with links;
  • Link to external sources and deliverables on internal pages as appropriate;
  • Estimate the time you need for tasks, and develop a habit of improving your time-management skills.

3.1.4 Deliverables:

  1. Your Journal: Your entire journal will be evaluated at the end of the course. Refer to the marking rubrics for details.
  2. Insights: If you find something particularly noteworthy about this unit, make a note in your insights! page.
  1. 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 on the Student Wiki—like all other submitted material—must contain a {{CC-BY}} template.

3.1.5 Prerequisites:

You need the following preparation before beginning this unit. If you are not familiar with this material from courses you took previously, you need to prepare yourself from other information sources:

  • ‘’’Inquiry’’’: The scientific method; evidence based reasoning; how to design, execute and document an experiment; Conjecture, hypothesis and theory.
  • ‘’’Writing’’’: Basic essay and report writing skills. How to format your submitted materials, how to quote, cite and avoid plagiarism.
  • This unit builds on material covered in the following prerequisite units:

Work through this unit, then make your work with the “Plagiarism” Unit the first entry of your Journal!

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 a technical solution needs to support incorporating or linking to results, data, code, workflow scripts, documentation, and much more. In this course, we use the open source Media Wiki software to support journal keeping.

Here are some alternative applications – but (!) disclaimer, I myself don’t use any of these (yet):

  1. Evernote - a web hosted, automatically syncing e-notebook.
  2. Nevernote - the Open Source alternative to Evernote.
  3. Google Keep - if you have a Gmail account, you can simply log in here. Grid-based. Seems a bit awkward for longer notes. But of course you can also use Google Docs.
  4. Microsoft OneNote - this sounds interesting and if any one is using this, I’d like to hear from you. Syncing across platforms, being able to format contents and organize it sounds great.
  5. RStudio projects - for development-focussed work – especially (but not exclusively) – in R, an RStudio project may be the right solution to keep your code, results, notes, manuscript drafts, literature and other assets all in one place. The great benefit is that it can all be under version control and it’s super easy to share everything with colleagues on a team through GitHub Technically, GitHub documents are all publicly accessible if they are stored in repositories of free accounts - but you can commit binary files, so you can simply keep sensitive material in password-protected .zip files or otherwise encrypted.. The only downside that I can think of is that it’s not possible to cross-reference and link to material.

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: a point-form record of your actual activities.3 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, begin every work-session by opening an editing window for its journal entry. Have the window open, and immediately record everything of importance. The Wiki is online, so you can even edit your journal from a library computer, and even (although it’s awkward) from your phone.

Obviously, the first step is to create a journal page in the User space of the Student Wiki - you have already done this in the Wiki editing unit.

3.3 Objective

  • State the objective.
  • In one brief sentence, restate what your activity is supposed to achieve.

3.4 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. The sample journal template that is included below contains wikitext to format a time estimate.

3.5 What to document

  • Document the procedure - 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 often be you, yourself, in the future. I hope that you won’t be constantly cursing your past-self because of omissions!
  • Document your results.
    • You can distinguish different types of results -
    1. Static data does not change over time and it may be sufficient to note a reference to the result. For example, there is 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.
    2. Variable data can change over time. For example the results of a BLAST search depend on the sequences 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.’’’ Incidentally, the technology to expand and collapse paragraphs that we demonstrated in the Wiki editing unit can be put to excellent use to record data but keep it out of sight when not needed.
    3. Analysis results - The results of sequence analyses, alignments etc. in general get recorded in your documentation. Again: be selective. Record what is important.

3.6 Conclusions

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.

3.7 Outlook for the next tasks

What’s the next step? Note it here. Also include a link to the logically next entry - this way you can quickly hop through consecutive entries for a theme.

3.8 Cross references

Add cross-references.

Cross-references to other information are supremely valuable as your documentation grows. It’s easy to see how to format a link to a section of your Wiki-page: just look at the link under the Table of Contents at the top. But you can also place “anchors” for linking anywhere on an HTML page: just use the following syntax. <span id=“{some-label}”><\span> for the anchor, and append #{some-label} to the page URL.

3.9 Media

3.9.1 Images

  • Use discretion when uploading images
  • Don’t upload irrelevant images, don’t upload copyrighted images, keep the size reasonable. Prepare your images well
  • Don’t upload uncompressed screen dumps. Save images in a compressed file format on your own computer. Then use the Image Upload link in the left-hand menu to upload images. The Wiki will only accept .jpeg, .png, .gif, or .svg images.
  • Use the correct image types.
  • In principle, images can be stored uncompressed as .tiff or .bmp, or compressed as .gif or .jpg or .png. .gif is useful for images with large, monochrome areas and sharp, high-contrast edges because the LZW compression algorithm it uses works especially well on such data; .jpg (or .jpeg) is preferred for images with shades and halftones such as the structure views you should prepare for several assignments, JPEG has excellent application support and is the most versatile general purpose image file format currently in use; .tiff (or .tif) is preferred to archive master copies of images in a lossless fashion, use LZW compression for TIFF files if your system/application supports it; The .png format is an open source alternative for lossless, compressed images.
  • .bmp is not preferred for really anything, it is bloated in its (default) uncompressed form and primarily used only because it is simple to code and ubiquitous on Windows computers. Accordingly we don’t support it here.

3.9.2 Image dimensions and resolution

Stereo images should have equivalent points displayed approximately 6cm apart. It depends on your monitor how many pixels this corresponds to. The dimensions of an image are stated in pixels (width x height). My notebook screen has a native display resolution of 1440 x 900 pixels/23.5 x 21 cm. Therefore a 6cm separation on my notebook corresponds to approximately 260 pixels. However on my desktop monitor, 260 pixels is 6.7 cm across. And on a high-resolution iPad display, at 227 ppi (pixels per inch), 260 pixels are just 2.9 cm across. If your assigment or learning unit ask you to prepare stero images: adjust your images so they are approximately at the right separation and are approximately 500 to 600 pixels wide. 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, lost in murky shadows.

Considerations for print (manuscripts etc.) are slightly different: for print output you can specify the output resolution in dpi (dots per inch). A typical print resolution is about 300 dpi: 6 cm separation at 300dpi is about 700 pixels. Print images should therefore be about three times as large in width and height as screen images.

3.9.3 Preparation of stereo views

  • When assignments or leartning 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.

3.9.4 Code

Always markup code using the GeSHi extension. This provides syntax highlighting, which is very useful to read the code. You simply place the code-block into opening- and closing “source” tags, and tell GeSHi which language it should assume. For R-code this looks like:

for i in 1:10{
  a = 1
}

You can also use GeSHi to markup plain text - (although you can achieve a similar effect by simply beginning each line with a blank " “).

Lorem ipsum dolor sit amet ...

3.10 Wikitext Template

The section below contains Wiki-markup code that you can copy and paste for your course journal.

<!-- HTML comments will not be rendered by the wiki. -->

<div class="b1">
Sample Journal
</div>

<!-- To position the table of contents at a particular position, include -->
<!-- the __TOC__ "magic text" -->

{{Vspace}}

__TOC__

{{Vspace}}

<!-- BEGIN template for one entry -->
== <my activity> ==

;Objective
: text ...

<div class="time-estimate">
Time estimated: XXX h; taken XXX h; date started: 2017-MM-DD; date completed: 2017-MM-DD
</div>

===Progress===

;Activity 1
: Notes ...

;Activity 2
: Notes ...

=== Conclusion and outlook===

Describe ...

{{Vspace}}

<!-- END of template for one entry -->


<!-- BEGIN sample entry -->

== (Example Journal Entry) Explore Cytoscape ==

;Objective
: Write R code to generate a random network. Explore it with Cytoscape.

<div class="time-estimate">
Time estimated: 2 h; taken 4 h; date started: 2017-09-16; date completed: 2017-09-18
</div>

===Progress===

;R code for a random network.
: Cytoscape can read networks in [http://wiki.cytoscape.org/Cytoscape_User_Manual/Network_Formats#SIF_format SIF format]. Wrote the following code to generate N random nodes with random interactions and write them to file.

<div class="toccolours mw-collapsible mw-collapsed" style="width:800px">
My R code below ...
<div class="mw-collapsible-content">

<source lang="R">
N <- 15  # number of nodes
nMin <- 1 # minimum number of edges
nMax <- 5 # maximum number of edges
OUT <- "myRandomSIF.txt"


# Create N random strings from three uppercase characters
# First make more than we need, because some might not be unique ...
nodes <- character(2*N)

set.seed(161803)
for (i in 1:(2*N)) {
  nodes[i] <- paste0(sample(LETTERS, 1),
                     sample(LETTERS, 1),
                     sample(LETTERS, 1))
}
set.seed(NULL)

nodes <- unique(nodes) # throw away duplicates ...
nodes <- nodes[1:N]    # ... and keep only N

# Create SIF output
mySIF <- character()

set.seed(112358)
for (myA in nodes) {  # for each node
  for (i in 1:sample(nMin:nMax, 1)) { # for a random number of interactors ...
    myB <- sample(nodes, 1)           # ... randomly choose interactor ...
                                      # ... create record and apend to mySIF
    mySIF <- c(mySIF, sprintf("%s\tpp\t%s", myA, myB)) # myA, "pp", myB
                                                       # separated by tabs
  }
}
set.seed(NULL)

# write mySIF to file
writeLines(mySIF, OUT)
</source>

</div>
  </div>

;Install Cytoscape
: Straightforward installation of <b>Cytoscape 3.5.1</b> from http://www.cytoscape.org

;Visualize and explore options
*:Worked through an introductory tutorial from http://opentutorials.cgl.ucsf.edu/index.php/Tutorial:Introduction_to_Cytoscape_3.1-part2 Noteworthy: nodes can be coloured by attribute values.
*:Loaded my own SIF file with the File → Import → Network → File option. Explored various layout options and visualization styles. Manually added nodes and edges with the options one gets when ctrl-clicking on the canvas.

{{Vspace}}

=== Conclusion and outlook===

* Creating layouts, applying styles, adding nodes and edges with Cytoscape seems straightforward and creates evocative images.
* Analyzing and interpreting the network needs more thought. Need to explore ideas and tools for network analysis next - e.g. clustering tools, enrichment tools, motif discovery ...
* Next: write some code to create attribute values for nodes, import the values, and have Cytoscape style the nodes accordingly.

{{Vspace}}

----

<!-- Footnotes -->
==Notes and References==
<references />

{{Vspace}}

<!-- Category and Footer -->
[[Category:BCH441-2019_Journal]]

----

{{CC-BY}}

<!-- END -->

3.11 Self-evaluation

  1. I have come across “journal entries” that consist only of copy/pasted learning unit objectives…↩

  2. If the Wiki automatically displays section numbers in its Table of Contents, you can turn that off in the preferences.↩

  3. Media Wiki also has its own search functions that search for material everywhere on the Wiki, but this is likely not useful on the Student Wiki where many users may be writing about similar things.↩