Tidy code, add README, LICENSE

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Luke Zappia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,87 @@
+# PhD commits
+
+Functions for scraping git commits from repositories associated with a PhD (or
+anything else) and plotting them. The result looks something like this.
+
+![Commits GIF](phd-commits.gif)
+
+## How to use
+
+### 1. Get your commits
+
+The `get_commits()` function takes a path and searches each of the
+subdirectories. For each subdirectory that is a git repository it extracts
+the git commits. The other arguments can be used to filter the commits to
+a specific date or users. The output is a `tibble` with columns "SHA", "Name",
+"When" and "Repository".
+
+```r
+commits <- get_commits("/path/to/repos")
+```
+
+If you have repositories in multiple locations you can combine them using
+`dplyr::bind_rows()` and filter on the SHA to remove any duplicates.
+
+```r
+commits1 <- get_commits("/path/to/repos1")
+commits2 <- get_commits("/path/to/repos2")
+
+commits <- commits1 %>%
+    dplyr::bind_rows(commits2) %>%
+    dplyr::distinct(SHA, .keep_all = TRUE)
+```
+
+### 2. Categorise your repositories
+
+Each repository needs a category and a type. Categories can be broad
+projects/thesis chapters and I used Type to specify if the repository was
+mostly code or writing. I did this by printing all the repositories using this
+code:
+
+```r
+cat(paste(sort(unique(commits$Repository)), collapse = "\n"))
+```
+
+Then copying that list into Excel and categorising each repository. There is
+probably a better/more R way to do it but this works. What you need at the end
+is a second repository tibble with the columns "Repository", "Category" and
+"Type".
+
+### 3. Plot your commits
+
+You can now pass these two tibbles to the `plot_commits()` function.
+
+```r
+commits_plot <- plot_commits(commits, repositories)
+```
+
+Change the other arguments to make sure you have the right category
+order/labels, colours etc. The `label` parameter labels the first commit of
+each repository with the (truncated) repository name.
+
+### 4. Animate your commits
+
+The last step is to animate everything using `animate_commits()`. This is
+mostly pretty easy, the tricky part is getting the subtitle right.
+
+```r
+animate_commits(commits_plot)
+```
+
+Save your animation as a git using `gganimate::anim_save()`.
+
+```r
+anim_save("commits.gif")
+```
+
+## Notes
+
+* Hopefully this is useful/interesting for some people.
+* This code is not well tested, use at your own risk.
+* I tried to make the functions as generic as possible but there may be some
+  places where things specific to me are still there.
+* I couldn't get any kind of enter tranistion to work for the points. I think
+  it has something to do with having to give each point it's own group so they
+  don't disappear. Solutions welcome.
+* Thanks to everyone who wrote the packages I used and everyone who has posted
+  tutorials/answered questions on the internet.

get_commits.R

@@ -1,5 +1,7 @@
 get_commits <- function(path, distinct = TRUE, filter = TRUE,
+                        users = c("l.zappia", "lazappi", "Luke Zappia"),
                         from = "2016-02-08") {
+
     dirs <- fs::dir_ls(path, type = "directory")
 
     message("Searching ", length(dirs), " directories...")
@@ -38,7 +40,7 @@ get_commits <- function(path, distinct = TRUE, filter = TRUE,
     if (filter) {
         message("Filtering names...")
         commits <- dplyr::filter(
-            commits, Name %in% c("l.zappia", "lazappi", "Luke Zappia")
+            commits, Name %in% users
         )
         message("Found ", nrow(commits), " commits by me")
     }

plot_commits.R

@@ -1,4 +1,19 @@
-plot_commits <- function(commits, repositories) {
+plot_commits <- function(commits, repositories, label = FALSE,
+                         cat_levels = c("Tools", "Simulation", "ClustTrees",
+                                        "Analysis", "Reports", "Other",
+                                        "SideProject"),
+                         cat_labels = c("Tools", "Simulation",
+                                        "Clustering trees",
+                                        "Analysis", "Reports", "Other",
+                                        "Side projects"),
+                         pal = c("#00ADEF", "#8DC63F", "#EC008C", "#00B7C6",
+                                 "#7A52C7", "#F47920", "grey50"),
+                         # This isn't used in this function but has to go
+                         # here for the animation. Something to do with
+                         # namespaces I think...
+                         start_date = "2016-02-08"
+                         ) {
+
     `%>%` <- magrittr::`%>%`
 
     commits <- dplyr::left_join(commits, repositories, by = "Repository")
@@ -15,70 +30,22 @@ plot_commits <- function(commits, repositories) {
         commits,
         Category = factor(
             Category,
-            levels = rev(c("Tools", "Simulation", "ClustTrees", "Analysis",
-                           "Reports", "Other", "SideProject")),
-            labels = rev(c("Tools", "Simulation", "Clustering trees",
-                           "Analysis", "Reports", "Other", "Side projects")))
+            levels = rev(cat_levels),
+            labels = rev(cat_labels))
         )
 
-    first_commits <- commits %>%
-        dplyr::group_by(Repository) %>%
-        dplyr::arrange(When) %>%
-        dplyr::filter(dplyr::row_number() == 1) %>%
-        dplyr::ungroup() %>%
-        dplyr::mutate(Repository = stringr::str_trunc(Repository, 13))
-
-    first_commits_top <- first_commits %>%
-        dplyr::group_by(Category) %>%
-        dplyr::filter(dplyr::row_number() %% 2 == 1) %>%
-        dplyr::ungroup() %>%
-        dplyr::mutate(vjust = rep(c(3, 5), length.out = n()))
-
-    first_commits_bottom <- first_commits %>%
-        dplyr::group_by(Category) %>%
-        dplyr::filter(dplyr::row_number() %% 2 == 0) %>%
-        dplyr::ungroup() %>%
-        dplyr::mutate(vjust = rep(c(3, 5), length.out = n()))
-
-    pal <- c(
-        "#00ADEF", # Blue
-        "#8DC63F", # Green
-        "#EC008C", # Pink
-        "#00B7C6", # Teal
-        "#7A52C7", # Purple
-        "#F47920", # Orange
-        "grey50"   # Grey
-    )
-
-    ggplot2::ggplot(
+    commits_plot <- ggplot2::ggplot(
         commits,
         ggplot2::aes(x = Category, y = When, colour = Category, shape = Type)
     ) +
         ggplot2::geom_jitter(
-            aes(group = seq_along(SHA)),
+            # Give each point it's own group for animation
+            ggplot2::aes(group = seq_along(SHA)),
             width = 0.2, height = 0, alpha = 0.8, size = 2
         ) +
-        #ggplot2::geom_text(data = first_commits, aes(label = Repository),
-        #                   vjust = -2) +
-        # ggrepel::geom_text_repel(
-        #     data = first_commits_top,
-        #     aes(label = Repository, vjust = -vjust,
-        #         group = seq_len(nrow(first_commits_top))),
-        #     size = 3,
-        #     direction = "x",
-        #     show.legend = FALSE
-        # ) +
-        # ggrepel::geom_text_repel(
-        #     data = first_commits_bottom,
-        #     aes(label = Repository, vjust = vjust,
-        #         group = seq_len(nrow(first_commits_bottom))),
-        #     size = 3,
-        #     direction = "x",
-        #     show.legend = FALSE
-        # ) +
         ggplot2::scale_x_discrete(drop = FALSE) +
         ggplot2::scale_shape_manual(values = c(16, 1)) +
-        ggplot2::scale_colour_manual(values = rev(pal)) +
+        ggplot2::scale_colour_manual(values = rev(pal), guide = FALSE) +
         ggplot2::coord_flip() +
         ggplot2::labs(
             title = "A PhD in git commits",
@@ -91,38 +58,85 @@ plot_commits <- function(commits, repositories) {
             plot.title = ggplot2::element_text(size = 20),
             plot.subtitle = ggplot2::element_text(size = 16),
             axis.title = ggplot2::element_blank(),
+            axis.text = ggplot2::element_text(size = 12),
             legend.position = "bottom"
         )
-}
 
-get_date <- function(frame_along, commits) {
-    the_date <- dplyr::if_else(frame_along > min(commits$When),
-                               frame_along, min(commits$When))
-    the_date <- dplyr::if_else(the_date < max(commits$When), the_date,
-                               max(commits$When))
-    return(the_date)
+    if (label) {
+        # Get the first commit for each repository
+        first_commits <- commits %>%
+            dplyr::group_by(Repository) %>%
+            dplyr::arrange(When) %>%
+            dplyr::filter(dplyr::row_number() == 1) %>%
+            dplyr::ungroup() %>%
+            dplyr::mutate(Repository = stringr::str_trunc(Repository, 13))
+
+        # Put half above the commits...
+        first_commits_top <- first_commits %>%
+            dplyr::group_by(Category) %>%
+            dplyr::filter(dplyr::row_number() %% 2 == 1) %>%
+            dplyr::ungroup() %>%
+            # Stagger the adjustment to avoid overlaps
+            dplyr::mutate(vjust = rep(c(3, 5), length.out = dplyr::n()))
+
+        # ... and half below
+        first_commits_bottom <- first_commits %>%
+            dplyr::group_by(Category) %>%
+            dplyr::filter(dplyr::row_number() %% 2 == 0) %>%
+            dplyr::ungroup() %>%
+            dplyr::mutate(vjust = rep(c(3, 5), length.out = dplyr::n()))
+
+        commits_plot <- commits_plot +
+            # ggplot2::geom_text(data = first_commits, aes(label = Repository),
+            #                   vjust = -2) +
+            ggrepel::geom_text_repel(
+                data = first_commits_top,
+                ggplot2::aes(label = Repository, vjust = -vjust,
+                             group = seq_len(nrow(first_commits_top))),
+                size = 3,
+                direction = "x",
+                show.legend = FALSE
+            ) +
+            ggrepel::geom_text_repel(
+                data = first_commits_bottom,
+                ggplot2::aes(label = Repository, vjust = vjust,
+                             group = seq_len(nrow(first_commits_bottom))),
+                size = 3,
+                direction = "x",
+                show.legend = FALSE
+            )
+    }
+
+    return(commits_plot)
 }
 
-get_days <- function(the_date) {
+# Functions used in the animated subtitle
+get_days <- function(the_date, start_date) {
     lubridate::as.period(
-        lubridate::as_datetime(the_date) - lubridate::as_datetime("2016-02-08")
+        lubridate::as_datetime(the_date) -
+            lubridate::as_datetime(start_date)
     )@day
 }
 
+get_nrepos <- function(commits, frame_along) {
+    length(unique(commits$Repository[commits$When <= frame_along]))
+}
+
 animate_commits <- function(commits_plot) {
 
+    # Glue together the subtitle. `frame_along` is a variable created by
+    # `transition_reveal()`.
     subtitle <- paste(
-        "{sum(first_commits$When <= frame_along)} repositories with",
-        "{sum(commits$When <= frame_along)} commits in",
-        "{get_days(get_date(frame_along, commits))} days by",
-        "{as.Date(get_date(frame_along, commits))}"
+       "{get_nrepos(commits, frame_along)} repositories with",
+       "{sum(commits$When <= frame_along)} commits in",
+       "{get_days(frame_along, start_date)} days by",
+       "{as.Date(frame_along)}"
     )
 
-    commits_plot +
-        gganimate::transition_reveal(
-            When,
-            range = c(lubridate::as_datetime("2016-01-01"),
-                      lubridate::as_datetime("2020-01-31"))
-        ) +
-        labs(subtitle = subtitle)
+    commits_ani <- commits_plot +
+        gganimate::transition_reveal(When) +
+        ggplot2::labs(subtitle = subtitle)
+
+    gganimate::animate(commits_ani, height = 600, width = 800,
+                       start_pause = 10, end_pause = 20)
 }