Skip to main content

WEEL Guide

3 Projects

3.1 Project structure

Some example structures:

project
└───data/
    └───derived/
    └───raw/
└───R/
└───script/
└───graphics/
└───README.md

or

project/
└───README.md
└───input/
└───output/
└───R/
└───graphics/

We’ll use the SocCaribou project as an example throughout the following sections.

3.1.1 README

A README.md file should always be included and stores plenty of information about the project. Installation instructions, TODOs, description or purpose of the project, authors, news, known bugs or limitations, instructions for contributing, link to license, etc.

For example, the SocCaribou README:


## Space-use and social organization in a gregarious ungulate: testing the conspecific attraction and resource dispersion

[![DOI](https://zenodo.org/badge/173167283.svg)](https://zenodo.org/badge/latestdoi/173167283)

  - Authors:
      - Mélissa Peignier
      - [Quinn M.R. Webber](https://qwebber.weebly.com/)
      - [Erin Koen](https://sites.google.com/site/erinlkoen/)
      - [Michel P. Laforge](https://mammalspatialecology.weebly.com/)
      - [Alec L. Robitaille](http://robitalec.ca)
      - [Eric Vander Wal](http://weel.gitlab.io)

This repository contains the code accompanying the paper “Space-use and
social organization in a gregarious ungulate: testing the conspecific
attraction and resource dispersion”. Scripts are under `scripts/` and
reused functions are in `R/`. This project uses standard R package
structure and can therefore be installed with `devtools`. This also
helps declare external package dependencies required for the analysis.
Please note that while functions are included here, they are not tested
for use in other projects and may not be suitable (at least not in their
current version).

## Abstract
Animals use a variety of proximate cues to assess habitat quality when resources
vary spatiotemporally. Two non-mutually exclusive strategies to assess habitat
quality involve either direct assessment of landscape features or observation of
social cues from conspecifics as a form of information transfer about forage
resources. [...]

Other examples:

More on README’s * Make a README * Github’s About READMEs

3.1.2 Scripts

R scripts can be organized into scripts/ and R/. The scripts/ folder holds analysis scripts, often (ideally) numbered in the order they should be run in. For example, in the SocCaribou project there’s 1-Data-Cleaning.R then 2-HomeRangeAnalysis.R. See Jenny Bryan’s project oriented workflow.

The R/ folder is used for functions. Functions help us chunk out larger project into manageable pieces of code. This section of the targets manual has a great overview of the two approaches.

It doesn’t have to be one or the other - if you have a discrete chunk of code that needs to be applied multiple times, or might be useful in another project, etc, just write it as a function and drop it into your R/ folder. In addition, the R/ folder is recognized if you turn your project into a package or a research compendium as the standard place and structure for functions.

See the SocCaribou project that has both an R/ folder and a scripts/ folder.

SocCaribou
├── R
│   ├── dynamic_network.R
│   ├── hr_network.R
│   └── step_length.R
├── scripts
│   ├── 1-DataCleaning.R
│   ├── 2-HomeRangeAnalysis.R
│   ├── 3-SiteFidelityAnalysis.R
│   ├── 4-SocialNetworkAnalysis.R
│   ├── 5-Randomizations.R
│   ├── 6-MergeTidyFiles.R
│   └── 7-DataAnalysis.R
...

3.1.3 Data

Always start with raw data. Keep raw data raw in a raw-data/ folder.

Then use scripts to prepare and organize your data - never modify it by hand. This way, you can go always go back to the raw data in case anything changes in your preparation steps.

Intermediate and output data can be sorted into input/ and output/ folders and saved as an .Rds files using the base R functions: saveRDS() and readRDS(). More details in Efficient R / Binary file formats. Or if you use data.table, use fread and fwrite to read/write CSV files. If your dates are stored in the ISO standard format, they will be automatically converted to POSIXct by fread.

3.2 Metadata

Keep track of where the raw data comes from, how it was generated, by who, when, etc using metadata. See the metadata project. Use this project to write metadata for your data. Talk to Alec about contributing/using it!

https://weel.gitlab.io/metadata

3.2.1 Etc

Other elements include:

  • LICENSE file - Choose an open source license
  • graphics/ or figures/ folder for figures and plots
  • manuscript/ or paper/ folder for storing the manuscript
  • man/ folder for storing the documentation of your functions
  • Keep a ChangeLog / News file. Traditionally in the R community, it is stored in a NEWS.md file.

3.3 RStudio projects

Always work within RStudio Projects to avoid setwd() hell. If you share an RStudio Project (.RProj) with someone else, they can immediately use it without changing working directories or paths to files.

Details: Efficient R / Project Management and Project oriented workflow

3.4 Slides

Slides and Resources