- FAIR @@ -343,7 +350,7 @@
- In cases where you’re developing a novel method or workflow, structuring your code in this way will increase the odds that someone outside of your team will adopt your strategy -
- Carefully load packages and record package versions -
- All changes between raw data and the final data should be done with scripts -
- Workflow should be divided into logical, modular scripts (e.g., wrangle vs. analyze vs. graph) -
- Portable code (i.e., transferable) uses relative file paths -
- Choose a logical coding style and stick with it -
- Concise and descriptive object names (and variable names) -
- Use spaces between operators and after commas -
- Indentation should be consistent about tabs vs. spaces -
- Code should be thoroughly documented with comments
- Comments should focus on “why” of operations rather than “what” (assumes code is being read by a person who can interpret the ‘what’ by scanning the code) @@ -443,8 +447,8 @@
- Low (ish) effort way to increase reproducibility is to use extensive/clear comments
- If an operation is duplicated more than 3 times within a project, write a custom function to centralize the work
- If an operation is duplicated across more than 3 projects, consider creating an R package diff --git a/search.json b/search.json index 8a09de1..4c6bb16 100644 --- a/search.json +++ b/search.json @@ -304,7 +304,7 @@ "href": "mod_reproducibility.html#reproducible-coding", "title": "Reproducibility Best Practices", "section": "Reproducible Coding", - "text": "Reproducible Coding\nNow that you’ve organized your project in a reasonable way and documented those choices, we can move on to principles of reproducible coding! Doing your data operations with scripts is more reproducible than doing those operations without a programming language (i.e., with Microsoft Excel, Google Sheets, etc.). However, scripts are often written in a way that is not reproducible. A recent study aiming to run 2,000 project’s worth of R code found that 74% of the associated R files failed to complete without error (Trisovic et al. 2022). Many of those errors involve coding practices that hinder reproducibility but are easily preventable by the original code authors.\n\nWhen your scripts are clear and reproducibly-written you will reap the following benefits:\n\nReturning to your code after having set it down for weeks/months is much simpler\nCollaborating with team members requires less verbal explanation\nSharing methods for external result validation is more straightforward\nIn cases where you’re developing a novel method or workflow, structuring your code in this way will increase the odds that someone outside of your team will adopt your strategy\n\n\nSession Information\n\nCarefully load packages and record package versions\n\n\n\nScript Organization\n\nAll changes between raw data and the final data should be done with scripts\nWorkflow should be divided into logical, modular scripts (e.g., wrangle vs. analyze vs. graph)\nPortable code (i.e., transferable) uses relative file paths\n\n\n\nCode Style\n\nChoose a logical coding style and stick with it\nConcise and descriptive object names (and variable names)\nUse spaces between operators and after commas\nIndentation should be consistent about tabs vs. spaces\n\n\n\nCode Comments\n\nCode should be thoroughly documented with comments\nComments should focus on “why” of operations rather than “what” (assumes code is being read by a person who can interpret the ‘what’ by scanning the code)\nCode tells the computer what to do, comments tell the human what we’re telling the computer to do\nLow (ish) effort way to increase reproducibility is to use extensive/clear comments\n\n\n\nConsider Custom Functions\n\nIf an operation is duplicated more than 3 times within a project, write a custom function to centralize the work\nIf an operation is duplicated across more than 3 projects, consider creating an R package\nCustom functions should be written “defensively”\n\nAnticipate/identify likely errors and code custom warning/error messages that clearly identify how to fix them\nKey is to “fail fast” and ensure code throws an error as soon as something unexpected happens rather than doing a bunch of processing and failing later on because of something that could be identified early on", + "text": "Reproducible Coding\nNow that you’ve organized your project in a reasonable way and documented those choices, we can move on to principles of reproducible coding! Doing your data operations with scripts is more reproducible than doing those operations without a programming language (i.e., with Microsoft Excel, Google Sheets, etc.). However, scripts are often written in a way that is not reproducible. A recent study aiming to run 2,000 project’s worth of R code found that 74% of the associated R files failed to complete without error (Trisovic et al. 2022). Many of those errors involve coding practices that hinder reproducibility but are easily preventable by the original code authors.\n\nWhen your scripts are clear and reproducibly-written you will reap the following benefits:\n\nReturning to your code after having set it down for weeks/months is much simpler\nCollaborating with team members requires less verbal explanation\nSharing methods for external result validation is more straightforward\nIn cases where you’re developing a novel method or workflow, structuring your code in this way will increase the odds that someone outside of your team will adopt your strategy\n\n\nPackages, Namespacing, and Software Versions\nOne of the first things that every script should begin with is an explicit loading of all libraries that script need (these are called “dependencies). Scripts that don’t specify which libraries are needed are unlikely to run on anyone’s computer. Unfortunately, many R packages need to be installed by each user before they can be loaded with the library function. You may find it simpler to use the librarian package which automatically detects and installs needed packages if they are not already present. Note that users would still need to install librarian itself!\nIt is also strongly recommended to “namespace” functions everywhere you use them. In R this is technically optional (Python requires this) but it is a really good practice to adopt, particularly for functions that may appear in multiple packages with the same name but do very different operations depending on their source. Namespacing in R is done by adding the package name and two colons before the function name (e.g., dplyr::mutate). This prevents accidental use of functions from the ‘wrong’ package for a given context.\nYou may also need to consider the version of the packages that you’re using and the version of R. The sessionInfo function (from the utils package loaded into R by default) is a good way of capturing some of this information but it is relatively high level and lacks sufficient detail for many contexts. For a more complete amount of information, consider using the renv or packrat packages.\n\n\nScript Organization\nEvery change to the data between the initial raw data and the finished product should be scripted. The ideal would be that you could hand someone your code and the starting data and have them be able to perfectly retrace your steps. This is not possible if you make unscripted modifications to the data at any point!\nYou may wish to break your scripted workflow into separate, modular files for ease of maintenance and/or revision. This is a good practice so long as each file fits clearly into a logical/thematic group (e.g., data cleaning versus analysis).\nFinally, your code should never use absolute file paths. Absolute file paths are those that begin at the root of your entire computer (“C:…” on Windows and “~…” on Mac). Such paths are inherently not reproducible as the odds of anyone having the exact same absolute file path are extremely slim. Instead, using relative file paths that begin at the project folder is preferable. These are transferable among users. You can even use R’s file.path function to automatically detect the correct direction of slashes between folders to make it easier to collaborate across operating systems! Note in the above figure from Trisovic et al. (2022) that many scripts that set the working directory manually had errors until that bit was removed. Avoid setting the working directory explicitly and instead structure your project such that relative paths within the project folder will always succeed.\n\n\nCode Style\nWhen it comes to code style, the same ‘rule of thumb’ applies here that applied to project organization: virtually any system will work so long as you (and your team) are consistent! Thtat said, there are a few principles worth adopting if you have not already done so.\n1. Use concise and descriptive object names\nIt can be difficult to balance these two imperatives but short object names are easier to re-type and visually track through a script. Descriptive object names on the other hand are useful because they help orient people reading the script to what the object contains.\n2. Don’t be afraid of space!\nScripts are free to write regardless of the number of lines so do not feel as though there is a strict character limit you need to keep in mind. Cramped code is difficult to read and thus can be challenging to share with others or debug on your own. Inserting an empty line between coding lines can help break up sections of code and putting spaces before and after operators can make reading single lines much simpler.\n\n\nCode Comments\n\nCode should be thoroughly documented with comments\nComments should focus on “why” of operations rather than “what” (assumes code is being read by a person who can interpret the ‘what’ by scanning the code)\nCode tells the computer what to do, comments tell the human what we’re telling the computer to do\nLow (ish) effort way to increase reproducibility is to use extensive/clear comments\n\n\n\nConsider Custom Functions\n\nIf an operation is duplicated more than 3 times within a project, write a custom function to centralize the work\nIf an operation is duplicated across more than 3 projects, consider creating an R package\nCustom functions should be written “defensively”\n\nAnticipate/identify likely errors and code custom warning/error messages that clearly identify how to fix them\nKey is to “fail fast” and ensure code throws an error as soon as something unexpected happens rather than doing a bunch of processing and failing later on because of something that could be identified early on", "crumbs": [ "Quantitative Modules", "Reproducibility" diff --git a/sitemap.xml b/sitemap.xml index 3fe90a6..cc39a50 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -2,78 +2,78 @@
Project
Folder Structure
The simplest and often most effective way of beginning a reproducible project is adopting (and sticking to) a good file organization system. There is no single “best” way of organizing your projects’ files as long as you are consistent. Consistency allows those navigating your system to deduce where particular files are likely to be without having in-depth knowledge of the entire suite of materials.
-
+
To begin, it is best to have a single folder for each project. This makes it simple to find the project’s inputs and outputs and also makes collaboration and documentation much cleaner. Later in your project’s life cycle, this ‘one folder’ approach will also make it easier to share your project with external reviewers or new team members. For researchers used to working alone there can be a temptation to think about your leadership of a project as the fundamental unit rather than the individual projects’ scopes. This method works fine when working alone but greatly increases the difficulty of communication and co-working in projects led by teams. RStudio (the primary Integrated Developer Environment for R) and most version control systems assume that each project’s materials will be placed in a single folder and either of these systems can confer significant benefits to your work (well worth any potential reorganization difficulty).
Within your project folder, it is valuable to structure your folders and files hierarchically. Having a folder with dozens of mixed file types of various purposes that may be either inputs or outputs is cumbersome to document and difficult to navigate. If instead you adopt a system of sub-folders that group files based on purpose and/or source engagement becomes much simpler. You need not use an intricate web of sub-folders either; often just a single layer of these sub-folders provides sufficient structure to meet your project’s organizational needs.
@@ -411,31 +418,28 @@ Reproducible CodingSharing methods for external result validation is more straightforward
-Session Information
-
-
+
+Packages, Namespacing, and Software Versions
+One of the first things that every script should begin with is an explicit loading of all libraries that script need (these are called “dependencies). Scripts that don’t specify which libraries are needed are unlikely to run on anyone’s computer. Unfortunately, many R packages need to be installed by each user before they can be loaded with the library function. You may find it simpler to use the librarian package which automatically detects and installs needed packages if they are not already present. Note that users would still need to install librarian itself!
+It is also strongly recommended to “namespace” functions everywhere you use them. In R this is technically optional (Python requires this) but it is a really good practice to adopt, particularly for functions that may appear in multiple packages with the same name but do very different operations depending on their source. Namespacing in R is done by adding the package name and two colons before the function name (e.g., dplyr::mutate). This prevents accidental use of functions from the ‘wrong’ package for a given context.
+You may also need to consider the version of the packages that you’re using and the version of R. The sessionInfo function (from the utils package loaded into R by default) is a good way of capturing some of this information but it is relatively high level and lacks sufficient detail for many contexts. For a more complete amount of information, consider using the renv or packrat packages.
-
-Script Organization
-
-
+
+Script Organization
+Every change to the data between the initial raw data and the finished product should be scripted. The ideal would be that you could hand someone your code and the starting data and have them be able to perfectly retrace your steps. This is not possible if you make unscripted modifications to the data at any point!
+You may wish to break your scripted workflow into separate, modular files for ease of maintenance and/or revision. This is a good practice so long as each file fits clearly into a logical/thematic group (e.g., data cleaning versus analysis).
+Finally, your code should never use absolute file paths. Absolute file paths are those that begin at the root of your entire computer (“C:…” on Windows and “~…” on Mac). Such paths are inherently not reproducible as the odds of anyone having the exact same absolute file path are extremely slim. Instead, using relative file paths that begin at the project folder is preferable. These are transferable among users. You can even use R’s file.path function to automatically detect the correct direction of slashes between folders to make it easier to collaborate across operating systems! Note in the above figure from Trisovic et al. (2022) that many scripts that set the working directory manually had errors until that bit was removed. Avoid setting the working directory explicitly and instead structure your project such that relative paths within the project folder will always succeed.
-
-Code Style
-
-
+
+Code Style
+When it comes to code style, the same ‘rule of thumb’ applies here that applied to project organization: virtually any system will work so long as you (and your team) are consistent! Thtat said, there are a few principles worth adopting if you have not already done so.
+1. Use concise and descriptive object names
+It can be difficult to balance these two imperatives but short object names are easier to re-type and visually track through a script. Descriptive object names on the other hand are useful because they help orient people reading the script to what the object contains.
+2. Don’t be afraid of space!
+Scripts are free to write regardless of the number of lines so do not feel as though there is a strict character limit you need to keep in mind. Cramped code is difficult to read and thus can be challenging to share with others or debug on your own. Inserting an empty line between coding lines can help break up sections of code and putting spaces before and after operators can make reading single lines much simpler.
-
-Code Comments
+
+Code Comments
Code Comments
-
-Consider Custom Functions
+
+Consider Custom Functions
https://lter.github.io/ssecr/mod_facilitation.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.768Z
https://lter.github.io/ssecr/topic_interactivity.html
- 2024-02-07T18:58:35.685Z
+ 2024-02-07T20:05:42.772Z
https://lter.github.io/ssecr/mod_spatial.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.768Z
https://lter.github.io/ssecr/topic_spatial.html
- 2024-02-07T18:58:35.685Z
+ 2024-02-07T20:05:42.772Z
https://lter.github.io/ssecr/mod_data-viz.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.768Z
https://lter.github.io/ssecr/index.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.768Z
https://lter.github.io/ssecr/mod_reports.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.768Z
https://lter.github.io/ssecr/mod_version-control.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.772Z
https://lter.github.io/ssecr/mod_data-disc.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.768Z
https://lter.github.io/ssecr/mod_reproducibility.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.768Z
https://lter.github.io/ssecr/CONTRIBUTING.html
- 2024-02-07T18:58:35.661Z
+ 2024-02-07T20:05:42.748Z
https://lter.github.io/ssecr/mod_project-mgmt.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.768Z
https://lter.github.io/ssecr/mod_wrangle.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.772Z
https://lter.github.io/ssecr/mod_findings.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.768Z
https://lter.github.io/ssecr/mod_credit.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.768Z
https://lter.github.io/ssecr/mod_thinking.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.768Z
https://lter.github.io/ssecr/mod_stats.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.768Z
https://lter.github.io/ssecr/mod_logic-models.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.768Z
https://lter.github.io/ssecr/mod_team-sci.html
- 2024-02-07T18:58:35.681Z
+ 2024-02-07T20:05:42.768Z
Folder Structure
The simplest and often most effective way of beginning a reproducible project is adopting (and sticking to) a good file organization system. There is no single “best” way of organizing your projects’ files as long as you are consistent. Consistency allows those navigating your system to deduce where particular files are likely to be without having in-depth knowledge of the entire suite of materials.
-
To begin, it is best to have a single folder for each project. This makes it simple to find the project’s inputs and outputs and also makes collaboration and documentation much cleaner. Later in your project’s life cycle, this ‘one folder’ approach will also make it easier to share your project with external reviewers or new team members. For researchers used to working alone there can be a temptation to think about your leadership of a project as the fundamental unit rather than the individual projects’ scopes. This method works fine when working alone but greatly increases the difficulty of communication and co-working in projects led by teams. RStudio (the primary Integrated Developer Environment for R) and most version control systems assume that each project’s materials will be placed in a single folder and either of these systems can confer significant benefits to your work (well worth any potential reorganization difficulty).
Within your project folder, it is valuable to structure your folders and files hierarchically. Having a folder with dozens of mixed file types of various purposes that may be either inputs or outputs is cumbersome to document and difficult to navigate. If instead you adopt a system of sub-folders that group files based on purpose and/or source engagement becomes much simpler. You need not use an intricate web of sub-folders either; often just a single layer of these sub-folders provides sufficient structure to meet your project’s organizational needs.
Reproducible CodingSharing methods for external result validation is more straightforward
Session Information
--
-
Packages, Namespacing, and Software Versions
+One of the first things that every script should begin with is an explicit loading of all libraries that script need (these are called “dependencies). Scripts that don’t specify which libraries are needed are unlikely to run on anyone’s computer. Unfortunately, many R packages need to be installed by each user before they can be loaded with the library function. You may find it simpler to use the librarian package which automatically detects and installs needed packages if they are not already present. Note that users would still need to install librarian itself!
It is also strongly recommended to “namespace” functions everywhere you use them. In R this is technically optional (Python requires this) but it is a really good practice to adopt, particularly for functions that may appear in multiple packages with the same name but do very different operations depending on their source. Namespacing in R is done by adding the package name and two colons before the function name (e.g., dplyr::mutate). This prevents accidental use of functions from the ‘wrong’ package for a given context.
You may also need to consider the version of the packages that you’re using and the version of R. The sessionInfo function (from the utils package loaded into R by default) is a good way of capturing some of this information but it is relatively high level and lacks sufficient detail for many contexts. For a more complete amount of information, consider using the renv or packrat packages.
Script Organization
--
-
Script Organization
+Every change to the data between the initial raw data and the finished product should be scripted. The ideal would be that you could hand someone your code and the starting data and have them be able to perfectly retrace your steps. This is not possible if you make unscripted modifications to the data at any point!
+You may wish to break your scripted workflow into separate, modular files for ease of maintenance and/or revision. This is a good practice so long as each file fits clearly into a logical/thematic group (e.g., data cleaning versus analysis).
+Finally, your code should never use absolute file paths. Absolute file paths are those that begin at the root of your entire computer (“C:…” on Windows and “~…” on Mac). Such paths are inherently not reproducible as the odds of anyone having the exact same absolute file path are extremely slim. Instead, using relative file paths that begin at the project folder is preferable. These are transferable among users. You can even use R’s file.path function to automatically detect the correct direction of slashes between folders to make it easier to collaborate across operating systems! Note in the above figure from Trisovic et al. (2022) that many scripts that set the working directory manually had errors until that bit was removed. Avoid setting the working directory explicitly and instead structure your project such that relative paths within the project folder will always succeed.
Code Style
--
-
Code Style
+When it comes to code style, the same ‘rule of thumb’ applies here that applied to project organization: virtually any system will work so long as you (and your team) are consistent! Thtat said, there are a few principles worth adopting if you have not already done so.
+1. Use concise and descriptive object names
+It can be difficult to balance these two imperatives but short object names are easier to re-type and visually track through a script. Descriptive object names on the other hand are useful because they help orient people reading the script to what the object contains.
+2. Don’t be afraid of space!
+Scripts are free to write regardless of the number of lines so do not feel as though there is a strict character limit you need to keep in mind. Cramped code is difficult to read and thus can be challenging to share with others or debug on your own. Inserting an empty line between coding lines can help break up sections of code and putting spaces before and after operators can make reading single lines much simpler.