Reporting with RMarkdown

Communication is a critical part of project planning. For this, projmgr provides a family of report functions. These functions translate certain R objects like lists or dataframes into HTML code which will render nicely when knitted to HTML in an RMarkdown document.

Plans & To-Do Lists

Recall that plans and to-do lists can be written in YAML. For example:

- title: Data cleaning and validation
  description: >
    We will conduct data quality checks,
    resolve issues with data quality, and
    document this process
  due_on: 2018-12-31T12:59:59Z
  issue:
    - title: Define data quality standards
      body: List out decision rules to check data quality
      assignees: [emilyriederer]
      labels: [a, b, c]
    - title: Assess data quality
      body: Use assertthat to test decision rules on dataset
      labels: [low]
    - title: Resolve data quality issues
      body: Conduct needed research to resolve any issues

- title: Exploratory data analysis
  description: >
    Create basic statistics and views to better
    understand dataset and relationships
  issue:
    - title: Summary statistics
      body: Calculate summary statistics
    - title: Visualizations
      body: Create univariate and bivariate plots

The report_plan() function converts plans into formatted HTML for inclusion in RMarkdown documents for more aesthetic reporting.

plan <- read_plan(plan_path)
report_plan(plan)

Data cleaning and validation ( 0 / 5 )

• ☐ Define data quality standards
• ☐ Assess data quality
• ☐ Resolve data quality issues

Exploratory data analysis ( 0 / 5 )

• ☐ Summary statistics
• ☐ Visualizations

The report_todo() function works similarly.

Issues & Milestones

Similarly, any issue-milestone data pulled back down from GitHub can be reported in a similar format with report_progress().

report_progress(issues)

Data cleaning and validation ( 100 % Complete - 3 / 3 )

• ☑ Resolve data quality issues
• ☑ Assess data quality
• ☑ Define data quality standards

Exploratory data analysis ( 50 % Complete - 1 / 2 )

• ☐ Visualizations
• ☑ Summary statistics

Taskboards

Using HTML and CSS grid, the report_taskboard() function also offers aesethetic and interactive views of your work.

report_taskboard(pkg_issues, in_progress_when = is_assigned_to("emilyriederer"))

Not Started

In Progress

Done

Extend report() support to LaTeX

Add get for events data

Add parse for events data

API mocking for testing

Validate YAML read from read fxs

Add browse and help functions

Write vignette to demo visualization

Add metadata function examples to vignettes

Add JSON support for plan / todo

Users specify what logic to use for identifying “in progress” items by passing a function factory to the in_progress_when parameter. The above example uses the is_labeled_with() option. Other options include:

ls('package:projmgr')[grep("^is_*", ls('package:projmgr'))]
#>  [1] "is_assigned"       "is_assigned_to"    "is_created_before"
#>  [4] "is_due"            "is_due_before"     "is_in_a_milestone"
#>  [7] "is_in_milestone"   "is_labeled"        "is_labeled_with"  
#> [10] "is_part_closed"

See ?taskboard_helpers for more details.

Optional parameters of this function are include_link (whether to link back to the relevant GitHub issue), hover (for slightly enlarging a task on hover), and colors (to provide a character vector of colors to override the defaults.)

As a second example, suppose we instead classify issues as in progress once they have been put in a milestone.

report_taskboard(pkg_issues,
                 in_progress_when = is_in_a_milestone(),
                 include_link = FALSE,
                 hover = TRUE,
                 colors = c('#ff0000', '#00ff00', '#0000ff'))

Not Started

In Progress

Done

Extend report() support to LaTeX

Add get for events data

Add parse for events data

API mocking for testing

Validate YAML read from read fxs

Add browse and help functions

Write vignette to demo visualization

Add JSON support for plan / todo

Add metadata function examples to vignettes

Discussions

Additionally, full issues discussions can be pulled from GitHub and reformatted to HTML for long-term documentation with the report_discussion() function.

issues <- get_issues(experigit, number = 163) %>% parse_issues()
comments <- get_issue_comments(experigit, number = 163) %>% parse_issue_comments()

report_discussion(comments, issues)
#> Warning in if (!is.na(issue)) {: the condition has length > 1 and only the first
#> element will be used

Issue: #163: A very important issue
Created by emilyriederer on 2018-12-30

Issue Description:

This is the beginning of a conversation

Visit on GitHub

---

emilyriederer ( OWNER ) wrote at 2018-12-30 :

I’m just commenting to add more information.

---

emilyriederer ( OWNER ) wrote at 2018-12-30 :

Actually, I disagree. My perspective is this.