Plan, a package for project planning

Description

This package provides tools for project planning, e.g. burndown charts, gantt diagrams, etc.; see burndown and gantt for entries to the documentation.

Author(s)

Dan Kelley

See Also

Useful links:

• https://github.com/dankelley/plan

• https://dankelley.github.io/plan/

Replace Parts of a plan Object

Description

Replace something within a plan object, avoiding using the "slot" notation.

Usage

## S4 replacement method for signature 'plan'
x[[i, j, ...]] <- value

Arguments

Extract Something From a plan Object

Description

Extract something from a plan object, avoiding using the "slot" notation.

Usage

## S4 method for signature 'plan'
x[[i, j, ...]]

Arguments

Create a burndown object

Description

Create a burndown object from the given data.

Usage

as.burndown(start, deadline, tasks, progress, progressInPercent = FALSE)

Arguments

Details

Creates a burndown object from the given data; progress may be given in percentage or absolute values.

Value

A burndown object.

Author(s)

Frank Schmitt

See Also

Other things related to burndown data: burndown-class, burndown, plot,burndown-method, read.burndown(), summary,burndown-method

Examples

library(plan)
# same data as in tests/burndown.dat
start <- as.POSIXct(strptime("2006-04-08 12:00:00", "%Y-%m-%d %H:%M:%S"))
deadline <- as.POSIXct(strptime("2006-04-11 20:00:00", "%Y-%m-%d %H:%M:%S"))
tasks <- data.frame(key = c(1, 2, 3, 4, 5, 6),
    description = c("code read.burndown()", "code summary.burndown()", 
        "code plot.burndown()", "create R package", 
        "write documentation", "set up website"),
    effort = c(4, 1, 5, 2, 2, 1),
    stringsAsFactors = FALSE)
progress <- data.frame(key = c(1, 2, 1, 2, 4, 5, 4, 1, 3, 3, 3, 2, 2, 1, 5, 5, 5, 1, 3, 6),
    progress = c(5, 5, 10, 50, 5, 5, 100, 50, 5, 30, 80, 60, 
        100, 70, 30, 90, 100, 100, 100, 100),
    time = structure(c(1144494000, 1144495800, 1144497600, 1144501200, 
            1144517400, 1144519200, 1144523760, 1144566600, 
            1144568460, 1144570680, 1144573200, 1144576800, 
            1144577400, 1144578600, 1144583400, 1144585200,
            1144585800, 1144586100, 1144586400, 1144591200), 
        class = "POSIXct"),
    stringsAsFactors = FALSE
)
b <- as.burndown(start, deadline, tasks, progress, progressInPercent = TRUE)
summary(b)
plot(b)

Create a gantt object.

Description

This creates a gantt object.

Usage

as.gantt(key, description, start, end, done, neededBy)

Arguments

Value

A gantt object; for details, see read.gantt().

Author(s)

Dan Kelley

See Also

Other things related to gantt data: gantt-class, ganttAddTask(), gantt, plot,gantt-method, read.gantt(), summary,gantt-method

Examples

library(plan)
arrive <- as.POSIXct("2012-09-05")
month <- 28 * 86400
year <- 12 * month
leave <- arrive + 4 * year
startT1 <- arrive
endT1 <- startT1 + 4 * month
startT2 <- endT1 + 1
endT2 <- startT2 + 4 * month
startQE <- arrive + 9 * month
endQE <- arrive + 12 * month
QEabsoluteEnd <- arrive + 15 * month
startProposal <- arrive + 15 * month # for example
endProposal <- arrive + 20 * month
startThesisWork <- arrive + 2 * month # assumes no thesis work until 2 months in
endThesisWork <- leave - 4 * month
startWriting <- leave - 36 * month
endWriting <- leave
g <- as.gantt(key=1:8, c("Academic",
              "Term 1 classes",
              "Term 2 classes",
              "Qualifying Examination",
              "Research",
              "Proposal Defence",
              "Thesis Work",
              "Paper/Thesis Writing"),
              c(startT1, startT1, startT2, startQE, startProposal, startProposal,
                startThesisWork, startWriting),
              c(startT1, endT1, endT2, endQE, startProposal, endProposal,
                endThesisWork, endWriting),
              done=rep(0, 7))
plot(g, xlim=c(arrive, leave),
     ylabel=list(font=c(2,rep(1,3),2), justification=c(0,rep(1,3),0)))

Sample burndown dataset

Description

This is sample burndown dataset provided for testing.

Author(s)

Dan Kelley

See Also

Other things related to burndown data: as.burndown(), burndown-class, plot,burndown-method, read.burndown(), summary,burndown-method

Other data sets provided with plan: gantt

Class to store burndown objects

Description

Class to store burndown objects

See Also

Other things related to burndown data: as.burndown(), burndown, plot,burndown-method, read.burndown(), summary,burndown-method

check tokens

Description

check tokens

Usage

check.tokens(tokens, expected)

Arguments

Sample gantt dataset

Description

This is sample gantt dataset provided for testing.

Author(s)

Dan Kelley

See Also

Other things related to gantt data: as.gantt(), gantt-class, ganttAddTask(), plot,gantt-method, read.gantt(), summary,gantt-method

Other data sets provided with plan: burndown

Class to store gantt objects

Description

These objects may be created with as.gantt() or read.gantt().

See Also

Other things related to gantt data: as.gantt(), ganttAddTask(), gantt, plot,gantt-method, read.gantt(), summary,gantt-method

Add a task to a gantt object

Description

This can be a simpler method than using as.gantt(), because tasks can be added one at a time.

Usage

ganttAddTask(
  g,
  description = "",
  start = NA,
  end = NA,
  done = 0,
  neededBy = NA,
  key
)

Arguments

See Also

Other things related to gantt data: as.gantt(), gantt-class, gantt, plot,gantt-method, read.gantt(), summary,gantt-method

Examples

library("plan")
g <- new("gantt")
g <- ganttAddTask(g, "Courses") # no times, so a heading
g <- ganttAddTask(g, "Physical Oceanography", "2016-09-03", "2016-12-05")
g <- ganttAddTask(g, "Chemistry Oceanography", "2016-09-03", "2016-12-05")
g <- ganttAddTask(g, "Fluid Dynamics", "2016-09-03", "2016-12-05")
g <- ganttAddTask(g, "Biological Oceanography", "2017-01-03", "2017-04-05")
g <- ganttAddTask(g, "Geological Oceanography", "2017-01-03", "2017-04-05")
g <- ganttAddTask(g, "Time-series Analysis", "2017-01-03", "2017-04-05")
g <- ganttAddTask(g, "Research") # no times, so a heading
g <- ganttAddTask(g, "Literature review", "2016-09-03", "2017-04-05")
g <- ganttAddTask(g, "Develop analysis skills", "2016-09-03", "2017-08-01")
g <- ganttAddTask(g, "Thesis work", "2017-01-01", "2018-04-01")
g <- ganttAddTask(g, "Defend thesis proposal", "2017-05-01", "2017-06-01")
g <- ganttAddTask(g, "Write papers & thesis", "2017-05-01", "2018-04-01")
g <- ganttAddTask(g, "Defend thesis", "2018-05-01", "2018-05-15")
# Set 'font' for bold-faced headings
font <- ifelse(is.na(g[["start"]]), 2, 1)
plot(g, ylabel=list(font=font))

Base Class for plan Objects

Description

Base Class for plan Objects

Slots

data

A list containing variable contents.

Draw a burndown chart

Description

Plot a burndown chart.

Usage

## S4 method for signature 'burndown'
plot(
  x,
  col = NULL,
  draw.plan = TRUE,
  draw.regression = TRUE,
  draw.lastupdate = FALSE,
  t.stop = "",
  y.name = "Remaining Effort",
  debug = FALSE,
  ...
)

Arguments

Author(s)

Dan Kelley

References

https://en.wikipedia.org/wiki/Burndown_chart

See Also

Other things related to burndown data: as.burndown(), burndown-class, burndown, read.burndown(), summary,burndown-method

Examples

library(plan)
data(burndown)
summary(burndown)
plot(burndown)

Draw a Gantt diagram

Description

Plot a gantt chart that shows the time allocated to a set of tasks, optionally also with an indication of discrete events that occur as instants in time.

Usage

## S4 method for signature 'gantt'
plot(
  x,
  xlim,
  time.format = NULL,
  time.labels.by,
  time.lines.by,
  event.time = NULL,
  event.label = NULL,
  event.side = 3,
  col.connector = "black",
  col.done = gray(0.3),
  col.notdone = gray(0.9),
  col.eventLine = gray(0.1),
  col.event = par("fg"),
  cex.event = par("cex"),
  font.event = par("font"),
  lty.eventLine = par("lty"),
  lwd.eventLine = par("lwd"),
  bg = par("bg"),
  grid.col = "lightgray",
  grid.lty = "dotted",
  ylabels = list(col = 1, cex = 1, font = 1, justification = 1),
  arrows = NULL,
  main = "",
  line.main = NA,
  cex.main = par("cex"),
  mgp = c(2, 0.7, 0),
  maiAdd = rep(0, 4),
  axes = TRUE,
  debug = FALSE,
  ...
)

Arguments

Details

Time is indicated along the x axis, and tasks are stacked along the y axis, akin to progress bars. Colour-coding can be used to indicate the degree of completion of each task. These codes can be set individually for individual tasks. Progress bars can have arrows (on either end), suggesting tasks with flexible start/end dates or overdue tasks. Vertical lines may be drawn for discreet events. See “Examples” for a few of the possibilities.

Author(s)

Dan Kelley

References

Gantt diagrams are described on wikipedia ⁠https://en.wikipedia.org/wiki/Gantt_Chart⁠.

See Also

Other things related to gantt data: as.gantt(), gantt-class, ganttAddTask(), gantt, read.gantt(), summary,gantt-method

Examples

library(plan)
data(gantt)
summary(gantt)

# 1. Simple plot
plot(gantt)

# 2. Plot with two events
event.label <- c("Proposal", "AGU")
event.time <- c("2008-01-28", "2008-12-10")
plot(gantt, event.label=event.label,event.time=event.time)

# 3. Control x axis (months, say)
plot(gantt,labels=paste("M",1:6,sep=""))

# 4. Control task colours
plot(gantt,
     col.done=c("black", "red", rep("black", 10)),
     col.notdone=c("lightgray", "pink", rep("lightgray", 10)))

# 5. Control event colours (garish, to illustrate)
plot(gantt, event.time=event.time, event.label=event.label,
     lwd.eventLine=1:2, lty.eventLine=1:2,
     col.eventLine=c("pink", "lightblue"),
     col.event=c("red", "blue"), font.event=1:2, cex.event=1:2)

# 6. Top task is in bold font and red colour
plot(gantt,ylabels=list(col="red",font=2))

# 7. Demonstrate zero-time item (which becomes a heading)
gantt[["description"]][1] <- "Preliminaries"
gantt[["end"]][1] <- gantt[["start"]][1]
plot(gantt, ylabel=list(font=2, justification=0))

# 8. Arrows at task ends
plot(gantt, arrows=c("right","left","left","right"))

Scan burndown data file

Description

Read a data file containing burndown information.

Usage

read.burndown(file, debug = FALSE)

Arguments

Details

Reads a burndown dataset.

A strict format is required, in which the following items must be present, in the stated order, and with nothing else in the file. An example is given after the description.

• Line 1: contains two comma-separated items: the string Start, and a time expressed in ISO 8601 format (YYYY-MM-DD or ⁠YYY-MM-DD hh:mm:ss⁠). This line indicates the start of the project.

• Line 2: as Line 1, but the string is to be Start, and the line indicates the deadline for the project.

• Line 3: a header line for a "tasks" list, comprising the following three words separated by commas: Key, Description, and Effort.

• Lines 4 to N: data lines, each containing three items: a numeric index "Key" for the task, a short "Description" of the task, and the estimated "Effort" for this task, expressed as a number. The keys must be distinct, and they must match the keys in the progress table (see below). The description should be short enough to give a reasonable-size legend as created by plot,burndown-method(). The effort may be expressed in any convenient unit, e.g. the number of hours or days for the task, or as a percentage of the overall task.

• Line N+1: a header line for the "Progress" list, comprising the following four words separated by commas: Key, Done, and Time.

• Line N+2 to end: data lines holding Progress items. Each "Key" must match a key in the task list. The "Done" column holds the percentage of the task that has been completed. The "Time" is in ISO 8601 format, as described above.

Value

A burndown object.

Sample data file

Start, 2006-04-08 12:00:00
Deadline, 2006-04-11 20:00:00
Key, Description,            Effort
  1, Code read.burndown(),    4
  2, Code summary.burndown(), 1
  3, Code plot.burndown(),    5
  4, Create R package,        2
  5, Write documentation,     2
  6, Set up website,          1
Key, Done, Time
  1,    5, 2006-04-08 13:00:00
  2,    5, 2006-04-08 13:30:00
  1,   10, 2006-04-08 14:00:00
  2,   50, 2006-04-08 15:00:00
  4,    5, 2006-04-08 19:30:00
  5,    5, 2006-04-08 20:00:00
  4,  100, 2006-04-08 21:16:00
  1,   50, 2006-04-09 09:10:00
  3,    5, 2006-04-09 09:41:00
  3,   30, 2006-04-09 10:18:00
  3,   80, 2006-04-09 11:00:00
  2,   60, 2006-04-09 12:00:00
  2,  100, 2006-04-09 12:10:00
  1,   70, 2006-04-09 12:30:00
  5,   30, 2006-04-09 13:50:00
  5,   90, 2006-04-09 14:20:00
  5,  100, 2006-04-09 14:30:00
  1,  100, 2006-04-09 14:35:00
  3,  100, 2006-04-09 14:40:00
  6,  100, 2006-04-09 16:00:00

Author(s)

Dan Kelley

See Also

Other things related to burndown data: as.burndown(), burndown-class, burndown, plot,burndown-method, summary,burndown-method

Examples

library(plan)
filename <- system.file("extdata", "burndown.dat", package="plan")
b <- read.burndown(filename)
summary(b)
plot(b)

Read a gantt data file

Description

Read a data file containing gantt information. The data format is strict, and deviations from it may lead to error messages that are difficult to understand; see “Details”.

Usage

read.gantt(file, debug = FALSE)

Arguments

Details

The first line is a header, and must contain the words Key, Description, Start, End, Done, and NeededBy, written exactly in this way, with commas separating the words. (Blanks are ignored in this line.)

Additional lines indicate the details of each of several sub-projects, in comma-separated items, as follows:

• A key for the task. These must be distinct, and are typically just the numbers 1, 2, 3, etc.

• A description of the task. (This may not contain commas!)

• The start time for the task, in ISO 8601 format (YYYY-MM-DD or ⁠YYYY-MM-DD hh:mm:ss⁠).

• The end time for the task, in the same format as the starting time. If an end time equals the corresponding start time, no rectangle will be drawn for the activity, and this gives a way to make headings (see example 7 for plot,gantt-method()).

• A number indicating the percentage of this task that has been completed to date.

• A space-separated optional list of numbers that indicate the keys of other tasks that depend on this one. This list is ignored in the present version of read.gantt().

Value

A gantt object, which is a data frame containing description (a character description of the task), "start" (the task's start time), "end" (the task's end time), "progress" (a number giving the percent progress on this item, or NA if none given), and needed.by (a number giving the indices of other tasks that rely on this task, or NA if none given).

Sample data file

Key, Description,                 Start,        End, Done, NeededBy
  1, Assemble equipment,     2008-01-01, 2008-03-28, 90
  2, Test methods,           2008-02-28, 2008-03-28, 30
  3, Field sampling,         2008-04-01, 2008-08-14, 0
  4, Analyse field data,     2008-06-30, 2008-11-14, 0
  5, Write methods chapter,  2008-08-14, 2008-11-14, 0
  6, Write results chapter,  2008-10-14, 2009-01-15, 0
  7, Write other chapters,   2008-12-10, 2009-02-28, 0
  8, Committee reads thesis, 2009-02-28, 2009-03-14, 0
  9, Revise thesis,          2009-03-15, 2009-03-30, 0
 10, Thesis on display,      2009-04-01, 2009-04-15, 0
 11, Defend thesis,          2009-04-16, 2009-04-17, 0
 12, Finalize thesis,        2009-04-18, 2009-05-07, 0

Author(s)

Dan Kelley

See Also

Other things related to gantt data: as.gantt(), gantt-class, ganttAddTask(), gantt, plot,gantt-method, summary,gantt-method

Examples

library(plan)
filename <- system.file("extdata", "gantt.dat", package="plan")
g <- read.gantt(filename)
summary(g)
plot(g)

Summarize a burndown object

Description

Print a summary of a burndown dataset.

Usage

## S4 method for signature 'burndown'
summary(object, ...)

Arguments

Author(s)

Dan Kelley

See Also

Other things related to burndown data: as.burndown(), burndown-class, burndown, plot,burndown-method, read.burndown()

Examples

library(plan)
data(burndown)
summary(burndown)

Summarize a gantt object

Description

Summarizes a gantt object.

Usage

## S4 method for signature 'gantt'
summary(object, ...)

Arguments

Details

Prints a summary of a gantt dataset.

Author(s)

Dan Kelley

References

https://en.wikipedia.org/wiki/Burndown_chart

See Also

Other things related to gantt data: as.gantt(), gantt-class, ganttAddTask(), gantt, plot,gantt-method, read.gantt()

Examples

library(plan)
data(gantt)
summary(gantt)