{"id":16876947,"url":"https://github.com/jlmelville/vizier","last_synced_at":"2025-04-11T11:33:02.230Z","repository":{"id":147289613,"uuid":"106159122","full_name":"jlmelville/vizier","owner":"jlmelville","description":"Visualization of 2D Datasets in R","archived":false,"fork":false,"pushed_at":"2024-09-14T20:29:17.000Z","size":268,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-25T07:51:13.078Z","etag":null,"topics":["plotly","r","visualization"],"latest_commit_sha":null,"homepage":"","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jlmelville.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-08T07:51:45.000Z","updated_at":"2024-09-14T20:29:20.000Z","dependencies_parsed_at":"2023-11-25T19:26:06.610Z","dependency_job_id":"2e09c0e4-a5c6-4166-a62f-61df47fc1190","html_url":"https://github.com/jlmelville/vizier","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlmelville%2Fvizier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlmelville%2Fvizier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlmelville%2Fvizier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlmelville%2Fvizier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlmelville","download_url":"https://codeload.github.com/jlmelville/vizier/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248384175,"owners_count":21094682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["plotly","r","visualization"],"created_at":"2024-10-13T15:41:02.963Z","updated_at":"2025-04-11T11:33:02.207Z","avatar_url":"https://github.com/jlmelville.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vizier\n\n[![Last Commit](https://img.shields.io/github/last-commit/jlmelville/vizier)](https://github.com/jlmelville/vizier)\n\nAn R Package for Visualization of 2D Datasets.\n\n## News\n\n**November 25 2023**: use [Polychrome](https://cran.r-project.org/package=Polychrome)\nto generate default color schemes for categorical data.\n\n**September 6 2020**: fix `alpha_scale` with `embed_plotly`. Also, new \nparameter: `limits` for `embed_plotly`.\n\n**August 26 2020**: version 0.4 includes the following improvements and fixes: \n\n* Fixed bug where using recent versions of\n[paletteer](https://cran.r-project.org/package=paletteer) for choosing the color\nscheme was broken.\n* The\n[turbo colormap](https://ai.googleblog.com/2019/08/turbo-improved-rainbow-colormap-for.html)\n(based on a \n[github gist](https://gist.github.com/jlmelville/be981e2f36485d8ef9616aef60fd52ab))\nhas been added as the `turbo` function.\n* New argument `rev` to reverse the ordering of the colors in the palette. This\nis useful when comparing `turbo` with other rainbow palettes because `turbo`\ngoes from blue to red.\n* For the \n[new color palettes in R 4.0](https://developer.r-project.org/Blog/public/2019/11/21/a-new-palette-for-r/index.html),\nyou can pass them by name, e.g. `color_scheme = \"Okabe-Ito\"`.\n* `colorRampPalette` is only used if you need to interpolate the palette (i.e.\nif you ask for more colors than exist in the palette). Colors will now be\nreturned in the order they appear in the palette.\n\n**September 27 2018**: Color schemes with `embed_plotly` was badly messed up.\nThis now fixed. You now also have control over whether to interpolate a discrete\npalette.\n\nVisualizing datasets in 2D (e.g. via PCA, Sammon Mapping, t-SNE) is much more\ninformative if the points are colored, using something like:\n\n* Factor levels mapped to different colors.\n* A numeric value mapped to a color scale.\n* A string encoding a color.\n\nThis package is to make doing that a bit easier, using the `graphics::plot`\nfunction, or via the [plotly](https://plot.ly/) JavaScript library. If you\ndon't specify a specific column to color by, it will attept to find a suitable\nfactor or color column automatically, using the last suitable column found, so\nyou can add a custom column to a dataframe if needed and have it picked out \nautomatically.\n\n## Installing\n\n```R\ninstall.packages(\"devtools\")\ndevtools::install_github(\"jlmelville/vizier\")\n```\n\n## Documentation\n\n```R\n?embed_plot\n?embed_plotly\n```\n\n## Examples\n\nCreate a plot of the first two principal components (PCA) for the `iris`\ndataset:\n\n```R\npca_iris \u003c- stats::prcomp(iris[, -5], retx = TRUE, rank. = 2)\n```\n\nSimplest use of embed_plot: pass in data frame and it will use the last \n(in this case, only) factor column it finds and the `rainbow` color scheme\n\n```R\nembed_plot(pca_iris$x, iris)\n```\n![Default embed plot result](img/embed_ex.png \"embed_plot(pca_iris$x, iris)\")\n\n\nMore explicitly color by iris species, use the rainbow color scheme and also\nprovide a title and subtitle:\n\n```R\nembed_plot(pca_iris$x, iris$Species, color_scheme = rainbow, title = \"iris PCA\", sub = \"rainbow color scheme\")\n```\n![Embed plot with a title](img/embed_ex_title.png \"embed_plot(pca_iris$x, iris$Species, color_scheme = rainbow, title = \\\"iris PCA\\\")\")\n\n\nIncrease the transparency of the fill color by scaling the alpha by 0.5:\n\n```R\nembed_plot(pca_iris$x, iris$Species, color_scheme = rainbow, alpha_scale = 0.5)\n```\n![Embed plot with transparency](img/embed_ex_alpha.png \"embed_plot(pca_iris$x, iris$Species, color_scheme = rainbow, alpha_scale = 0.5)\")\n\nIf you already have colors you want to use for each point, you can use the\n`colors` parameter. In the example below, \n`colorRampPalette(c(\"red\", \"yellow\"))(nrow(iris)))` produces a vector of 150 \ncolors going from red to yellow:\n\n```R\nmy_iris_colors = colorRampPalette(c(\"red\", \"yellow\"))(nrow(iris))\nembed_plot(pca_iris$x, iris$Species, colors = my_iris_colors)\n```\n\n![Embed plot with colors](img/embed_ex_colors.png \"embed_plot(pca_iris$x, iris$Species, colors = my_iris_colors)\")\n\nIf you just want the points to be all one color you need only pass a single\nvalue, e.g. `colors = \"blue\"`. In general, if you pass fewer colors than there\nare points, the colors are recycled.\n\nHere's another example of using a built-in palette, `topo.colors`:\n\n![Embed plot with a topo color scheme](img/embed_ex_topo.png \"embed_plot(pca_iris$x, iris$Species, color_scheme = topo.colors)\")\n\nThis package also includes the\n[turbo colormap](https://ai.googleblog.com/2019/08/turbo-improved-rainbow-colormap-for.html)\nas a palette, via the `turbo` function, which works a lot like \n`grDevices::rainbow` (although reversed in terms of colors):\n\n```R\nembed_plot(pca_iris$x, iris$Species, color_scheme = turbo)\n```\n\n![Embed plot with the turbo color scheme](img/embed_ex_turbo.png \"embed_plot(pca_iris$x, iris$Species, color_scheme = turbo)\")\n\nThe `rev` argument can be used to reverse a color scheme:\n\n```R\nembed_plot(pca_iris$x, iris$Species, color_scheme = turbo, rev = TRUE)\n```\n\n![Embed plot with the turbo color scheme reversed](img/embed_ex_turbo_rev.png \"embed_plot(pca_iris$x, iris$Species, color_scheme = turbo, rev = TRUE)\")\n\nYou can also provide your own palette (i.e. a vector colors):\n\n```R\nembed_plot(pca_iris$x, iris$Species, color_scheme = c(\"black\", \"red\", \"gray\"))\n```\n\n![Embed plot with custom palette](img/embed_ex_custom.png \"embed_plot(pca_iris$x, iris$Species, color_scheme = c(\\\"black\\\", \\\"red\\\", \\\"gray\\\"))\")\n\nNote that if you have more colors in your palette than needed, the extra ones\nare ignored: e.g. if `c(\"black\", \"red\", \"gray\", \"blue\")`, `\"blue\"` would have\nbeen unused, because we only needed three colors from the palette for this plot\nfor the three species.\n\nWatch out for the opposite situation where you need *more* colors than your\npalette provides. In this case `vizier` will use interpolation to get the colors\nit needs. This might work out for some palettes that represent a continuous\ncolor scale (like `rainbow`), but will give weird and probably undesirable\nresults for discrete palettes. For more details, see the section \n\"Discrete Palettes with `continuous` Type\" below.\n\nAs of R 4.0, there are some \n[new color palettes](https://developer.r-project.org/Blog/public/2019/11/21/a-new-palette-for-r/index.html).\nYou can see the options available via `grDevices::palette.pals()` and generate\nthe palette using `grDevices::palette.colors`. Here's an example using the `\"Okabe-Ito\"`\npalette:\n\n```R\nif (exists(\"palette.colors\", where = \"package:grDevices\")) {\n  embed_plot(pca_iris$x, iris$Species, color_scheme = palette.colors(palette = \"Okabe-Ito\"))\n}\n```\n![Embed plot with new built-in palette](img/embed_ex_okabe_ito.png \"embed_plot(pca_iris$x, iris$Species, color_scheme = palette.colors(palette = \\\"Okabe-Ito\\\"))\")\n\nFor any palette in `palette.pals`, you can also just provide the palette name\nas a shortcut:\n\n```\nembed_plot(pca_iris$x, iris$Species, color_scheme = \"Okabe-Ito\")\n```\n\nTo force axes to be equal size to stop clusters being distorted in one direction:\n\n```R\nembed_plot(pca_iris$x, iris$Species, color_scheme = topo.colors, equal_axes = TRUE)\n```\n\n![Embed plot with equal axes](img/embed_ex_ax.png \"embed_plot(pca_iris$x, iris$Species, color_scheme = topo.colors, equal_axes = TRUE)\")\n\nYou can plot the category names instead of points, but it looks bad if they're\nlong (or the dataset is large. Making the text a bit smaller with the `cex` \nparam can help:\n\n```R\nembed_plot(pca_iris$x, iris$Species, cex = 0.75, text = iris$Species)\n```\n\n![Embed plot with text labels](img/embed_ex_text.png \"embed_plot(pca_iris$x, iris$Species, cex = 0.75, text = iris$Species)\")\n\nFor more color schemes, Vizier makes use of the excellent \n[paletteer](https://cran.r-project.org/package=paletteer) package. \nYou can select one of the palettes on offer by (among other ways) passing a \nstring with the format`\"package::palette\"`. For example, to use the `Dark2`\nscheme from the the \n[RColorBrewer](https://cran.r-project.org/package=RColorBrewer) package \n(itself based on [ColorBrewer](http://www.colorbrewer2.org) schemes):\n\n```R\nembed_plot(pca_iris$x, iris, color_scheme = \"RColorBrewer::Dark2\")\n```\n![Embed plot with ColorBrewer color scheme](img/embed_ex_cb.png \"embed_plot(pca_iris$x, iris, color_scheme = \\\"RColorBrewer::Dark2\\\")\")\n\nFor more on selecting color schemes, see the 'Color Schemes' section below.\nHere's another example, using a continuous palette from RColorBrewer, useful\nfor mapping numeric vectors to the color:\n\n```R\n# Visualize numeric value (petal length) as a color\nembed_plot(pca_iris$x, iris$Petal.Length, color_scheme = \"RColorBrewer::Blues\")\n```\n![Embed plot with quantitative color scale](img/embed_ex_quant.png \"embed_plot(pca_iris$x, iris$Petal.Length, color_scheme = \\\"RColorBrewer::Blues\\\")\")\n\n```R\n# Just show the points with the 10 longest petals\nembed_plot(pca_iris$x, iris$Petal.Length, color_scheme = \"RColorBrewer::Blues\", top = 10)\n```\n![Embed plot only showing top 10 petal lengths](img/embed_ex_top.png \"embed_plot(pca_iris$x, iris$Petal.Length, color_scheme = \\\"RColorBrewer::Blues\\\", top = 10)\")\n\nIf you install the [plotly](https://cran.r-project.org/package=plotly) package,\nyou can use the `embed_plotly` function which has the same interface as \n`embed_plot` (except the `top` and `sub` parameters are missing). This has the advantage\nof showing a legend and tooltips:\n\n```R\nembed_plotly(pca_iris$x, iris)\n```\n![Embed plot as a webpage with plotly](img/embed_ex_plotly.png \"embed_plotly(pca_iris$x, iris)\")\n\n```R\n# Don't have to see a legend if custom tooltips will do\nembed_plotly(pca_iris$x, iris, show_legend = FALSE, tooltip = paste(\"Species:\", iris$Species))\n```\n\n![plotly with custom tooltips](img/embed_ex_plotly_tooltip.png \"embed_plotly(pca_iris$x, iris, show_legend = FALSE, tooltip = paste(\\\"Species:\\\", iris$Species))\")\n\n## Color Schemes\n\nVizier makes use of the wonderful \n[paletteer](https://cran.r-project.org/package=paletteer) package which unifies\nthe enormous number of palettes out there. To specify a color scheme, use the\n`color_scheme` parameter, passing one of:\n\n* A palette function that takes an integer `n` and returns a vector of colors,\ne.g. `grDevices::rainbow`.\n* A vector of colors making up a custom color scheme of your own devising, e.g.\n`c('red', 'green', 'blue')`. There must be at least two colors in the list.\n* The name of a color scheme provided by `paletteer`, in the form \n`\"package::palette\"`. For a list of the many, many palettes supported, see\n[paletteer's github page](https://github.com/EmilHvitfeldt/paletteer). Some\nexamples include `\"dutchmasters::milkmaid\"`, `\"cartography::green.pal\"`, \n`\"viridis::inferno\"`, `\"RColorBrewer::Dark2\"`. `vizier` makes no distinction\nbetween the continuous, fixed-width or dynamic palette classification used by\n`paletteer`.\n\n### Palette Interpolation\n\nIf the color scheme you select has a maximum number of colors, and `vizier`\nneeds to use more than those that are available, then it will interpolate\namong the maximum number of colors to create the desired number. This may lead\nto results where different categories are hard to distinguish from each other.\nIf you set `verbose = TRUE`, then if interpolation is required, a message will \nbe logged to console to this effect. `paletteer` has information on the number\nof colors available in each palette.\n\n### Discrete Palettes with `continuous` Type\n\nFor discrete palettes, if you ask for fewer colors than the full range, you will\nonly get the first few colors from the palette. For some palettes this works \nfine. For example, here is the `Dark2` palette from `RColorBrewer`:\n\n![RColorBrewer Dark2 swatch](img/dark2_swatch.png \"swatches::show_palette(paletteer::paletteer_d(\\\"RColorBrewer\\\", \\\"Dark2\\\"))\")\n\nIf you use this palette to color the iris PCA:\n\n![iris PCA with Dark2 color scheme](img/embed_dark2.png \"embed_plot(pca_iris$x, iris, color_scheme = \\\"RColorBrewer::Dark2\\\", cex = 2, title = \\\"RColorBrewer Dark2\\\")\")\n\nThe three colors from the lefthand side of the swatch are used to color the \nspecies.\n\nHowever, some discrete palettes have an ordering to them, e.g. they go to from\nred to blue via yellow. Here's `rainbow` from the `jcolors` package:\n\n![jcolors rainbow](img/rainbow_swatch.png \"swatches::show_palette(paletteer::paletteer_d(\\\"jcolors\\\", \\\"rainbow\\\"))\")\n\nThe PCA embedding now looks like:\n\n![iris PCA with rainbow color scheme](img/embed_jcrainbow.png \"embed_plot(pca_iris$x, iris, color_scheme = \\\"jcolors::rainbow\\\", cex = 2, title = \\\"jcolors rainbow\\\")\")\n\nIf you would prefer to use a fuller extent of the palette, you can treat the\npalette as continuous, by appending `::c` to the name of the color scheme, \ne.g. `\"jcolors::rainbow::c\"`. Now the result is:\n\n![iris PCA with continuous rainbow color scheme](img/embed_jcrainbowc.png \"embed_plot(pca_iris$x, iris, color_scheme = \\\"jcolors::rainbow::c\\\", cex = 2, title = \\\"jcolors rainbow (continuous)\\\")\")\n\nwhere the colors come from the left-most, right-most and center positions on\nthe swatch.\n\nThe downside to treating these palettes as continuous is that there is no \nguarantee that the interpolation will result in colors that actually come from\nthe palette. In fact, they probably won't. We just got lucky in the above\nexample, because interpolating between colors was not required. For colors which\nshow a natural progression like `jcolors::rainbow`, results should still be ok.\nHowever, for palettes like `RColorBrewer::Dark2`, interpolation may not turn out\nso well. The iris PCA with the \"continuous\" version of Dark2, i.e. specifying \n`RColorBrewer::Dark2::c` results in:\n\n![iris PCA with continuous Dark2 color scheme](img/embed_dark2c.png \"embed_plot(pca_iris$x, iris, color_scheme = \\\"RColorBrewer::Dark2::c\\\", cex = 2, title = \\\"RColorBrewer Dark2 (continuous)\\\")\")\n\nThe left cluster uses the green from the left-hand of the Dark2 swatch, and the\nright cluster is colored in the gray color from the right-hand side. But the\nmiddle cluster isn't any of the other colors and mixes rather murkily with the\ngray cluster. It doesn't make sense to use interpolation in this case.\n\nIn summary, avoid interpolation of discrete color schemes if you can, and \n*definitely* do avoid for those like `RColorBrewer::Dark2` which don't work on a\ncolor scale.\n\n## License\n\n[GPL-3](https://www.gnu.org/licenses/gpl-3.0.en.html). The code for the\n`turbo` color scheme is from \u003chttps://gist.github.com/jlmelville/be981e2f36485d8ef9616aef60fd52ab\u003e\nand is licensed under Apache 2.\n\n## See Also\n\n* More example datasets that I've used these functions with can be found in the [snedata](https://github.com/jlmelville/snedata) and [COIL-20](https://github.com/jlmelville/coil20) packages.\n* [quadra](https://github.com/jlmelville/quadra) for assessing the results quantitatively. This one's a bit rough at the moment, though.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlmelville%2Fvizier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlmelville%2Fvizier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlmelville%2Fvizier/lists"}