verkehrsbetriebezuerich / catmaply

'catmaply' package for 'R'

catmaply

Contents

• Introduction
• Installation
• Examples
• Code of Conduct

Introduction

A heatmap is a graphical representation of data that uses a system of color-coding to represent different values. Heatmaps are used in various forms of analytics, however, this R package specifically focuses on providing an efficient way for creating interactive heatmaps for categorical data or continuous data that can be grouped into categories.

This package is originally being developed for Verkehrsbetriebe Zürich (VBZ), the public transport operator in the Swiss city of Zurich, to illustrate the utilization of different routes and vehicles during different times of the day. Therefore, it groups utilization data (e.g. persons per m^2) into different categories (e.g. low, medium, high utilization) and illustrates it for certain stops over time in a heatmap.

This package can easily be integrated into a shiny dashboard which supports additional interactions with other plots (e.g. boxplot, histogram, forecast) by using plotly events.

This work is based on the plotly.js engine.

Please submit feature requests

This package is still under active development. If you have features you would like to have added, please submit your suggestions (and bug-reports) at: https://github.com/VerkehrsbetriebeZuerich/catmaply/issues/

News

You can see the most recent changes of the package in NEWS.md.

Installation

To install the latest ("cutting-edge") GitHub version run:

# make sure that you have the corrent R Tools installed.
# as you might need to build some packages from source

# if do not have RTools installed, you can install it with:
# install.packages('installr'); install.Rtools() # not tested on windows
# or download it from here:
# https://cran.r-project.org/bin/windows/Rtools/
# in any case, make sure that you select the correct version, 
# otherwise the installation will fail.

# Then you'll need devtools
if (!require('devtools'))
  install.packages('devtools')

# Finally install the package
devtools::install_github('VerkehrsbetriebeZuerich/catmaply')

To install the latest available version on cran, run:

install.packages('catmaply')

And then you may load the package using:

library("catmaply")

Examples

To get an impression what catmaply does take a look at the following examples.

Simple plot with default options

# simple plot
library(catmaply)

# example data within catmaply
data("vbz")
df <- vbz[[3]]

catmaply(
  df,
  x = trip_seq,
  x_order = trip_seq,
  y = stop_name,
  y_order = stop_seq,
  z = occ_category
)

The code shown above leads to the following output

More complex plot

catmaply brings many costumizing options for you to get the plot in the shape you want. Also the layout options from Plotly can be used to style the plot.

# a bit more complex plot,
# using some costumizing options and
# layout options from plotly

library(catmaply)
library(plotly)
library(dplyr)

# example data within catmaply
data("vbz")
df <- vbz[[3]]


catmaply(
  df,
  x = trip_id,
  x_order = trip_seq,
  y = stop_name,
  y_order = stop_seq,
  z = occupancy,
  categorical_color_range = TRUE,
  categorical_col = occ_category,
  hover_template = paste(
    "<b>Time</b>:", departure_time,
    "<br><b>Stop</b>:", stop_name,
    "<br><b>Occupancy</b>:", occupancy,
    "<br><b>Occupancy Category</b>:", occ_cat_name,
    "<br><b>No Of Measurements</b>:", number_of_measurements,
    "<extra></extra>"
  ),
  legend_col = occ_cat_name
) %>%
  layout(
    title = list(text = ""),
    # adjust hight of plot due to number of stops/observations
    height = 500 + 10 * max(df$stop_seq),
    # flip axis and use spikes
    yaxis = list(
      autorange = "reversed",
      showspikes = TRUE,
      spikedash = "solid",
      spikethickness = 0.5,
      spikecolor = "gray"
    ),
    # use spikes
    xaxis = list(
      showspikes = TRUE,
      spikedash = "solid",
      spikethickness = 0.5,
      spikecolor = "gray",
      rangeslider = list(thickness = 0.1)
    ),
    # horizontal and adjusted legend
    legend = list(
      yanchor = "top",
      y = -0.25,
      orientation = "h",
      font = list(size = 9)
    )
  )

The code shown above leads to the following output

Further examples

More step-by-step examples and further descriptions can be found here.

Code of conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

catmaply's Issues

Label formatting

• Possibility to define if labels should be displayed or not in function call
• Possibility to define template for label formatting

Base functionality axis

• Possibility to select x and y axis columns; ordering should be dynamic by any other column.
• Possibility to set size, color and orientation of text in function call
• Possibility to set axis position/side in function call

Field coloring does not depend on category order

At the moment, field coloring is dependent on the category order in the data frame. See this example:

library(catmaply)

df <- vbz[[1]]$data

# ordering smallest to largest Kat
df <- df %>% arrange(-desc(Ausl_Kat))

catmaply(
  df,
  x = fahrt_seq,
  y = halt_seq,
  vals = Ausl_Kat
)

# ordering largest to smallest Kat
# inverses color order
df <- df %>% arrange(desc(Ausl_Kat))

catmaply(
  df,
  x = fahrt_seq,
  y = halt_seq,
  vals = Ausl_Kat
)

Field colors should be in ascending order based on the respective category column.

Field formatting

• Possibility to set columns for fields in function call, ordered by x and y.
• Possibility to set categorical style (background color) with color palette
• Possibility to set annotation
• Empty fields need to be shown and should be white.

fix cran release

Describe the bug
Package cannot be deployed to CRAN:

Error message:

Please see the problems shown on
https://cran.r-project.org/web/checks/check_results_catmaply.html.

In particular, please see the "Found the following HTML validation
problems" NOTEs in the "HTML version of manual" check for the r-devel
debian checks results.

R 4.2.0 switched to use HTML5 for documentation pages. Now validation
using HTML Tidy finds problems in the HTML generated from your Rd files
of the form

element removed from HTML5

element removed from HTML5

attribute "align" not allowed for HTML5

attribute "hspace" not allowed for HTML5

attribute "width" has invalid value "120px"

attribute "width" has invalid value "480px"

attribute "width" has invalid value "50px"

attribute "width" has invalid value "72px"

For the first four, please see
https://html.spec.whatwg.org/#obsolete-but-conforming-features for
info on these: in principle, all can be fixed by using style attributes,
e.g.

style='text-align: right;'

instead of align='right' etc., which will work for both the new and old
ways of converting Rd to HTML.

For the second four, simply drop the px units: the HTML5 standard asks
for a non-negative integer implied to be in CSS pixels.

Can you please fix as necessary?

Note that the problems are found in Rd files auto-generated with
roxygen2: to fix it might suffice to re-generate these using the current
CRAN version of roxygen2.

Fix and resubmit to cran

error behavior of color palette

If number of categories is lower than number of colors in color palette, reduce color palette

behavoir x-axis

x-axis ignores "x_order" when input column for "x" is not the same as for "x_order". Creates some unwanted overlapping. It doesn't matter if "x" is unique or not.

Ordering of x and y axis

Allow custom ordering of x and y axis (decreasing/ascending)

Add examples to Readme.md

Add some examples of the usage of catmaply directly to the "front page" (Readme.md) in this repository. Idea: Get a good first impression of what catmaply does without having to install it.

Legend functionality

• Possibility to show or hide legend in function call
• Show / Hide fields based on click on legend
• Define legend names based on any column in input data.frame

Documentation

• Improve documentation
• add recent data-set

"Padded" heatmap

I apologise if I'm missing something, but after looking around I haven't found a way to implement the xgap and ymap traces in order to add some white space between the "bricks". Please let me know if there is any way to do this or if it could be implemented.

Thanks for your work developing this package.

Wrong categorical color range when "legend_interactive = FALSE"

Describe the bug
When plotting with a categorical color range and no interactive legend ("legend_interactive = FALSE"), the color range is biased, some values appear as if they belong to a different category than they actually are in.

Thanks for considering the issue.
I'll be ready for eventual questions.
Cheers, Simon

To Reproduce
To reproduce you can use the available "vbz" data.
The code to reproduce is given below. Execute it onec as it is and an other time with the option "legend interactive = TRUE":

data("vbz")
df <- vbz[[3]]

catmaply(
df,
x = trip_id,
x_order = trip_seq,
y = stop_name,
y_order = stop_seq,
z = occupancy,
categorical_color_range = TRUE,
categorical_col = occ_category,
legend_interactive = FALSE,
hover_template = paste(
"Time:", departure_time,
"
Stop:", stop_name,
"
Occupancy:", occupancy,
"
Occupancy Category:", occ_cat_name,
"
No Of Measurements:", number_of_measurements,
""
),
legend_col = occ_cat_name
)

Expected behavior
I would expect the colors in the plot to stay the same for each square within the heatmap plot, since neither the values nor their categories change. It's just the legend type which changes. Instead, the colors are shifted such that for some of the squares the category seems to change, which is not true.
With the interactive legend the color category and the variable category seem to match, whereas with the non-interactive legend, they seem to be offset.

Screenshots
Screenshot of a non-interactive example, where a square (courseno.: 17020, station name: Zuerich, Kreuzplatz) with a value of the category "medium high" appears in a color which clearly is within the color palette of the category "high":

The very same example but this time with the interactive legend shows, that the same square now belongs to the correct category "medium high":

Environment:
Append result of sessionInfo().
sessionInfo.txt

Hovertext when empty

Hover generates "%{text} medium high" at empty fields. It would be better if there is no hoverinfo at empty fields.

Allow DateTime Axis

• Allow DateTime or Time on X Axis
• Allow dynamic labels based on zoom on X Axis
• Allow custom axis labels based on zoom level

Add annotation capability

Add capability to add annotations to catmaply

Update Readme

• Add cran badges
• Add download from cran

Adjust naming categorical_colorbar

Parameter categorical_colorbar is not entirely correct, as it can also be used with no legend at all and display categorical color_ranges per category.

Rename it to categorical_color_range

improve discrete_coloring

currently, it is not allows to use custom color ranges per categories with the catmaply_single trace. It should be possible to:

• add a color range per category similar to catmaply_traces
• dynamically increase colorbar based on the number of elements displayed in it

also; when using catmaply single without displaying the legend; warnings should be thrown that

• parameter categorical_colorbar will be ignored
• parameter categorical_col will be ignored