jdblischak/git-for-science

A quick introduction to version control with Git and GitHub

A quick introduction to version control with Git and GitHub

This paper has been published (link to final version) as part of the PLOS Computational Biology Education Collection.

Synopsis and Motivation

This is the repository for the paper "A quick introduction to version control with Git and GitHub". The goal of this paper was to introduce scientists to the concepts behind version control (using Git) so that they can incorporate these practices into their workflows. The manuscript was written using the Authorea platform.

In the manuscript, we encourage readers to practice using GitHub by contributing to this repository. The full details are explained in the section Contribute to other projects, but briefly the steps are:

• Fork the repository
• git clone the fork locally
• Add a file called {GitHub_username}.txt to the readers folder (replace {GitHub_username} with your own GitHub username)
• git add + git commit
• git push the commit to GitHub
• Issue a Pull Request (PR) to incorporate the change into this repository

Take a look in the readers folder to see all of the contributions from anyone who has had a Pull Request accepted. If you haven't contributed already, we'd love to see your PR!

Example code

The example code, which were provided as supplementary files, can be found in the sudirectory code. If you're interested in running the scripts, please see the README in that directory for instructions.

Build the document

The full tex file and compiled PDF can be obtained from the "Export document" on the Authorea page for this article. Choose the PLOS 2015 template for the best results.

However, to both maintain a presentable version for display on Authorea (e.g. contain the figures) and a version that complies with the PLOS submission guidelines (e.g. only contain figure captions but not images), we created a custom Python script to build the final TEX and PDF files for submission. Run it as follows:

python build-full-article.py > blischak-et-al.tex

You should be able to run it with either major version of Python. We were able to run it with either Python 2.7.10 or Python 3.4.3.

Contributors

Thank you to all of our contributors!

License

CC BY 3.0. Please see the file license for the full legal text.

git-for-science's Issues

Format reference numbering in References section

"Your references need to be formatted according to the NLM/ICMJE standard reference style. PLOS uses the numbered citation [citation-sequence] method and first six authors, et al. Authors should be listed as ""Last name, First Initial"". Please note that references should be cited in square [ ] brackets and not round ( ) brackets to ensure that they are correctly typeset. Additionally, the reference list should be formatted as “1.” and not “[1]”. Please see our Author Guidelines for further information and examples: http://www.ploscompbiol.org/static/guidelines#references

Authorea uses the 2009 version of the PLOS bibtex style file. Everything seems in accordance with the exception of the numbering in the References section. Ours has "[1]" instead of "1". I've included the 2015 version in the repo for building locally, so I may need to build the final version locally.

remove pdf output from repository

First: Great paper. I will recommend this to my students.

One thing that might be a bit inconsistent... In the paper it states:

...things not to version control are large data files that never change, binary files (including Word and Excel documents), and the output of your code.

it would there be more consistent to remove the generated pdf output from the repository

Provide figures in RGB

-Figures 1-4 have been submitted in CMYK, a color space which we do not accept for Figure files. Please provide us with Figures in RGB. File --> Document Color Mode --> RGB Color.

Add definition of version control system (VCS) to Box 1

‘Conclusions’ is not a valid main heading for PLOS papers.

‘Conclusions’ is not a valid main heading for PLOS papers. Please ensure that this is set as a subheading, or removed completely from the manuscript.

I am confused about this one. The word "Conclusions" never appears in our document. We have a section titled "Conclusion", but it is the same header level as the titles of all of our other sections.

Other PLOS Computational Biology papers with a section titled "Conclusion":

• Chimusa, 2015
• Aoki-Kinoshita, 2008
• Budd et al., 2015

Check that all the web links included in your manuscript are functional and amend or remove if necessary

Improve typesetting of Table 1

The center justification makes it difficult to read.

http://journals.plos.org/ploscompbiol/s/latex
http://journals.plos.org/ploscompbiol/s/tables

Remove the numbering system from headings and subheadings

http://journals.plos.org/ploscompbiol/s/latex

Fix table formatting

Table 1 looks good on Authorea (link). However, once it is exported, it is too wide to fit on the page.

Remove automatic numbering of figures

On Authorea, the figures only display their caption. Thus we have labeled the figures how we want. However, when exported, LaTeX also adds automatically generated labels. This creates duplicate labels, and also labels S1 Figure as Figure 4.

Place the legend/ caption for each figure after the paragraph in which it is first mentioned in the manuscript file

Please place the legend/ caption for each figure after the paragraph in which it is first mentioned in the manuscript file. SI legends should remain at the end of the file.

This will be done only on the "production" branch.

Handle missing fonts in figures

-When opening Figures 1-4 we are receiving a missing font error message (MyriadProBold).

-When opening Figures 1, 3, and 4, we are receiving a missing font error message (CourierBold).

To ensure that your Figures publish properly, please convert the text in your Figures to outlines (in Illustrator: Select>All, then Type>Create Outlines.

(http://www.ploscompbiol.org/static/figureGuidelines.action#outlines) Alternately, you may submit your figures as high resolution (300-600 dpi) RGB TIFF files, within our limitations on dimensions. When submitting TIFFs, you must submit them in 8-bit RGB and save using LZW compression .(http://www.ploscompbiol.org/static/figureGuidelines.action#lzw) in order to reduce file size. If you encounter the “ICC Profile is present” error, that is an error message that you can ignore.)

Indicate the corresponding author with an asterisk and list this author’s email address on the title page of the manuscript

Convert figures from svg to eps

svg images display on Authorea, but cannot be used when exporting to pdf.

Remove the copies of your figures from the manuscript file

We don't want to remove the figures from the version on Authorea, so I'll create a new branch named "production" for changes like these.

Change dimensions of Fig. 4

-Figure 4 exceeds the dimension limits for Figures (look at your
Figures in Outline View to see how). Figures must be less than 19.05
cm in width, and less than 22.225cm in height. When determining
artwork dimensions we measure from edge to edge, horizontally and
vertically, including any frames or boxes surrounding the artwork.
Please make the necessary adjustments and re-upload your Figures.

Cite your figures in the style “Fig. 1”, “Fig. 2”

Directly embed references in tex file

Please remove the .BIB/.BBL file and include your references directly in the .TEX file, as per our template. For more information, see http://journals.plos.org/ploscompbiol/s/latex.

Supporting Information Legends

Please create a new section in your manuscript titled “Supporting Information Legends” directly following the “References” section. In this section please include a legend for all supporting information files. Your supporting information files should be titled and cited in the following style: “S1 Data”, “S2 Data”, “S3 Data”. Please ensure that each supporting information item is cited at least once in the text. Additional information can be found here: http://www.ploscompbiol.org/static/supportingInformation#captions