{"id":24895394,"url":"https://github.com/watanabe-j/eigvaldisp","last_synced_at":"2025-08-01T03:34:50.565Z","repository":{"id":143163100,"uuid":"423615523","full_name":"watanabe-j/eigvaldisp","owner":"watanabe-j","description":"R package for statistics of eigenvalue dispersion indices","archived":false,"fork":false,"pushed_at":"2023-12-07T12:49:06.000Z","size":193,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-01T19:18:22.479Z","etag":null,"topics":["correlation-matrix","covariance-matrix","eigenvalues","evolutionary-biology","morphometrics","r","r-package"],"latest_commit_sha":null,"homepage":"","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/watanabe-j.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-11-01T21:03:04.000Z","updated_at":"2022-12-07T13:16:31.000Z","dependencies_parsed_at":"2023-07-03T04:32:19.204Z","dependency_job_id":null,"html_url":"https://github.com/watanabe-j/eigvaldisp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watanabe-j%2Feigvaldisp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watanabe-j%2Feigvaldisp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watanabe-j%2Feigvaldisp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watanabe-j%2Feigvaldisp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/watanabe-j","download_url":"https://codeload.github.com/watanabe-j/eigvaldisp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245870002,"owners_count":20685952,"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":["correlation-matrix","covariance-matrix","eigenvalues","evolutionary-biology","morphometrics","r","r-package"],"created_at":"2025-02-01T19:18:24.193Z","updated_at":"2025-03-27T15:25:55.172Z","avatar_url":"https://github.com/watanabe-j.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"# eigvaldisp\nR package for statistics of eigenvalue dispersion indices\n\nThis package involves functions for analyzing eigenvalue dispersion\nindices of covariance and correlation matrices\u0026mdash;common measures\nof phenotypic integration in biometrics.\nThe primary feature of this package is to calculate expectation and\nvariance (i.e., sampling bias and error) of eigenvalue dispersion indices\nfor arbitrary population covariance structures\nunder multivariate normality.\n\nThis package was designed to supplement Watanabe (2022),\nand built on the supplementary scripts associated with that paper.\nSee that paper for theoretical details.\n\n\n## Installation\n```\n# install.packages(\"devtools\")\ndevtools::install_github(\"watanabe-j/eigvaldisp\")\n```\nIf you have the packages `rmarkdown` and `knitr`, and have\n[`pandoc`](https://pandoc.org) installed on your machine (for `pandoc \u003c 2.11`, `pandoc-citeproc` is required as well), you can build a vignette by the option\n`build_vignettes = TRUE` in `install_github()` (recommended).\n\nThis package has the following dependencies:\n```\nImports:\n    stats,\n    hypergeo\nSuggests:\n    eigvaldispRcpp,\n    parallel,\n    testthat (\u003e= 3.0.0),\n    knitr,\n    rmarkdown\n```\n\nEarlier developmental versions imported `Rcpp`, but the relevant\nfunctionality has now been separated into an extension package,\n[`eigvaldispRcpp`](https://github.com/watanabe-j/eigvaldispRcpp),\nto minimize dependency of the main package.\nOne would not need that extension unless interested in calculating\nsampling variance of the relative eigenvalue variance of\nlarge correlation matrices *V*\u003csub\u003erel\u003c/sub\u003e(**R**)\n(*p* \u003e 100 or so).\n\n\n## Examples\n\nTo get some ideas, let's create a simple population covariance matrix\nwith the function `GenCov()`, which constructs a covariance/correlation\nmatrix with known eigenvalues/vectors, and then calculate\neigenvalue dispersion indices of this matrix with the function `VE()`:\n```\nset.seed(30)\n## Generate a population covariance matrix with known eigenvalues\nLambda \u003c- c(4, 2, 1, 1)\n(Sigma \u003c- GenCov(evalues = Lambda, evectors = \"random\"))\n#\u003e              [,1]         [,2]       [,3]       [,4]\n#\u003e [1,]  2.525707231 -0.002305745  0.4878674 -1.2925039\n#\u003e [2,] -0.002305745  1.893637883  0.2794045 -0.4629743\n#\u003e [3,]  0.487867373  0.279404464  1.2438233 -0.5590454\n#\u003e [4,] -1.292503917 -0.462974308 -0.5590454  2.3368316\neigen(Sigma)$values\n#\u003e [1] 4 2 1 1\n\n## Calculate eigenvalue dispersion indices of this matrix\nEDI_pop \u003c- VE(S = Sigma)\n\n## Eigenvalue variance (\"V(Sigma)\")\nEDI_pop$VE\n#\u003e [1] 1.5\n\n## Relative eigenvalue variance (\"Vrel(Sigma)\"):\nEDI_pop$VR\n#\u003e [1] 0.125\n```\n\nIt is trivial to calculate the population eigenvalue dispersion indices.\nThe problem is the presence of sampling bias (and error),\nwhich renders inferences from a sample rather difficult.\n\nTo see this, simulate a small multivariate normal sample from\nthe same population covariance matrix using the function `rmvn()`:\n```\n## Simulate a multivariate normal sample\nN \u003c- 20\nX \u003c- rmvn(N = N, Sigma = Sigma)\ncov(X)\n#\u003e            [,1]       [,2]       [,3]       [,4]\n#\u003e [1,]  2.8116163  0.5779609  0.9517708 -1.3106853\n#\u003e [2,]  0.5779609  2.6693532  0.2962871 -0.9844253\n#\u003e [3,]  0.9517708  0.2962871  1.2897573 -0.5258998\n#\u003e [4,] -1.3106853 -0.9844253 -0.5258998  2.2849262\n## Reasonable estimate of Sigma\n\n## Calculating eigenvalue dispersion indices from the sample\nEDI_sam \u003c- VE(X = X)\n## Same as VE(S = cov(X)) but usually faster\n\n## Sample eigenvalue variance (\"V(S)\")\nEDI_sam$VE\n#\u003e [1] 2.499072\n\n## Sample relative eigenvalue variance (\"Vrel(S)\")\nEDI_sam$VR\n#\u003e [1] 0.1625316\n```\n\nThese are typically larger than the population values,\nalthough there is always some random fluctuation. In other words,\nsample eigenvalue dispersion indices tend to overestimate\nthe population values in this case\n(although underestimation can happen when the population value is large).\n\nThe main functionality of this package is to calculate\nexpectation and variance (i.e., estimates of sampling bias and error)\nof eigenvalue dispersion indices from arbitrary\npopulation covariance/correlation matrices:\n```\n## Expectation of eigenvalue variance (\"E[V(S)]\")\n## The argument n is for the degree of freedom, hence N - 1 in this case\n(E_V_Sigma \u003c- Exv.VES(Sigma = Sigma, n = N - 1))\n#\u003e [1] 2.486842\n\n## Expected bias\nE_V_Sigma - EDI_pop$VE\n#\u003e [1] 0.9868421\n\n## Error (sampling variance) of eigenvalue variance (\"Var[V(S)]\")\nVar.VES(Sigma, N - 1)\n#\u003e [1] 3.126513\n\n## Same for relative eigenvalue variance (\"E[Vrel(S)]\", \"Var[Vrel(S)]\")\n(E_Vrel_Sigma \u003c- Exv.VRS(Sigma, N - 1))\n#\u003e [1] 0.18438\nE_Vrel_Sigma - EDI_pop$VR\n#\u003e [1] 0.05938\nVar.VRS(Sigma, N - 1)\n#\u003e [1] 0.007989498\n```\n\n\"Bias-corrected\" estimators are also implemented, although this is\nnot globally unbiased for the relative eigenvalue variance:\n```\n## Bias-corrected eigenvalue variance\nVESa(X = X)$VESa\n#\u003e [1] 1.290192\n\n## Its expectation (equals the population value)\nExv.VESa(Sigma, N - 1)\n#\u003e [1] 1.5\n\n## Its variance (smaller than that of the ordinary one)\nVar.VESa(Sigma, N - 1)\n#\u003e [1] 2.094455\n\n\n## Adjusted relative eigenvalue variance\nVRSa(X = X)$VRSa\n#\u003e [1] 0.09274259\n\n## Its expectation (underestimates the population value)\nExv.VRSa(Sigma, N - 1)\n#\u003e [1] 0.1164117\n\n## Its variance\nVar.VRSa(Sigma, N - 1)\n#\u003e [1] 0.009376563\n```\n\nThe same functionalities are also available for correlation matrices,\nbut via different functions (`Exv.VRR()`, `Var.VRR()`, `VRRa()`, etc.)\nsince their distributions are different.\n\nAlso involved in this package are:\n- Function for Monte Carlo simulation of eigenvalue dispersion indices\n- Cholesky factorization functions for singular covariance matrices\n- Calculation of exact/asymptotic moments of correlation coefficients\n\nThere may be better R implementations for some of the functionalities,\nbut this package is intended to be as much self-contained as possible.\n\nFor more detailed descriptions, use `vignette(\"eigvaldisp\")`.\n\n\n## Copyright notice\nThe function `GenCov()` in this package involves an algorithm originally\nadopted (with modifications) from the package `fungible` version 1.99\n(Waller, 2021), which is under GPL (\u003e= 2). See description of that function for details.\n\n\n## References\nWaller, N. G. (2021). fungible: psychometric functions from\nthe Waller Lab. R package version 1.99.\n[https://CRAN.R-project.org/package=fungible](https://CRAN.R-project.org/package=fungible).\n\nWatanabe, J. (2022). Statistics of eigenvalue dispersion indices: quantifying the magnitude of phenotypic integration. *Evolution*, **76**, 4\u0026ndash;28. doi:[10.1111/evo.14382](https://doi.org/10.1111/evo.14382).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwatanabe-j%2Feigvaldisp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwatanabe-j%2Feigvaldisp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwatanabe-j%2Feigvaldisp/lists"}