cmap-repos / cmapplot

Set of templates and themes to apply CMAP graphics standards to R products.

cmapplot

This R package provides themes, color scales, and other custom functions for ggplot2, based on Chicago Metropolitan Agency for Planning (CMAP) design guidelines.

CMAP staff who are interested in using this package, or merely staying in the loop, are encouraged to join the R team in Microsoft Teams and follow the “cmapplot” channel.

The basics

The cmapplot package contains a few key components:

1. Apply a CMAP theme to ggplots with theme_cmap()
2. Easily provide common CMAP plot customizations, such as with custom geoms geom_recessions() and geom_text_lastonly()
3. Apply CMAP colors using a variety of custom functions (e.g. cmap_fill_discrete())
4. Place the themed plot within a CMAP layout, and export the plot from R if desired with finalize_plot()

Installation

Run the following to install or update cmapplot:

## Install current version from GitHub
devtools::install_github("CMAP-REPOS/cmapplot", build_vignettes=TRUE)

## Then load the package as you would any other
library(cmapplot)

For more detailed information about installing the package, particularly on a CMAP-issued computer, see this article.

To install on macOS, users must install XQuartz before cmapplot can be loaded. (This can be easily accomplished via the Homebrew package manager with the command brew install --cask xquartz.)

A note about fonts: The cmapplot package works best when installed on a computer with the Whitney family of fonts installed (specifically the Book, Medium, and Semibold variants). If installed on a computer without Whitney, the package will still work, but the fonts will default to your computer’s default sans-serif font (probably Arial).

CMAP theme and colors

The function theme_cmap() returns a complete ggplot2 theme that can be added to a ggplot code block (similar to ggplot2::theme_minimal() or ggplot2::theme_bw()). Additionally, theme_cmap() accepts a variety of arguments to additionally customize the theme output. CMAP color functions apply colors from the CMAP color palette to the plot.

ggplot(data = pop_and_laborforce_by_age, 
       aes(x = value,
           y = interaction(year, variable, sep = " "),
           fill = age)) +
  geom_col(position = position_stack(reverse = TRUE)) +
  scale_x_continuous(labels = scales::percent) +
  theme_cmap(xlab = "Percent",
             gridlines = "v",
             vline = 0) +
  cmap_fill_discrete(palette = "environment")

Finalizing the plot

The function finalize_plot() places a ggplot within a frame defined by CMAP design standards. It provides a variety of customization options via arguments, and allows for in-R viewing and/or exporting in various formats.

finalize_plot(title = "Regional population and labor force participation",
              caption = "Data from the American Community Survey",
              width = 7, height = 4.25)

Additional reading

While this package is designed to make the application of CMAP design standards to plots relatively easy, developing a professional, finished plot in R will require a decent familiarity with the grammar of ggplot2. Excellent resources in this category already exist:

• The R graphics cookbook provides accessible examples of how to make almost any type of plot, as well as how to modify things like limits, scales, coordinate systems, and facets.
• The ggplot2 book delves deeper into why and how ggplot2 works the way it does, also with distinct chapters on topics like scales, coordinate systems, facets, etc.
• The ggplot2 website.
• The R for Data Science (R4DS) book, especially the Graphics for Communication chapter.

cmapplot's Issues

Improving default panel spacing

Minor change, but I think we should change the default spacing for faceted graphs (currently unit(consts$half_line, "pt")) to some larger value, as it can be quite tight in the current defaults, particularly when the whole background is the same color (white) and there is only a small break, which can lead to overlapping axis values.

I propose that we do this after #72 is merged.

improved x axis control in TS

In time series, x labels should be integers. Also, in some situations we have published graphs where the first year is full ("2001") and those that follow are partial ('02, '03, '04, etc). We could make this an easy add (I've already found a source for the first half).

How to test theme changes

I made some changes in a branch to the theme. Not sure how to test them.

I changed the font and title placement.

I made the left margin big - per CMAP standard. However I think the margin should really be x% of chart size rather than points or cm. Wecome to thoughts.

conflicts and masks

I typically load the tidyverse library before loading cmapplot, which 'looks' great. However, I recently loaded cmapplot before tidyverse, and was surprised by the extensive list of conflicts:

Why would this be? It doesn't seem to cause any issues but I am curious.

pkgdown site graphics are Arial-only

For our convenience, I set up a "GitHub Action" that rebuilds the pkgdown site every time a commit is pushed to master (including PR merges). This action was developed by the r-lib team (who developed pkgdown, devtools, usethis, roxygen2, etc.), and was set up to run the site-building functions in a virtual macOS environment operated by GitHub. (From what I can tell, a new environment is created from scratch each time the action is run, and deleted upon completion.)

The obvious issue with this, for our purposes, is that the graphics generated for our website use the non-Windows font settings (i.e. Arial-only). I think it would be possible to reconfigure the action to use a Windows environment instead (which the R-CMD-check action already does), if we want the graphics to use Calibri instead of Arial.

If we want the graphics to use Whitney (once we have access to it), I think the only option will be to disable the pkgdown action and rebuild the site manually from our own PCs using pkgdown::deploy_to_branch each time we update master. This seems like a pain in the ass, and is likely to be forgotten for minor commits. Is the trade-off worth it? What are others' thoughts on this?

I can only assign Noel to tasks.

Need some examples of good visualizations that we can try to reproduce.

geom_text_lastonly() enhancements?

Questions about label_last_point mostly pertain to implicitly automating behavior that the user is likely to need pretty much every time this function is added. Of course, this means more work now, and it may be that some of these things are not worth the effort. But here's what comes to mind:

• 1. Could it be programmed in such a way that defaults to taking the Y axis value as the label, rather than requiring the user to set the label attribute in top-line aes? Considering that the following two code blocks yield the same output, can geom_text_lastonly() be set up to inherit the master aes y value as it's label value?

• 2. Similar question re formatting: could the formatting applied to the y axis apply to the label by default?

• 3. in my test plot, which involves a legend, the legend gets modified by the addition of the label. See the image below.

• 4. I forget where we left this off in our discussion last week - considering so much of the functionality is the same, is it worth incorporating adding a dot on the last point into the same function?

• 5. is it within reason to automate the expand_scale() so it occurs within this function?

• 6. Add optional point_aes and text_aes parameters to allow separate control of label/point geom parameters.

Originally posted by @tallishmatt in #23 (comment)

What are our short term goals?

pkgdown site fonts broken

It appears all fonts in plots on the pkgdown site are currently rendering in Arial. Noel, would you be willing to look into why this is the case, and hopefully implement a solution within #115?

Allowing additional arguments in cmap scales

I've come across some plots where it would be helpful to have control over the formatting of the labels and text in the cmap_fill_continuous (and other cmap scales). The vanilla versions of these functions allow such modifications (see here) but I believe our current configuration does not.

Incorporate sample ggplot code into README.Rmd; eliminate sample_graphics.R

@nmpeterson per your request to document the sample datasets I added, I attempted to follow the instructions you sent here, which led me to chapter 8 of the same book and to the basics of Roxygen. However, I am lost and could use your help.

I am working in the 'adtl-sample-data' branch. I have code in the file data.R that should generate a man file, but when I attempt to build the man files by running devtools::document() from the console, I get an error that has to do with sample_graphics.R:
Error in theme_cmap() (from sample_graphics.R#8) : could not find function "theme_cmap"

Would appreciate your troubleshooting help so that we can figure out how to use roxygen for all documentation, as that seems to be a common method/best practice for documentation.

Thank you!

What should this GitHubs project's structure look like?

warning when specifying aes in geom_text_lastonly

In this ggplot, the text for geom_text_lastonly is selected automatically/by default in some way that I am not familiar with:

ggplot(data = df, 
       mapping = aes(x = year, y = ridership, color = system)) +
  geom_recessions(ymin = 0) +
  geom_line(size = 1) +
  theme_cmap(ylab = "Annual Ridership (Millions)") + 
  geom_text_lastonly(add_points = TRUE,
                     nudge_x = 0.5) +
  coord_cartesian(clip = "off")

However, if the user wants to specify/customize the text, I believe label must be specified in aes(), such as this:

ggplot(data = df, 
       mapping = aes(x = year, y = ridership, color = system, label = round(ridership, digits = 0))) +
  geom_recessions(ymin = 0) +
  geom_line(size = 1) +
  theme_cmap(ylab = "Annual Ridership (Millions)") + 
  geom_text_lastonly(add_points = TRUE,
                     nudge_x = 0.5) +
  coord_cartesian(clip = "off")

This aes should be able to be specified in either the top-line ggplot (above) or in the geom (below). Interestingly, for me, the following works but throws an error message "Ignoring unknown aesthetics: label".

ggplot(data = df, 
            mapping = aes(x = year, y = ridership, color = system)) +
  geom_recessions(ymin = 0) +
  geom_line(size = 1) +
  theme_cmap(ylab = "Annual Ridership (Millions)") + 
  geom_text_lastonly(mapping = aes(label = round(ridership, digits = 0)), 
                     add_points = TRUE,
                     nudge_x = 0.5) +
  coord_cartesian(clip = "off")

Why does the warning get triggered?

pkgdown news page -- tie to github releases?

I think it would be nice to include a news page on the pkgdown site that automatically captures updates via the github releases tool. In my mind, every few PR merges should get a release update, and it would make sense to capture that in a changelog on the website.

This does not seem hard to do: https://pkgdown.r-lib.org/reference/build_news.html#yaml-config

Allow capitalized race designations for cmap_[fill/color]_race

Right now, the cmap_fill_race and cmap_color_race will only work if your race/ethnicity designations are in lower case. I propose that we also enable it to work in the case when they are the same words but in different cases, to make it easier to generate production-ready graphics. I can look into this, I don't imagine it will be terribly complicated.

Panel spacing doesn't seem to work when using theme_cmap()

This is a weird bug, but I've noticed that when I try to add spacing between panels, it doesn't work. What's weirder is that it also adds the numeric value of the spacing you add below the plot.

For example, this yields the following chart:

chart2 <- project_type_spending_ratio %>%
  filter(DisplayGroup == "Neither" | DisplayGroup == "EDA and/or DA") %>%
  filter(!(PROJECT.TYPE %in% null_types)) %>%
  filter(ratio_type %in% c("area_ratio","pop_ratio")) %>%
  mutate(ratio_type = case_when(
    ratio_type == "area_ratio" ~ "2. Per acre",
    ratio_type == "pop_ratio" ~ "1. Per capita"
  )) %>%
  ggplot(aes(x = value, y = reorder(PROJECT.TYPE,desc(PROJECT.TYPE)))) +
  geom_bar(aes(fill = DisplayGroup), stat = "identity", position = position_dodge(width = .55), width = .5) +
  facet_grid(~ratio_type,scales = "free") +
  theme_cmap(gridlines = "hv",theme(panel.spacing.x = unit(5,"lines"))) +
  scale_x_continuous(labels = scales::label_dollar()) +
  cmap_fill_discrete(palette = "governance")

I can try to look into this, but does anyone have any initial ideas? @matthewstern @nmpeterson ? Maybe this will get solved by having a complete theme? (We can hope)

automatically highlight final data point on a time series chart with dot and data label

see e.g. Noel's ACS indicator R script and this graph.

left alignment of legends

Moving this to a new issue:

• New item to explore - left aligning legends, potentially with padding as an option.

Originally posted by @dlcomeaux in #8 (comment)

Improvements based on comms review

Feel free to add/change this list based on your notes:

Fonts @nmpeterson

• Axis labels, bot not legend, should use Book
• in-plot labels should use semibold
• title leading should default to 1, not 0.93

Finalize @dlcomeaux

• caption default placement should be bottom
• svg outputs appear to be corrupt upon opening in illustrator
• margin_legend_i should be a bit bigger
• Maybe, additional testing/exploration about the idealized web output (670 px, font sizing, etc). This may warrant some additional discussion with Ben/Joey/Dawn, but I would also recommend against going too deep here until we actually launch and people start using this. Through actual use we'll gain a better sense of what comms needs/wants

theme_cmap (@sarahcmap would you be willing to work on this?)

• Add the ability to add optional axis lines that are the same thickness as grid lines (0.3 bigpts). This would utilize I think axis.line.x and axis.line.y in optional constructions that look very similar to how gridlines are currently specified.

highlight last @nmpeterson

• apply label defaults (text in semibold)
• confirm that we've identified the best possible workaround for the buffer on the right side of the graph and confirm that we have clearly articulated that workaround in the documentation

recessions @matthewstern

• confirm color, alpha, and draw order settings/capabilities

colors @gritzenthaler

• stand by on direction from Ben/Dawn

Font specification won't work on Mac/Linux

Update font specification to check current platform and do something different if non-Windows.

Distance between axis and axis labels

As I was re-making the Census graphic, I noticed that our current default setting for the margin between axis labels and the plot is 5 big points, which is significantly larger than the similar spacing in the comms-produced graphic. Also, that value (5) is hard-coded into theme_cmap(), which might be better served as an adjustable value in the overrides list.

Flagging here because I think this could also benefit from adding the same functionality for y-axis labels, in cases where the labels are on the side - currently, the margin for those is not manually adjusted, and remains at the default.

Easier tick marks

Per an earlier conversation with @matthewstern in #68 I wanted to add a potential enhancement: making it easier for users to turn on tick marks. As this stands, it requires modifications to two different elements of the theme (see here), but this could be simplified for users that want to add a "default" style tick mark.

create debug_grobs mode in finalize_plot

add an argument called debug_grobs or similar, and implement code that draws outlines around the various grobs and viewports if the argument is set to TRUE.

With texbox grobs, this is probably best done in box_gp. In the plot, easiest is likely adding a theme element to the plot that paints a border. (this might change depending on @dlcomeaux 's legend implementation).

Fonts don't work when you install the package

I tried installing the package to use it on a graph I'm making, and it appears that the font issues we thought we'd solved are not solved. When I attempt to create a graph using theme_cmap it gives the following (and annoyingly familiar) error
message:

Warning messages:
1: In grid.Call(C_textBounds, as.graphicsAnnot(x$label), x$x, x$y,  :
  font family not found in Windows font database
2: In grid.Call(C_textBounds, as.graphicsAnnot(x$label), x$x, x$y,  :
  font family not found in Windows font database
3: In grid.Call(C_textBounds, as.graphicsAnnot(x$label), x$x, x$y,  :
  font family not found in Windows font database
4: In grid.Call(C_textBounds, as.graphicsAnnot(x$label), x$x, x$y,  :
  font family not found in Windows font database

As a result, it is exporting text in Arial, and not Calibri. The issue persists even after running finalize.

I'm not really sure how best to proceed on fixing this, as I really thought we had. But flagging for others to test if they get the same issue. In either case, we need to do some investigating.

`text_nudge_y` in `geom_recessions` does not seem to work

ggplot(filter(grp_over_time, category == "Services"), aes(x = year, y = realgrp, color = cluster)) +
  geom_recessions(text_nudge_x = 0.1, text_nudge_y = 1) +
  theme_cmap(hline = 0,
             axislines = "x",
             legend.max.columns = 3) +
  geom_line() +
  scale_x_continuous("Year", breaks = 2007:2017) +
  geom_text_lastonly(aes(label = realgrp), add_points = TRUE)

Set backup font in case Whitney is not installed

Use Calibri if possible.

package was working for me, tried to update, broken.

library(cmapplot)
> economy_basic

A tibble: 18 x 4

variable year sector value

1 Jobs 2001 local 2175402
2 Jobs 2001 tradedgoods 440908
3 Jobs 2001 tradedservices 1153064
4 Jobs 2017 local 2482547
5 Jobs 2017 tradedgoods 312112
6 Jobs 2017 tradedservices 1137597
7 Real Earnings 2001 local 109373872297
8 Real Earnings 2001 tradedgoods 32443025020
9 Real Earnings 2001 tradedservices 98962528774
10 Real Earnings 2017 local 127029954775
11 Real Earnings 2017 tradedgoods 28297549664
12 Real Earnings 2017 tradedservices 111886397025
13 Establishments 2001 local 121282
14 Establishments 2001 tradedgoods 8159
15 Establishments 2001 tradedservices 53911
16 Establishments 2017 local 146391
17 Establishments 2017 tradedgoods 8550
18 Establishments 2017 tradedservices 59761

ggplot(cluster_jobchange, aes(x = reorder(name, jobchange), y = jobchange, fill = category)) +

•  geom_col() +
  

•  coord_flip() +
  

•  cmapplot::theme_cmap()
  

Error in ggplot(cluster_jobchange, aes(x = reorder(name, jobchange), y = jobchange, :
object 'cluster_jobchange' not found

ggplot(cars) +

• geom_point(aes(x=speed, y = dist)) +
• style_cmap()
  Error in style_cmap() : could not find function "style_cmap"

a grouped and stacked bar chart (via interaction())

ggplot(economy_basic, aes(x = interaction(year, variable), y = value, fill = sector)) +

• geom_col(position = "fill") +
• scale_y_continuous(labels = scales::percent) +
• theme_cmap()
  Error in theme_cmap() : could not find function "theme_cmap"

discrete option for continuous palettes

From @gritzenthaler:
Maps are beyond the scope of this project, but perhaps someone might have a graphical need for displaying a continuous palette in binned form? Do you think it's worth taking the time to add a "discrete" argument to the functions? (The Viridis source code is here for reference: https://github.com/sjmgarnier/viridis/blob/master/R/scales.R. I'm poking around in it now.)

Fix `update_recessions()`

Looks like NBER has officially placed the US in a current recession (has no close-date), which is throwing off the function. Also, they upgraded their website and changed the URL location for the excel file. Quick fix applied in #85, but should revisit and make sure is working properly. Looks like the open-ended current recession is not processing correctly.

In addition, tryCatch methods should be implemented within the function so it doesn't hard-error, which will require revisiting the code within geom_recessions() (and presumably removing the TryCatch code implemented there)

built outputter function

export WEB, POWERPOINT, and REPORT versions of graphics as per the DESIGNER GUIDELINES section of this guide

Presumably based on bbplot::finalise_plot

improve add_recessions

• Inherit min, max, and type (date vs int) of x axis from the primary aes, rather than specifying them again. (see ggproto, as implemented in geom_text_lastonly?)
• cut off rectangles at highest and lowest grid lines rather than plot y axis min and max (better solution may be to define the y axis min and max as highest and lowest gridline so ymin = first gridline and ymax = last gridline).
• not really an enhancement, but we'll need to confirm down the road that "recessions" text defaults to correct font and size once theme_cmap is applied.
• there may be a way to improve the text_nudge_x argument's default to work better in more instances. Will need to play around.

establish centerpoint for divergent palettes

Figure out the easiest way to assign the midpoint of divergent palettes

lead on this here

add recession outlines to time series

Add transpo-related sample data

@MMenninger is it possible for you to import a couple of sample datasets still? It would be great to have a few things in here that are transportation focused, so that we can make sure we test with other types of data besides for economic and demographic.

It took me longer than I want to admit to figure out how to load in and document sample data. I would be happy to sit down with you and walk you through what I did. In hindsight it wasn't complicated...just not obvious how to do it right.

unable to use cmapplot continuous color palettes for fill aesthetic

I wanted to apply the built-in CMAP continuous palette to produce a continuous gradient fill aesthetic in a stacked bar chart. When I apply cmap_fill_continuous(palette = "seq_blues") to a stacked bar chart, I get the following error: "Error: Discrete value supplied to continuous scale". If I switch to cmap_color_continuous(palette = "seq_red_purple"), the code is ignored and the default ggplot colors are used.

I ended up having to use the ggplot color brewer, which worked. The example output I seek is attached.
scale_fill_brewer(palette = "Blues")

Update to systemfonts and ragg?

We should discuss whether it makes sense to upgrade font handling to use the new package systemfonts and new raster devices from the ragg package.

Resources:

• https://www.tidyverse.org/blog/2021/02/modern-text-features/#advanced-font-feature-support
• https://cran.r-project.org/web/packages/systemfonts/systemfonts.pdf
• https://ragg.r-lib.org/

While systemfonts should be able to handle fonts natively to some degree, it looks like a good way to guarantee font handling is to check for the font by filtering the df returned by system_fonts(), and if found use register_font(). We could do this with all three fonts we use, e.g.:

library(systemfonts)
register_font("Whitney Medium", "C:\\Windows\\Fonts\\Whitney-Medium-Adv.otf")
registry_fonts()

>                                         path index         family       style weight italic features
> 1 C:\\Windows\\Fonts\\Whitney-Medium-Adv.otf     0 Whitney Medium     Regular normal  FALSE     NULL
> 2 C:\\Windows\\Fonts\\Whitney-Medium-Adv.otf     0 Whitney Medium        Bold   bold  FALSE     NULL
> 3 C:\\Windows\\Fonts\\Whitney-Medium-Adv.otf     0 Whitney Medium      Italic normal   TRUE     NULL
> 4 C:\\Windows\\Fonts\\Whitney-Medium-Adv.otf     0 Whitney Medium Bold Italic   bold   TRUE     NULL

... except use the path from the df returned by system_fonts().

However, devices that don't communicate with systemfonts will not recognize these fonts. So, we'd need to address that across the board:

• upgrading to ragg devices for rasters solves this
• upgrading to svglite now solves this as of last month
• PDFs ????
• RStudio plotting supports agg via global settings override in v 1.4 and up.

I just upgraded RStudio (with IT help) and can confirm that after "registering" Whitney Medium as above...

ggplot() + 
    geom_text(
        aes(x = 0, y = 1, label = "the default is Arial"),
        size = 6
    ) + 
    geom_text(
        aes(x = 0, y = 0, label = "This is Whitney Medium"),
        family = "Whitney Medium",
        size = 6
    ) + 
    expand_limits(y = c(-1, 2)) + theme_void()

Note that the use of ragg as the default in Rstudio can be evaluated and set by code, so we could issue a package startup message or warning if ragg is not used, and/or actually have the package force the change (which we probably don't want to do).

> getOption("RStudioGD.backend")
[1] "default"
> options(RStudioGD.backend = "ragg")
> getOption("RStudioGD.backend")
[1] "ragg"

This seems likely to fix #116, as pkgdown now uses ragg devices by default.

improving iteration functionality in finalize_plot

In iteration through multiple save modes, finalize_plot will crash if one save fails. For example, if "test.pdf" already exists and is open by the user, so cannot be written to. Better behavior would be to skip that file if opening the device fails. I tried to implement tryCatch but couldn't figure it out.

Relatedly, the function currently overwrites past outputs with the same name with no warning or confirmation. Ideally tackled at the same time as the error handling above, it would be nice to introduce a new argument such as overwrite = TRUE, and have the function skip any existing file outputs that already exist if the argument is FALSE (the default).

Edit: the solution probably looks like this:

if(file.exists(file) & !overwrite){
    # warn and skip
  } else {
    tryCatch{
      # attempt the save
      # warn and move on if erroer
    }
  }

Example charts for cookbook

For the cookbook's fourth vignette, we decided to make a list of example "fully baked" CMAP charts. These should hit each of the major categories of charts that are regularly produced in CMAP publications and analyses. @gritzenthaler @nmpeterson @matthewstern @sarahcmap - please feel free to claim one (or more) of the following, or adding your own ideas, by editing this overview.

We can also have two examples for some of these, if there are good ones - in particular, given how common line and bar charts are, those might be good to have some extra.

Sample charts

• Line chart (a fully built-out version of the one that Matt is developing in his vignette is a good candidate for this)
• A scatterplot (like this one). Ideally, this will demonstrate changing both size and color of the points, as the linked one does.
• An area chart. My current idea would be to do a variant of the Line Chart 1 above and use the transit data in a different way to do this.
• Clustered bar chart: The replicated Census chart that I made should do the trick for this, as it demonstrates adjustments to bar sizes, annotations with text, dashed lines,
• Stacked bar chart (either absolute or scaled to share out of 100%)
• Some kind of chart using the highlight function (and probably a bar chart). There is a census piece chart that could be modified to do this, if no one has other ideas.
• A histogram
• A pie chart (for example, like these)
• A faceted chart (one of the above could also accomplish this).
• A chart using the race/ethnicity palette. One of the inclusive growth indicators would be a good candidate, e.g. this.

error in finalize w/o `theme_cmap`

Finalize fails for me due to a lack of unit object sometimes--it looks like this happens specifically when passing a non-theme-cmap() plot to finalize(). While this is an unlikely occurrence, it's not preferable and it would be nice to allow the user to do this if they wanted. It would be good to explore this and root out the problem if possible.

My initial guesses is this has something to do with the various theme modifications that work within finalize, and/or the legend extraction process.

constant modifier function

Timi ran into a problem today in which he needed to modify a value of cmapplot_globals - in his case, he wanted to shrink cmapplot_globals$fsize$S to something smaller than 11, the default. This is difficult/impossible to do from outside the the package, because (contrary to it's name!) cmapplot_globals is not a "global" variable from the user's perspective.

We could use a simple setter function modify_globals(name, value) that modifies a certain constant of cmapplot_globals.

Use cases:

# if name is found in cmapplot_globals, change the value of cmapplot_globals$name and return confirmation message
modify_globals("fsize$S", 8)

#if name is not found, do nothing and return error message
modify_globals("foo", 5)

this should be easy to do with the function assign... something like assign(paste0("cmapplot_globals$", name), value)... although I'm not sure that $ works within functions/strings like that.

Package logo

I spent a little bit of time working on a potential logo for the package, putting a CMAP twist on the tidyverse hexagon theme (they're seriously obsessed). I'm envisioning this being displayed both on the readme (i.e. GitHub project main page) like on ggplot2, as well as the navigation bar for the pkgdown site.

Here's what I came up with:

Thoughts?

Build general theme object

For fonts and sizes, use the DESIGNER GUIDELINES section of this guide.

For general layout, use a recent policy update such as this one.

Develop in R/theme_cmap.R

build color palettes

build a range of palettes including race/eth, Chi region and peers, and various sub-palettes and color scales for discrete and continuous data. All based on the master CMAP color palette.

Add `...` parameter to scale functions

I just ran into a case where I wanted to apply a color palette to a histogram with cmap_fill_discrete(). I also wanted to modify the legend labels, so I added scale_fill_discrete() with the labels parameter. These two functions conflict with each other, and only the last-specified one will be applied.

> ggplot(FACTORS_MUNI) +
+   geom_histogram(aes(x=SCORE_OVERALL_SCALED, fill=COHORT)) +
+   theme_cmap() +
+   scale_fill_discrete(labels=c("Cohort 1", "Cohort 2", "Cohort 3", "Cohort 4")) +
+   cmap_fill_discrete(palette="community")
Scale for 'fill' is already present. Adding another scale for 'fill', which will replace
the existing scale.

So with the above order, I got a plot that had the cmapplot palette applied, but not my custom labels. Switching the order yields a plot with custom labels and default ggplot colors. I tried supplying the labels parameter to cmap_fill_discrete, but we have not implemented that.

My current workaround is to use scale_fill_manual, where I can specify my own colors and labels.

I propose that all of cmapplot's color scale functions get a ... parameter that passes any extra parameters to the underlying ggplot scale functions that we're relying on.

Add title to vertical chart layout

Building on the work done in #111 and functionality tested in #109 , I am going to work on adding titles to the vertical layout.

This project is currently private. Should it be public?

update example

One of the examples in finalize_plot refers to the argument title_width. This should be updated to sidebar_width and a quick scan of examples in other man files should be done to confirm no deprecated args or constants are used.

package documentation/"cookbook"

Establish a digital book that helps new learn CMAPplot and help returning users implement it.

It's probably worth starting with reviewing the documentation for bbplot, and then implementing a framework for documentation development (pkg-down or bookdown?).

A few months ago, I had started to outline what should go in this packages readme and what should go in rmarkdown. I added a wiki file for the outline here, in the hopes we can develop it collaboratively.

repair SVG export

svg exports do not display correctly in Illustrator. However, they look fine in browsers. This is not a major issue, but solving it would be nice.

@sarahcmap reports that plots exported with ggsave() do display correctly in Illustrator.