Working in the Lab

Research is complex, and we need to work hard to keep things organized and coordinated. To make this as simple as possible, I ask that all lab members use a similar workflow. The components of this workflow are outlined below.

Lab space and key contacts

In Case of Emergency:

Campus police

  • Emergency: 978-934-4911

  • Non-emergency: 978-934-2398

EHS

Matt’s cell number (emergencies only): See canvas on the General channel in the lab Slack

Important Links

Lab GitHub
Lab Notebooks
Utilities and Protocols
Schedule a meeting with Matt
Nutrient Media Calculator
Culture Maintenance Logger
Lowell Canal Collection Logger

Key Spaces

Matt’s Office - Olsen 205
Lab - Olsen 613
Small Autoclave: Olsen 608
Large Autoclave: Olsen 618
DI water: Olsen 608
Field gear storage: TBD
Freezer farm: Olsen 618G

Protocols and resources

General protocols will be maintained on the lab GitHub in the ‘Protocols’ directory in the Lab Utilities repo. Specific or modified protocols can be recorded in your lab notebook.

The Equipment List describes the lab’s main equipment, and the Media Calculator provides recipes for nutrient media.

Other shared resources:

  • Lab Utilities repo: besides protocols, this holds other lab utilities, such as the HTML data loggers and templates.
  • Zotero group library: a key shared resource. Add relevant papers for your projects to the group library so everyone can find them.
  • Lab OneDrive: has a directory for images taken on the microscope or scanner.
WarningPlaceholder

How equipment training happens (who trains you, and whether there’s a sign-off or written SOP for each piece of equipment).

Planning a project

Setting up the project and GitHub repo

The data analysis workflow is likely to be the most unfamiliar aspect when you join the lab. I expect lab members to use project folders to organize their work. We maintain a template version of a project folder that should hopefully help lay the groundwork for a project, but it is up to you to keep these repos updated.

Start new projects from the lab’s project template. A project folder holds everything for a project in one place: background material, data, scripts, and outputs. The goal is that analyses are replicable and understandable, so that anyone in the lab can follow up on a project, add to its data, or apply the same analyses later.

The lab workflow site walks through the full workflow. The key steps are below.

One-time setup

  1. Create a GitHub account, and send me your username so I can add you to the ZoopEcoEvo organization.

  2. Install R and RStudio, and Git (installation help).

  3. Connect RStudio to GitHub: create a personal access token at github.com/settings/tokens with the “repo”, “user”, and “workflow” scopes. Then in RStudio run install.packages("gitcreds") and gitcreds::gitcreds_set(), and paste in the token.

  4. Set your Git identity in the terminal:

    git config --global user.name "your_GitHub_username"
git config --global user.email "your.email@something.com"

  5. Get familiar with the basic Git terms (pull, commit, push, branch) using the resources on the Git, GitHub, R Projects, and RStudio page.

Also set these RStudio options, so your work doesn’t depend on leftover objects or your working directory:

  • In Preferences > General, uncheck “Restore .RData into workspace at startup”, and set “Save workspace to .RData on exit” to “Never”.
  • In Preferences > R Markdown, set “Evaluate chunks in directory” to “Project”.

Each work session

The main branch of a project repo is generally read-only; you do your work on your own working branch.

  1. Open the project using its .Rproj file.
  2. Pull from your working branch to make sure you’re up to date. If others are working on the project too, also pull from the main branch.
  3. Work on your code, committing as you go.
  4. Before you stop, pull once more, then push your commits to your working branch.
Note

The lab workflow site and this handbook overlap. The plan is to eventually merge the workflow site’s content into the handbook.

Stats plan

Every project needs an analysis plan before any major work on the project starts. A template analysis plan is in the Background directory of the project template. Fill it in, then go over it with me.

Writing the plan before collecting data forces you to decide what you’re measuring, how many samples you need, and how you’ll analyze them, while there’s still time to change course. Your analysis plan should also include:

  • How samples will be labeled
  • Naming conventions for samples, files, and variables
WarningPlaceholder

Whether plans should include a power analysis or sample size justification, and when to consult a statistician.

Running experiments

One other thing to consider when planning out your schedule is the availability of equipment (microscopes, respirometers, incubators, etc.). If you are planning experiments that will take up lots of space or run for an extended time, make sure to bring it up during lab meeting. It is your responsibility to make sure these plans won’t interfere with other things going on in the lab.

Major experiments should be announced on Slack and at lab meeting, with at least a little information about which cultures and equipment you’ll be using, so other people can plan around them and avoid conflicts. Put major blocks of lab or field work on the lab calendar.

Before you start an experiment

During the experiment

Update your lab notebook at least daily, including transcribing any handwritten notes. If you’re recording data on paper datasheets, move the data into a CSV file and add it to the project’s GitHub repo within a week, if not sooner.

If something goes wrong partway through, write down what happened in your lab notebook right away, while the details are fresh. Then let me know, and we’ll decide together whether to continue, adjust, or restart. Problems are a normal part of running experiments; what matters is that they’re recorded and dealt with quickly.

Field work and safety

All lab members need to pay close attention to training materials and to strictly adhere to safety regulations both in the lab and in the field.

WarningPlaceholder

To be written.

Possible content:

  • Required EHS training
  • Field trip planning: float plans, check-in/check-out, buddy system, weather
  • Boat and water safety
  • Field gear checkout and cleaning
  • Permits and site access
  • Emergency procedures (see Lab Space and Key Contacts)

Data management

Lab notebooks

Lab members should use Obsidian as a digital lab notebook. This lab notebook will be pushed to GitHub at regular intervals. A template version of what this could look like is available on the lab GitHub. If you’d like to use a physical lab notebook, you must transcribe all information to the digital version daily.

Structure

The README file in the template lab notebook provides detailed information about the structure and function of the lab notebook. In brief, the basic components of your lab notebook are a section for daily entries (summaries of lab/work activities on a day-by-day basis), a section for experiments (details about a specific experiment you’re running), and a section for projects (a summary of a larger project, which can be used to outline the basic aims and experimental components). You should also have a section for protocols if you ever need to modify one of the lab’s basic protocols for your specific projects.

Beyond these components, though, you can expand your lab notebook however you see fit. My lab notebook, for example, also has my meeting notes, and sections that help me keep track of progress on manuscripts and grant proposals. I also use Obsidian to organize my reading notes - you can pull bibliographic information, annotations, snapshots, comments, etc. from Zotero into a note in Obsidian, which I’ve found can be really helpful for linking what you’re reading to what you’re working on. Remember, though, that your lab notebooks are open to the lab. The method we use to set up our lab notebooks means that there should be part of your vault that is not synced to the GitHub - you can use that portion for anything non-lab notebook related.

Function

Your lab notebook is a place to record anything and everything you do over the course of the day. Your lab notebook is, of course, where you record information about experiments you run in lab. But these notebooks are also useful because they’re used to record other information as well. Jot down an interesting observation you made while sorting through a plankton tow, or notes about an experimental design you’re thinking about. Outline bits of code you’re working on (it can be particularly useful to keep track of code you’ve tried that didn’t work, so you can avoid trying that same approach again later). Record culture maintenance activities along with any observations about the cultures at that point in time (this information can be extremely useful down the road), or the details about a field site visit. All of these components can be time-stamped, meaning you can track your day or coordinate next steps on a project (follow up samples after 24 hours, for example).

As is often said, your lab notebook should contain enough information that someone can repeat your work. It’s worth remembering that often the “someone” who’s trying to repeat your work is you, a couple months later. You’ll be surprised how quickly you forget key details about what you did… The lab notebook can be your guarantee you’ll remember information down the road. The more detail you record the better. I’ve never read a lab notebook entry and thought “wow this is too detailed”, but I have frequently read lab notebooks and thought “wow there is nowhere near enough detail here”.

While the GitHub repo will keep track of past versions, it’s best practice to never alter, remove, or delete sections of your lab notebook entries (just like with physical notebooks). If you’re making additions or comments on past entries, you must clearly indicate them as such.

Data files

Whenever possible, data will be recorded in .csv files. As a general principle, I expect you to record raw data in these files - any alterations, modifications, transformations, etc. should be done programmatically (e.g. with R). Excel files can be useful as calculators, but should not be used to store data.

Data recorded on paper datasheets need to be entered into a CSV file and added to the project’s GitHub repo within a week of collection, if not sooner. Raw data files are treated as read-only and should never be overwritten; processing scripts read in the raw data and save processed data separately.

WarningPlaceholder

To be written.

Possible content:

  • Folder structure and file naming for raw data
  • Metadata and data dictionaries
  • Backups and archiving (GitHub, university storage, data repositories like Dryad or Zenodo)

Coding and data analysis

As you work, you should regularly push changes to GitHub. To add these changes to the main branch will, however, require a code review process since these GitHub repos are one of the main public-facing access point for the data and code involved in a project. These code reviews are an early check for mistakes, but will also go over clarity and accessibility. Remember that as an open science lab, the availability and accessibility of data and code is a key consideration.

Tools and style

Analyses in the lab are done in R. You don’t need to be an expert when you join, but you do need at least basic R skills before starting on a project. Analyzing your own data is one of the best ways to build them. I primarily work in the tidyverse and recommend you do too. Coding style is mostly up to you; see the notes on coding style on the workflow site.

Requesting a code review

  1. In RStudio, do a final pull and push, so your working branch on GitHub has all your changes and any merge conflicts are caught.
  2. On GitHub, open a new pull request from your working branch into main.
  3. Request reviewers. I’m notified automatically; you can also tag other lab members, but be considerate of their time.
  4. Say which files you’d especially like reviewed.

Reviewers usually start with the output in the Reports directory, since it shows both the code and the figures, then look at scripts and data if time allows. They’ll leave comments or merge your work into main. If more work is needed, keep working on your branch and include “Ready for Review” in your commit message when you’d like another look. Once a branch is merged, start a new branch for your next goal.

For small questions that don’t need a full review, raise them at our regular meeting, or open a GitHub issue on the repo with the file name and line number. Please don’t send code by email; keep it on GitHub.

See Pull Requests on the workflow site for more detail.

Learning resources