{"id":18430179,"url":"https://github.com/friendly/heplots","last_synced_at":"2026-03-06T02:12:51.038Z","repository":{"id":56934543,"uuid":"13908453","full_name":"friendly/heplots","owner":"friendly","description":"Visualizing Hypothesis Tests in Multivariate Linear Models, http://friendly.github.io/heplots/","archived":false,"fork":false,"pushed_at":"2025-03-23T19:18:19.000Z","size":112353,"stargazers_count":9,"open_issues_count":3,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-01T21:55:52.856Z","etag":null,"topics":["linear-hypotheses","matrices","multivariate-linear-models","plot","repeated-measure-designs","visualizing-hypothesis-tests"],"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/friendly.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-10-27T19:10:06.000Z","updated_at":"2025-03-23T19:18:22.000Z","dependencies_parsed_at":"2023-02-01T03:15:58.448Z","dependency_job_id":"ff8159b7-728e-4847-96a2-c8995a5e2b61","html_url":"https://github.com/friendly/heplots","commit_stats":{"total_commits":532,"total_committers":5,"mean_commits":106.4,"dds":0.4849624060150376,"last_synced_commit":"bb1e9db3d06bae211f1cfd60a7cb773e484539e5"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friendly%2Fheplots","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friendly%2Fheplots/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friendly%2Fheplots/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friendly%2Fheplots/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/friendly","download_url":"https://codeload.github.com/friendly/heplots/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247698051,"owners_count":20981294,"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":["linear-hypotheses","matrices","multivariate-linear-models","plot","repeated-measure-designs","visualizing-hypothesis-tests"],"created_at":"2024-11-06T05:19:48.469Z","updated_at":"2026-03-06T02:12:51.029Z","avatar_url":"https://github.com/friendly.png","language":"R","readme":"---\noutput: github_document\neditor_options: \n  markdown: \n    wrap: 72\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file and knit again --\u003e\n\n```{r, echo = FALSE}\nknitr::opts_chunk$set(\n  warning = FALSE,   # avoid warnings and messages in the output\n  message = FALSE,\n  collapse = TRUE,\n  fig.width = 4,\n  fig.height = 4,\n  dpi = 96,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\"\n)\n\npar(mar=c(3,3,1,1)+.1)\n```\n\n```{r, echo=FALSE}\nlibrary(heplots)\n```\n\n\u003c!-- badges: start --\u003e\n\n[![Lifecycle:\nstable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)\n[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/heplots)](http://cran.r-project.org/package=heplots)\n[![R_Universe](https://friendly.r-universe.dev/badges/heplots)](https://friendly.r-universe.dev)\n[![Last Commit](https://img.shields.io/github/last-commit/friendly/heplots)](https://github.com/friendly/heplots/)\n[![Downloads](http://cranlogs.r-pkg.org/badges/grand-total/heplots)](https://cran.r-project.org/package=heplots)\n[![DOI](https://zenodo.org/badge/13908453.svg)](https://zenodo.org/badge/latestdoi/13908453)\n[![Docs](https://img.shields.io/badge/pkgdown%20site-blue)](https://friendly.github.io/heplots/)\n\u003c!-- badges: end --\u003e\n\n# heplots \u003cimg src=\"man/figures/logo.png\" height=\"200\" style=\"float:right; height:200px;\"/\u003e\n\n## **Visualizing Hypothesis Tests in Multivariate Linear Models** \n\n\u003c!-- Version 1.7.2 --\u003e\nVersion `r getNamespaceVersion(\"heplots\")`; documentation built for `pkgdown` `r Sys.Date()`\n\n## Description \n\nThe `heplots` package provides functions for visualizing hypothesis\ntests in multivariate linear models (\"MLM\" = {MANOVA, multivariate multiple\nregression, MANCOVA, and repeated measures designs}). It also provides other tools for\nanalysis and graphical display of MLMs.\n\nHE plots represent sums-of-squares-and-products matrices for linear\nhypotheses (**H**) and for error (**E**) using ellipses (in two\ndimensions), ellipsoids (in three dimensions), or by line segments in\none dimension. For the theory and applications, see:\n\n-   [Friendly (2007)](http://datavis.ca/papers/jcgs-heplots.pdf) for the basic theory on which this is based.\n-   [Fox, Friendly and Monette (2009)](https://datavis.ca/papers/FoxFriendlyMonette-2009.pdf) for a brief introduction,\n-   [Friendly (2010)](http://www.jstatsoft.org/v37/i04/paper) for the application of these ideas to repeated\n    measure designs,\n-   [Friendly, Monette and Fox (2013)](http://datavis.ca/papers/ellipses-STS402.pdf) for a general discussion of the role of elliptical geometry in statistical understanding, \n-   [Friendly \u0026 Sigal (2017)](https://doi.org/10.20982/tqmp.13.1.p020) for an applied R tutorial, \n-   [Friendly \u0026 Sigal (2018)](https://www.datavis.ca/papers/EqCov-TAS.pdf) for theory and examples of visualizing equality of covariance matrices.\n\nIf you use this work in teaching or research, please cite it as given by `citation(\"heplots\")` or see [Citation](authors.html#citation).\n\nOther topics now addressed here include:\n\n-   robust MLMs, using iteratively re-weighted least squared to\n    down-weight observations with large multivariate residuals,\n    `robmlm()`.\n-   `Mahalanobis()` calculates classical and _robust_ Mahalanobis squared\n    distances using MCD and MVE estimators of center and covariance.\n-   visualizing tests for equality of covariance matrices in MLMs (Box's\n    M test), `boxM()` and `plot.boxM()`. Also: `bartlettTests()` and `LeveneTests()`\n    for homogeneity of variance for each response in a MLM.\n-   $\\chi^2$ Q-Q plots for MLMs (`cqplot()`) to detect outliers and\n    assess multivariate normality of residuals.\n-   bivariate coefficient plots showing elliptical confidence regions\n    (`coefplot()`).\n\nIn this respect, the `heplots` package now aims to provide a wide range\nof tools for analyzing and visualizing multivariate response linear\nmodels, together with other packages:\n\n\u003ca href=\"https://friendly.github.io/candisc/\"\u003e\u003cimg src='https://raw.githubusercontent.com/friendly/candisc/master/candisc-logo.png' height='80' alt=\"candisc logo\"   style=\"float:right; height:80px;\"\u003e\u003c/a\u003e\n\n-   The related [`candisc`](https://friendly.github.io/candisc/) package\n    provides HE plots in **canonical discriminant** space, the space of\n    linear combinations of the responses that show the maximum possible\n    effects and for canonical correlation in multivariate regression\n    designs. See the [package documentation](https://friendly.github.io/candisc/)\n    for details.\n\n\u003ca href=\"https://friendly.github.io/mvinfluence/\"\u003e\u003cimg src='https://raw.githubusercontent.com/friendly/mvinfluence/master/man/figures/logo.png' height='80' alt=\"mvinfluence logo\"   style=\"float:right; height:80px;\"\u003e\u003c/a\u003e\n\n-   Another package,\n    [`mvinfluence`](https://friendly.github.io/mvinfluence/), provides\n    diagnostic measures and plots for **influential observations** in MLM\n    designs. See the [package documentation](https://friendly.github.io/mvinfluence/)\n    for details.\n\n\nSeveral tutorial vignettes are also included. See\n`vignette(package=\"heplots\")`.\n\n## Installation\n\n+-------------------+----------------------------------------------------------------------------+\n| CRAN version      | `install.packages(\"heplots\")`                                              |\n+-------------------+----------------------------------------------------------------------------+\n| R-universe        | `install.packages(\"heplots\", repos = c('https://friendly.r-universe.dev')` |\n+-------------------+----------------------------------------------------------------------------+\n| Development       | `remotes::install_github(\"friendly/heplots\")`                              |\n| version           |                                                                            |\n+-------------------+----------------------------------------------------------------------------+\n\n\n## HE plot functions\n\nThe graphical functions contained here all display multivariate model\neffects in variable (**data**) space, for one or more response variables\n(or contrasts among response variables in repeated measures designs).\n\n-   `heplot()` constructs two-dimensional HE plots for model terms and\n    linear hypotheses for pairs of response variables in multivariate\n    linear models.\n\n-   `heplot3d()` constructs analogous 3D plots for triples of response\n    variables.\n\n-   The `pairs` method, `pairs.mlm()` constructs a scatterplot matrix of\n    pairwise HE plots.\n\n-   `heplot1d()` constructs 1-dimensional analogs of HE plots for model\n    terms and linear hypotheses for single response variables.\n\n## Other functions\n\n-   `glance.mlm()` extends `broom::glance.lm()` to multivariate response\n    models, giving a one-line statistical summary for each response\n    variable. `uniStats()` does something similar, but formatted more like a ANOVA table.\n\n-   `boxM()` Calculates Box's *M* test for homogeneity of covariance\n    matrices in a MANOVA design. A `plot` method displays a visual\n    representation of the components of the test. Associated with this,\n    `bartletTests()` and `levineTests()` give the univariate tests of\n    homogeneity of variance for each response measure in a MLM.\n\n-   `covEllipses()` draw covariance (data) ellipses for one or more\n    group, optionally including the ellipse for the pooled within-group\n    covariance. \n    \n-   `coefplot()` for an MLM object draws bivariate confidence ellipses.\n\n### Repeated measure designs\n\nFor repeated measure designs, between-subject effects and within-subject\neffects must be plotted separately, because the error terms (**E**\nmatrices) differ. For terms involving within-subject effects, these\nfunctions carry out a linear transformation of the matrix **Y** of\nresponses to a matrix **Y M**, where **M** is the model matrix for a\nterm in the intra-subject design and produce plots of the **H** and **E**\nmatrices in this transformed space. The vignette `\"repeated\"` describes\nthese graphical methods for repeated measures designs. (This\npaper [HE plots for repeated measures\ndesigns](http://www.jstatsoft.org/v37/i04/paper) is now provided as a PDF vignette.)\n\n## Datasets\n\nThe package also provides a large collection of data sets illustrating a\nvariety of multivariate linear models of the types listed above,\ntogether with graphical displays. The table below classifies these with\nmethod tags. Their names are linked to their documentation with graphical output on the\n`pkgdown` website, [\u003chttp://friendly.github.io/heplots\u003e].\n\n```{r datasets, echo=FALSE}\nlibrary(here)\nlibrary(dplyr)\nlibrary(tinytable)\n#dsets \u003c- read.csv(here::here(\"extra\", \"datasets.csv\"))\ndsets \u003c- read.csv(\"https://raw.githubusercontent.com/friendly/heplots/master/extra/datasets.csv\")\ndsets \u003c- dsets |\u003e dplyr::select(-X) |\u003e arrange(tolower(dataset))\n\n# link dataset to pkgdown doc\nrefurl \u003c- \"http://friendly.github.io/heplots/reference/\"\n\ndsets \u003c- dsets |\u003e\n  mutate(dataset = glue::glue(\"[{dataset}]({refurl}{dataset}.html)\")) \n\ntinytable::tt(dsets)\n#knitr::kable(dsets)\n```\n\n## Examples\n\nThis example illustrates HE plots using the classic `iris` data set. How\ndo the means of the flower variables differ by `Species`? This dataset\nwas the impetus for R. A. Fisher (1936) to propose a method of\ndiscriminant analysis using data collected by Edgar Anderson (1928).\nThough some may rightly deprecate Fisher for being a supporter of\neugenics, Anderson's `iris` dataset should not be blamed.\n\nA basic HE plot shows the **H** and **E** ellipses for the first two\nresponse variables (here: `Sepal.Length` and `Sepal.Width`). The\nmultivariate test is significant (by Roy's test) *iff* the **H** ellipse\nprojects *anywhere* outside the **E** ellipse.\n\nThe positions of the group means show how they differ on the two\nresponse variables shown, and provide an interpretation of the\norientation of the **H** ellipse: it is long in the directions of\ndifferences among the means.\n\n```{r iris1}\n#| echo=-1,\n#| out.width=\"70%\",\n#| fig.cap = \"HE plot of sepal length and Sepal width for the iris data\"\npar(mar=c(4,4,1,1)+.1)\niris.mod \u003c- lm(cbind(Sepal.Length, Sepal.Width, Petal.Length, Petal.Width) ~ \n                 Species, data=iris)\nheplot(iris.mod)\n```\n\n### Contrasts\n\nContrasts or other linear hypotheses can be shown as well, and the\nellipses look better if they are filled. We create contrasts to test the\ndifferences between `versacolor` and `virginca` and also between\n`setosa` and the average of the other two. Each 1 df contrast plots as\ndegenerate 1D ellipse-- a line.\n\nBecause these contrasts are orthogonal, they add to the total 2 df\neffect of `Species`. Note how the first contrast, labeled `V:V`,\ndistinguishes the means of *versicolor* from *virginica*; the second\ncontrast, `S:VV` distinguishes `setosa` from the other two.\n\n```{r iris2, out.width=\"70%\"}\n#| fig.cap = \"HE plot of sepal length and Sepal width for the iris data, showing lines reflecting two contrasts among iris species.\"\npar(mar=c(4,4,1,1)+.1)\ncontrasts(iris$Species)\u003c-matrix(c(0, -1, 1, \n                                  2, -1, -1), nrow=3, ncol=2)\ncontrasts(iris$Species)\niris.mod \u003c- lm(cbind(Sepal.Length, Sepal.Width, Petal.Length, Petal.Width) ~ \n                 Species, data=iris)\n\nhyp \u003c- list(\"V:V\"=\"Species1\",\"S:VV\"=\"Species2\")\nheplot(iris.mod, hypotheses=hyp, \n       fill=TRUE, fill.alpha=0.1)\n```\n\n### All pairwise HE plots\n\nAll pairwise HE plots are produced using the `pairs()` method for MLM\nobjects.In the plot, note how the means of most pairs of variables are very\nhighly correlated, in the order Setosa \u003c Versicolor \u003c Virginica, but this\npattern doesn't hold for relations with `Sepal.Width`.\n\n```{r, iris3}\n#| out.width=\"100%\",\n#| fig.height = 6,\n#| fig.width = 6,\n#| fig.cap = \"Scatterplot matrix of pairwise HE plots for the iris data.\"\npairs(iris.mod, hypotheses=hyp, hyp.labels=FALSE,\n      fill=TRUE, fill.alpha=0.1)\n```\n\n### Canonical discriminant view\n\nFor more than two response variables, a multivariate effect can be viewed more simply by projecting\nthe data into canonical space --- the linear combinations of the responses which show the greatest\ndifferences among the group means relative to within-group scatter. The computations are performed\nwith the [`candisc`](https://github.com/friendly/candisc/) package, which has an `heplot.candisc()`\nmethod.\n\n```{r iris-can0}\nlibrary(candisc)\niris.can \u003c- candisc(iris.mod) |\u003e print()\n```\n\nThe HE plot in canonical space shows that the differences among species are nearly\nentirely one-dimensional. The weights for the variables on the first dimension\nshow how `Sepal.Width` differs from the other size variables.\n```{r iris-can}\n#| out.width = \"60%\",\n#| echo = -1,\n#| fig.cap = \"Canonical HE plot for the iris data\"\npar(mar=c(4,4,1,1)+.1)\n# HE plot in canonical space\nheplot(iris.can, var.pos = 1, scale = 40)\n```\n\n\n### Covariance ellipses\n\nMANOVA relies on the assumption that within-group covariance matrices are all equal.\nIt is useful to visualize these in the space of some of the predictors.\n`covEllipses()` provides this both for classical and robust (`method=\"mve\"`) estimates.\nThe figure below shows these for the three Iris species and the \npooled covariance matrix, which is the same as the **E** matrix used\nin MANOVA tests.\n```{r iris4, out.width=\"80%\"}\n#| echo = -1,\n#| fig.cap = \"Covariance ellipses for the iris data, showing the classical and robust estimates.\"\npar(mar=c(4,4,1,1)+.1)\ncovEllipses(iris[,1:4], iris$Species)\ncovEllipses(iris[,1:4], iris$Species, \n            fill=TRUE, method=\"mve\", add=TRUE, labels=\"\")\n```\n\n## References\n\nAnderson, E. (1928). The Problem of Species in the Northern Blue Flags,\nIris versicolor L. and Iris virginica L. *Annals of the Missouri\nBotanical Garden*, **13**, 241--313.\n\nFisher, R. A. (1936). The Use of Multiple Measurements in Taxonomic\nProblems. *Annals of Eugenics*, **8**, 379--388.\n\nFriendly, M. (2006).\n[Data Ellipses, HE Plots and Reduced-Rank Displays for Multivariate Linear Models: \nSAS Software and Examples.](https://www.jstatsoft.org/article/view/v017i06) \n_Journal of Statistical Software_, **17**, 1-42.\n\nFriendly, M. (2007).  [HE plots for Multivariate General Linear Models](http://datavis.ca/papers/jcgs-heplots.pdf).\n_Journal of Computational and Graphical Statistics_, **16**(2) 421-444.\nDOI: 10.1198/106186007X208407.\n\n\nFox, J., Friendly, M. \u0026 Monette, G. (2009). [Visualizing hypothesis\ntests in multivariate linear models: The heplots package for R](https://datavis.ca/papers/FoxFriendlyMonette-2009.pdf) *Computational Statistics*, **24**, 233-246.\n\n\nFriendly, M. (2010). [HE plots for repeated measures\ndesigns](http://www.jstatsoft.org/v37/i04/paper). *Journal of\nStatistical Software*, **37**, 1--37.\n\nFriendly, M.; Monette, G. \u0026 Fox, J. (2013). [Elliptical Insights:\nUnderstanding Statistical Methods Through Elliptical\nGeometry](http://datavis.ca/palers/ellipses-STS402.pdf) *Statistical\nScience*, **28**, 1-39.\n\nFriendly, M. \u0026 Sigal, M. (2017). [Graphical Methods for Multivariate\nLinear Models in Psychological Research: An R\nTutorial.](https://doi.org/10.20982/tqmp.13.1.p020) *The Quantitative\nMethods for Psychology*, **13**, 20-45.\n\nFriendly, M. \u0026 Sigal, M. (2018): [Visualizing Tests for Equality of\nCovariance Matrices](https://www.datavis.ca/papers/EqCov-TAS.pdf), _The American Statistician_, [DOI](https://doi.org/10.1080/00031305.2018.1497537)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriendly%2Fheplots","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffriendly%2Fheplots","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriendly%2Fheplots/lists"}