Working on code projects

Please refer to the video below to accompany the written tutorial on this page.

First of all, if you are about to work on a project locally on your computer, make sure you have the latest version of the g6tr package, because it contains all our helper functions for managing projects. On RStudio Workbench we have a managed shared library where all new versions will appear as they are developed. So you’ll have this automatically.

To update g6tr locally, open the monorepo project and run:

install.packages("g6tr")

Normally to install packages from private package repositories like ours you need to assure that HTTPUserAgent option contains the right key value. We’ve set up .Rprofile files in our repository such that it is done automatically and you don’t need to worry about it. In case if you still have any problems please address to this paragraph for how to set up the HTTPUserAgent option.

Formerly, when we did not have RStudio Workbench, we used to create a new Amazon ec-2 instance for each project we had to work on. This, although not being particularly convenient, naturally allowed us to have multiple sessions set in different git branches and be able to quickly switch between them. If you have just one copy of a repository, you can’t do this without first committing all the changes.

In RStudio Workbench there’s just one cloud setup that is accessed via a single URL, r.gradientmetrics.com. But this isn’t a problem at all. Each Workbench user may have as many sessions as they want and nobody stops users from having multiple copies of a single repository.

You can create a new copy by running a git clone command or by starting a new RStudio project and setting the github origin as a source. This won’t be lightning-quick because our repository is already quite big, but shouldn’t take horribly long either. Anyways, to make this more convenient and quicker, we’ve created:

• RStudio project template - start a new RStudio Project, select “New Directory”, scroll down and select the “G6TR Monorepo” template.

• A Helper function - just run g6tr_clone_monorepo("<some name>") and it will create a correspondingly named monorepo copy inside the “monorepos” folder in your home directory.

In either way an on-server monorepo copy will be used to speed up the process. To have this functionality, you need to have g6tr version >= 1.0.0 installed.

So how would it work in practice? Let’s say you’re working on Project A and have lots of uncommitted changes, and suppose you need to implement some quick updates for Project B. If you don’t want to finalize you work on Project A just yet, you can create a new monorepo copy to work specifically on project B in this project’s dedicated git branch. And this can be done as follows:

1. Create a new project from the “G6TR Monorepo” selecting the “open in new session” option. Or start a new session, run g6tr_clone_monorepo("project_b") and open monorepos/project_b folder in your home manually.

2. If B is a new project, create a project skeleton for it with g6tr_setup(). More on this to follow. If there’s already a folder for B, open the corresponding RStudio project and start a new branch.

Each client project has a dedicated main vignette and folder inside the “packages/g6tr.projects/vignettes” folder.

• packages
  • g6tr.projects
    • vignettes
      • yyyy-mm-dd_project_name.Rmd ← Main project vignette
      • yyyy-mm-dd_project_name ← Project subdirectory
        • 001_libraries.Rmd
        • 100_read_data.Rmd
        • 101_prep_data.Rmd
        • 200_analysis.Rmd
        • R ← This is where you write your custom functions
          • helper_function1.R
          • helper_function2.R
      • yyyy-mm-dd_some_other_project.Rmd
      • yyyy-mm-dd_some_other_project
        • …

The main project vignette is its cover. It does not contain any analysis it should only contain things like project overview, relevant links and discussions. Analysis happens in .Rmd scripts inside the project directory.

All the projects have 001_libraries.Rmd, 100_read_data.Rmd and 101_prep_data.Rmd scripts. The first one mainly deals with managing packages used in the project and setting up development environment. The next two are for reading data (e.g. from Qualtrics) and converting it to a tidy format correspondingly.

The other scripts are less standard. If, let’s say, your project has a maxdiff analysis and a segmentation, you may have “210_md.Rmd” and “220_segmentation.Rmd”. If your project has a crunch dashboard, the code for it is typically stored in “900_crunch.Rmd”.

You may want to create a set of custom functions for a project. Please put these functions into *.R scripts in the “R” directory of the project.

For Newsletter projects the setup is the same, only projects are located inside “packages/g6tr.voice/vignettes”.

We’ve made an effort to automate project creation and things related to managing project coding environment as much as possible. This resulted in a set of helper functions in our main g6tr package. Please check out the vignette covering these functions. In addition, the videos below show you how to use the base of these.

Starting a new client project

Continue working on a new client project

RStudio Workbench provides a way for live collaboration inside the same project folder. This is kind of like working on shared documents in Google Docs. But you and your collaborator will have separate R sessions, so you will not share the console and environment of each other. The drawback is that you can’t actually see what your collaborator has in memory, but you can replicate the same state by running the same set of scripts, and then you can work on the project in tandem.

To share a project, click the projects drop-down menu at the top right and click “Share Project…”.

We typically store project input data and project models on S3. For outputs that we’d like to share, we use Google Drive. We have a set of helper functions that makes it easy to upload and download files to and from both storage types. For the full overview, please see the vignette.

Sooner or later you’ll have to push the project code you’ve been working on to github. You’d first create a draft pull request to the master branch, ask an appropriate team member for a review and then this PR will be merged. This process is described in more detail in the coding at gradient vignette.

Before you ask someone to review your branch and before that person merges the code into /master please make sure you have done the following:

Checklist

• Check that your main vignette is buildable with knitr.
• Write a short readme (in yyyy-mm-dd_project_name.Rmd) entry in the g6tr.project directory with an overview of the project. Include as much information as you can (links, discussions, jira tags, whatever you can think of).
• Convert the draft PR into a regular Pull Request.
• Fix all errors that the automated builds catch if you made changes to functions in the packages.