Merge pull request #16 from inbo/hansvancalster-patch-3

Update version_control.Rmd

Author: ThierryO

vignettes/version_control.Rmd

@@ -58,7 +58,7 @@ Version control systems like [git](https://git-scm.com/), [subversion](https://s
 
 ## Sorting observations
 
-Version control system often track changes on plain text files based on row based differences. In layman's terms it only records which lines in a file are removed and which lines are inserted at what location. Changing an existing line implies removing the old version and inserting the new one. This is illustrated is the minimal example below.
+Version control systems often track changes on plain text files based on row based differences. In layman's terms it only records which lines in a file are removed and which lines are inserted at what location. Changing an existing line implies removing the old version and inserting the new one. This is illustrated is the minimal example below.
 
 Original version
 
@@ -89,7 +89,7 @@ A,B
 +1,10
 ```
 
-Ensuring that the observations are always sorted in the same way thus helps minimizing the diff. The sorted version of the same altered version looks the the example below. 
+Ensuring that the observations are always sorted in the same way thus helps minimizing the diff. The sorted version of the same altered version looks like the example below. 
 
 ```
 A,B
@@ -98,7 +98,7 @@ A,B
 3,0
 ```
 
-Diff between original and the sorted alternate version. Notice that all changes revert to actual changes in the information content. Another benefit is changes are easily spotted in the diff. A deletion without insertion on the next line is a removed observation. An insertion without preceding deletion is a new observation. A deletion followed by an insertion is an updated observation.
+Diff between original and the sorted alternate version. Notice that all changes revert to actual changes in the information content. Another benefit is that changes are easily spotted in the diff. A deletion without insertion on the next line is a removed observation. An insertion without preceding deletion is a new observation. A deletion followed by an insertion is an updated observation.
 
 ```diff
 A,B
@@ -108,23 +108,23 @@ A,B
 +3,0
 ```
 
-This is where the `sorting` argument comes into play. If this argument is not provided when a file is written for the first time, it will yields a warning about the lack of sorting. The observations will be written in their current order. New versions of the file will not apply any sorting either. Leaving this burden to the user. This is illustrated by the changed hash for the data file in the example below, whereas the metadata is not changed (no change it hash).
+This is where the `sorting` argument comes into play. If this argument is not provided when a file is written for the first time, it will yield a warning about the lack of sorting. The observations will be written in their current order. New versions of the file will not apply any sorting either, leaving this burden to the user. This is illustrated by the changed hash for the data file in the example below, whereas the metadata is not changed (no change in hash).
 
 ```{r row_order}
 library(git2rdata)
 write_vc(x, file = "row_order", root = root)
 write_vc(x[sample(nrow(x)), ], file = "row_order", root = root)
 ```
 
-`sorting` should contain a vector of variable names. The observations are automatically sorted along these variables prior to writing. However, we now get an error because the set of sorting variables has changed. The set of sorting variables is stored in the metadata. Changing the sorting can potentially lead to large diffs, which `git2rdata` try to avoid as much as possible.
+`sorting` should contain a vector of variable names. The observations are automatically sorted along these variables prior to writing. However, we now get an error because the set of sorting variables has changed. The set of sorting variables is stored in the metadata. Changing the sorting can potentially lead to large diffs, which `git2rdata` tries to avoid as much as possible.
 
 From this moment on we will store the output of `write_vc()` in an object to minimize the output.
 
 ```{r apply_sorting, error = TRUE}
 fn <- write_vc(x, "row_order", root, sorting = "y")
 ```
 
-Using `strict = FALSE` turns such errors into warnings and allows to update the file. Notice that we get a new warning: the variable we used for sorted results in ties, thus the order of the observations is not guaranteed to be stable. The solution is to use more or different variables. We'll need `strict = FALSE` again to override the change in sorting variables.
+Using `strict = FALSE` turns such errors into warnings and allows to update the file. Notice that we get a new warning: the variable we used for sorting resulted in ties, thus the order of the observations is not guaranteed to be stable. The solution is to use more or different variables. We'll need `strict = FALSE` again to override the change in sorting variables.
 
 ```{r update_sorting}
 fn <- write_vc(x, "row_order", root, sorting = "y", strict = FALSE)
@@ -169,7 +169,7 @@ The resulting diff is maximal because every single row was updated. Yet none of
 +13,3
 ```
 
-`git2rdata` tackles this problem by storing the order of the columns in the metadata. The order is defined by the order in the dataframe when it is written for the first time. From that moment on, the same order will be reused. The example below writes the same data set twice. The second version contains the exactly the same information but randomizes the order of the observations and the columns. The sorting by the internals of `write_vc()` will undo this randomization, resulting in an unchanged file.
+`git2rdata` tackles this problem by storing the order of the columns in the metadata. The order is defined by the order in the dataframe when it is written for the first time. From that moment on, the same order will be reused. The example below writes the same data set twice. The second version contains exactly the same information but randomizes the order of the observations and the columns. The sorting by the internals of `write_vc()` will undo this randomization, resulting in an unchanged file.
 
 ```{r variable_order}
 write_vc(x, "column_order", root, sorting = c("x", "abc"))
@@ -188,7 +188,7 @@ write_vc(old, "factor", root, sorting = "color")
 print_file("factor.yml", root)
 ```
 
-Let's add an observation with a new factor level. If we store the updated dataframe in a new file, we see that the indices are different. The factor level `"blue"` remains unchanged, but `"red"` becomes the third level and get index `3` instead of index `2`. This could lead to a large diff where as the potential semantics (and thus the information content) are not changed.
+Let's add an observation with a new factor level. If we store the updated dataframe in a new file, we see that the indices are different. The factor level `"blue"` remains unchanged, but `"red"` becomes the third level and get index `3` instead of index `2`. This could lead to a large diff whereas the potential semantics (and thus the information content) are not changed.
 
 ```{r factor2}
 updated <- data.frame(color = c("red", "green", "blue"))
@@ -204,7 +204,7 @@ fn <- write_vc(updated, "factor", root, strict = FALSE)
 print_file("factor.yml", root)
 ```
 
-The next example removes the `"blue"` level and switches the order of the remaining levels. Notice that again the existing index are retained. The order of the labels and indices reflects their new ordering.
+The next example removes the `"blue"` level and switches the order of the remaining levels. Notice that again the existing indices are retained. The order of the labels and indices reflects their new ordering.
 
 ```{r factor_deleted}
 deleted <- data.frame(
@@ -213,7 +213,7 @@ write_vc(deleted, "factor", root, sorting = "color", strict = FALSE)
 print_file("factor.yml", root)
 ```
 
-Changing an factor to an ordered factor or _vice versa_ will also keep existing level indices.
+Changing a factor to an ordered factor or _vice versa_ will also keep existing level indices.
 
 ```{r factor_ordered}
 ordered <- data.frame(
@@ -236,7 +236,7 @@ write_vc(relabeled, "write_vc", root, strict = FALSE)
 print_file("write_vc.yml", root)
 ```
 
-Therefore we created `relabel()`, which changes only the labels in the metadata. It takes three arguments: the name of the data file, the root and the change. `change` accepts two formats, a list or a dataframe. The named of the list must match with the variable name of a factor in the data. Each element of the list must be named vector, the name being the existing label and the value the new label. The dataframe format requires a `factor`, `old` and `new` variable with one row for each change in label. 
+Therefore we created `relabel()`, which changes only the labels in the metadata. It takes three arguments: the name of the data file, the root and the change. `change` accepts two formats, a list or a dataframe. The name of the list must match with the variable name of a factor in the data. Each element of the list must be a named vector, the name being the existing label and the value the new label. The dataframe format requires a `factor`, `old` and `new` variable with one row for each change in label. 
 
 ```{r}
 write_vc(old, "relabel", root, sorting = "color")
@@ -247,4 +247,4 @@ relabel("relabel", root,
 print_file("relabel.yml", root)
 ```
 
-A _caveat_: `relabel()` only makes sense with the data file uses optimized storage. The verbose mode stores the factor labels and not their indices, in which case relabels a label will always yield a large diff. Therefore `relabel()` will only handle the optimized storage. 
+A _caveat_: `relabel()` only makes sense when the data file uses optimized storage. The verbose mode stores the factor labels and not their indices, in which case relabelling a label will always yield a large diff. Therefore `relabel()` will only handle the optimized storage.