A template for reproducible papers

Writing fully reproducible papers is something everyone talks about but very few people actually do. Following nice examples I’ve seen developed by others (see here and here), I wanted to develop a GitHub template that I could easily use to organize the analysis I perform for each paper. I wanted it to be useful for the Reed group in general, but also anyone else who’d like to use it, so the version I’m presenting today is an initial version that will be adapted and evolve as our needs grow.

The template can be found here: https://github.com/antonia-had/paper_template and this blogpost will discuss its contents. The repository is set up as a template, so you can use “Import repository” when you create a new repository for your project or click on the green “Use this template” button on the top right.

The idea is that everything is organized and documented well so that another person can easily replicate your work. This will help with your own tools being more widely used and cited, but also future group members to easily pick up from where you left. The other selfish way in which this has helped me is that it forces me to spend some time and arrange things from the beginning so I can be more organized (and therefore more productive) during the project. Most importantly, when a paper does get accepted you don’t need to go back and organize everything so it looks halfway decent for a public repository. For these reasons I try to use a template like this from the early stages of a project.

A lot of the template is self explanatory, but I’ll go through to explain what is in it in short. The idea is you take it and just replace the text with your own in the README files and use it as a guide to organize your paper analysis and results.

There are directories to organize your content to code, data, and results (or anything else that works for you). Every directory has its own README listing its contents and how they should be used. All code that you didn’t write and data that you didn’t generate need to be cited. Again, this is useful to document from the beginning so you don’t need to search for it later.

Most of my work is done in Python, so I wrote up how to handle Python dependencies. The way I suggest going about it is through a ‘.yml‘ file that specifies all the dependencies (i.e. all the packages and versions your script uses) for your project. I believe the best way to handle this is by creating a Python environment for every project you work on so you can create a separate list of dependencies for each. We have a nice blogpost on how to create and manage Python environments here.

When the project is done and you’re ready to submit or publish your paper, export all dependencies by running:

conda env export > environment.yml --no-builds

and store your environment.yml in the GitHub repository. When someone else needs to replicate your results, they would just need to create the same Python environment (running conda env create --file environment.yml) before executing your scripts.

Finally, you could automate the analysis and figure production with a makefile that executes your scripts so who ever is replicating does not need to manually execute all of them. This also helps avoiding somebody executing the scripts in the wrong order. An example of this can be found in this template. The makefile can also be in Python, like Julie did here.

In recognition that this is not an exhaustive template of everything one might need, the aim is to have this blog post and the template itself evolve as the group identifies needs and material to be added.

WordPress: How to post a Screenr/YouTube video

Update: As of October 2015, Screenr has been discontinued.

As a guide for other folks trying to post videos on this blog (and, I suppose, on WordPress in general), here is the workflow:

  1. Create an account on screenr. In order to make a video, simply press Record and follow the instructions.
  2. After your video is done, it will give you a link to a screenr video. You can simply post a link to this video and have the users navigate to it on their site. The cooler thing to do, though, is to embed the video on YouTube. So…
  3. Create an acccount on YouTube. Nowadays you can link your Google account so it’s very seemless.
  4. Back in Screenr, click Publish to YouTube. It will ask for your YouTube name and password. The video is automatically sent to YouTube, and you have to navigate back to the YouTube page to manage it. As it explains on the screen, it may take a few minutes for the transfer to complete.
  5. In YouTube, navigate to My Videos to manage your new video. One suggestion is to make the video Unlisted, which means that you need a direct link in order to watch it. In the Advanced tools, make sure Enable Embedding is clicked.
  6. Click Watch on Video Page to see what the video will look like inside YouTube. Then, click Share, and then Embed to get the Embed code. Copy it to the clipboard.
  7. Now we’re ready to make our WordPress post. Log in to WordPress. Navigate to the WordPress “dashboard” to create a new post (you want to be in the Dashboard to get all the advanced settings for a full post, not just the quick post editor). Type a description of your video. When you’re ready to put the YouTube embed code, open the “Text” tab in the editor and paste the embed code.
  8. Publish the WordPress post and you’re done!

Some WordPress Tips

When you log in to wordpress, there should be a gray bar at the top that has your username. If you click your username, you’ll be taken into a screen that has all sorts of helpful links on the left hand side. Here you can create posts and edit existing ones. The editor that you reach from this menu seems better than another editor I’ve seen pop up, so use this one.

A few helpful features:

  • “Upload/Insert” allows you to post pdfs, pictures, powerpoints, you name it.  You can upload documents you’ve already written, such as software documentation for example.
  • In the “Publish” box on the right hand side of the editor, you can set the visibility of a post to private.  Once the blog goes public, this will be important.
  • Please set “Categories” for your posts which will help organization later on.  You can add a new category, or use existing ones.  There are also “Tags” for more specific content organization, but we haven’t really decided how to use one versus the other yet.
  • The following page talks about posting source code on WordPress.
  • If you have changed a page (like I did with this one) and want to move it up to the top of the blog, just change its publishing date to today’s date!
  • Tags allow us to be more easily found through WordPress.  Try to add them if you can!

As usual please feel free to add more WordPress tips to this post as we go along!

Publishing websites at Penn State

Here’s how to make a basic website at Penn State and some tips on getting started with HTML/CSS.

Most students should already have web space set up through personal.psu.edu, such as my personal site.  To access it, you can use portal.psu.edu.  Click “log in”, and then access the file transfer utility.  Anything you upload to the /www/ folder will be available through your personal site.  Penn State launched an “e-portfolios” initiative a few years ago, with a nice site with web publishing advice.  I haven’t checked it out in a while, but I remember there were some good resources there.

As far as website design, I’d recommend checking out free design template resources such as freecsstemplates.org.  That cite uses CSS templates, which stands for Cascading Style Sheets.  The idea is that the CSS file controls all the design (the background color, the fonts, what links look like, etc.) and you just have to add content through html code.  The html commands are pretty basic, and there is a starter html page included at the free CSS website that should help you get started.

Alternatively, you can use a hosting site such as wordpress, such as what handles this blog.  It’s great for news-style posts, but not as good if you want to have permanent content such as a resume or sets of links.