{"id":32200654,"url":"https://github.com/tystan/codaredistlm","last_synced_at":"2025-10-22T03:53:40.129Z","repository":{"id":62173331,"uuid":"554543486","full_name":"tystan/codaredistlm","owner":"tystan","description":"Functions to analyse compositional data and produce confidence intervals for relative increases and decreases in the compositional components","archived":false,"fork":false,"pushed_at":"2023-01-25T06:26:12.000Z","size":154,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-22T03:53:34.767Z","etag":null,"topics":["coda","compositional-data-analysis","isometric-log-ratio","multiple-linear-regression","plotting","prediction"],"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/tystan.png","metadata":{"files":{"readme":"README.md","changelog":"change-notes.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-10-20T01:38:32.000Z","updated_at":"2024-10-19T06:26:27.000Z","dependencies_parsed_at":"2023-02-14T05:30:46.925Z","dependency_job_id":null,"html_url":"https://github.com/tystan/codaredistlm","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tystan/codaredistlm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tystan%2Fcodaredistlm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tystan%2Fcodaredistlm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tystan%2Fcodaredistlm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tystan%2Fcodaredistlm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tystan","download_url":"https://codeload.github.com/tystan/codaredistlm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tystan%2Fcodaredistlm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280376541,"owners_count":26320276,"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","status":"online","status_checked_at":"2025-10-22T02:00:06.515Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["coda","compositional-data-analysis","isometric-log-ratio","multiple-linear-regression","plotting","prediction"],"created_at":"2025-10-22T03:53:38.967Z","updated_at":"2025-10-22T03:53:40.125Z","avatar_url":"https://github.com/tystan.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n**Please note that this package (`codaredistlm`, Compositional Data Analysis [CoDA] redistribution linear model) is the new actively maintained package  previously known as [deltacomp](https://github.com/tystan/deltacomp).**\n\n# The `codaredistlm` package\n\n\nFunctions to analyse compositional data and produce predictions (with confidence intervals) for relative increases and decreases in the compositional parts.\n\n\n\n## 1. Background\n\nFor an outcome variable `Y`, *D* compositional parts (`x_1, ..., x_D`) and *C* covariates (`z_1, ..., z_C`); this package fits the compositional data analysis model (notation inexact):\n\n\n`Y = b_0 + b_1 ilr_1 + ... + b_{D-1} ilr_{D-1} + a_1 z_1 + ... + a_C z_C + e`\n\nwhere `ilr_i` are the *D-1* isometric log ratio variables derived from the *D* compositional parts (`x_1, ..., x_D`), `b_0, ...,  b_{D-1}, a_1, ..., a_C` are *D+C* parameters to be estimated and `e ~ N(0, sigma)` is the error. The package then makes predictions in alterations of the time-use variables (the linearly dependent set of compositional parts) based on this model. \n\n\nFor a starting point to learn about compositional data analysis please see [Aitchison (1982)](https://doi.org/10.1111/j.2517-6161.1982.tb01195.x) or [van den Boogaart and Tolosana-Delgado (2013)](https://link.springer.com/book/10.1007/978-3-642-36809-7). However the articles [Dumuid et al. (2017a)](https://doi.org/10.1177/0962280217710835) and [Dumuid et al. (2017b)](https://doi.org/10.1177/0962280217737805) may be more approachable introductions.\n\n\n## 2. Reallocation of time-use component options\n\nPlease note that the use of 'mean composition' means the geometric mean on the compositional simplex and *not* the arithmetic mean. If these words have little meaning to you, that is no problems as these differently calculated means likely do not differ much in your dataset. \n\n### 2.1. Option `comparisons = \"prop-realloc\"` \n\nInformation on outcome prediction with time-use exchange between one part and the remaining compositional parts proportionally (`comparisons = \"prop-realloc\"` option of the `predict_delta_comps()` function), please see [Dumuid et al. (2017a)](https://doi.org/10.1177/0962280217710835).\n\n### 2.1.1. Example\n\nSuppose you have three (predictor) parts in a day summing to 1 (e.g., a day) to predict an outcome variable. The three parts are `sedentary`, `sleep`  and `activity`. Let's assume the mean sampled composition is:\n\n* `sedentary = 0.5` (i.e., half a day)\n* `sleep = 0.3`  (i.e., 30% a day)\n* `activity = 0.2` (i.e., 20% a day)\n\nIf you wanted to predict the change in the outcome variable from the above mean composition with `delta = +0.05` (5% of the day) is added to `sedentary`, the option `comparisons = \"prop-realloc\"` reduces the remaining parts by the 5% proportionately based on their mean values, illustrated below:\n\n* `sedentary* = 0.5 + delta = 0.5 + 0.05 = 0.55`\n* `sleep* = 0.3 - delta * sleep / (sleep + activity) = 0.3 - 0.05 * 0.3 / (0.3 + 0.2) = 0.3 - 0.03 = 0.27`\n* `activity* = 0.2 - delta * activity / (sleep + activity) = 0.2 - 0.05 * 0.2 / (0.3 + 0.2) = 0.2 - 0.02 = 0.18`\n\nNoting that the new compsition: `sedentary* + sleep* + activity* = 0.55 + 0.27 + 0.18 = 1`.\n\nNote for the example above, the option `comparisons = \"prop-realloc\"` in `predict_delta_comps()` will actually automatically produce separate predictions for a `delta = +0.05` on each of the parts against the remaining parts. i.e., not only the `sedentary* = 0.5 + delta` scenario as illustrated above but also `sleep* = 0.3 + delta` and `activity* = 0.2 + delta` cases.\n\n### 2.2. Option `comparisons = \"one-v-one\"` \n\nFor information on outcome prediction with time-use exchange between two compositional parts (i.e., the `comparisons = \"one-v-one\"` option of the `predict_delta_comps()` function), please see\n[Dumuid et al. (2017b)](https://doi.org/10.1177/0962280217737805).\n\n### 2.2.1. Example\n\nSimilarly to the previous example, suppose you have three (predictor) parts in a day summing to 1 (i.e. a day) to predict an outcome variable. The three parts are `sedentary`, `sleep`  and `activity`. Let's assume the mean sampled composition is:\n\n* `sedentary = 0.5` (i.e., half a day)\n* `sleep = 0.3`  (i.e., 30% a day)\n* `activity = 0.2` (i.e., 20% a day)\n\nIf you wanted to predict the change in the outcome variable from the above mean composition with `delta = +0.05` (5% of the day), the option `comparisons = \"one-v-one\"` looks at all pairwise exchanges between the parts `(sedentary*, sleep*, activity*)`:\n\n* `(0.5 + 0.05, 0.3 - 0.05, 0.2       )`\n* `(0.5 + 0.05, 0.3       , 0.2 - 0.05)`\n* `(0.5       , 0.3 + 0.05, 0.2 - 0.05)`\n* `(0.5 - 0.05, 0.3 + 0.05, 0.2       )`\n* `(0.5 - 0.05, 0.3       , 0.2 + 0.05)`\n* `(0.5       , 0.3 - 0.05, 0.2 + 0.05)`\n\n\n\n## 3. Datasets in package\n\nTwo datasets are supplied with the package:\n\n* `fairclough` and \n* `fat_data`.\n\nThe `fairclough` dataset was kindly provided by the authors of [Fairclough et al. (2017)](https://doi.org/10.1186/s12966-017-0521-z). `fat_data` is a randomly generated test dataset that might roughly mimic a real dataset.\n\n## 4. Example usage\n\n```R\nlibrary(devtools) # see https://www.r-project.org/nosvn/pandoc/devtools.html\ndevtools::install_github('tystan/codaredistlm')\nlibrary(codaredistlm)\n### see help file to run example\n?predict_delta_comps\n\npredict_delta_comps(\n    dataf = fat_data,\n    y = \"fat\",\n    comps = c(\"sl\", \"sb\", \"lpa\", \"mvpa\"),\n    covars = c(\"sibs\", \"parents\", \"ed\"),\n    deltas = seq(-60, 60, by = 5) / (24 * 60),\n    comparisons = \"prop-realloc\",\n    alpha = 0.05\n)\n\n# OR\n\npredict_delta_comps(\n    dataf = fat_data,\n    y = \"fat\",\n    comps = c(\"sl\", \"sb\", \"lpa\", \"mvpa\"),\n    covars = c(\"sibs\", \"parents\", \"ed\"),\n    deltas = seq(-60, 60, by = 5) / (24 * 60),\n    comparisons = \"one-v-one\",\n    alpha = 0.05\n)\n\n```\n\n\n## 5. Output and plotting results\n\nOutput is a `data.frame` that can be turned into the plot below using the following code.\n\n```R\n\npred_df \u003c- \n    predict_delta_comps(\n        dataf = fairclough,\n        y = \"z_bmi\",\n        comps = c(\"sleep\", \"sed\", \"lpa\", \"mvpa\"),\n        covars = c(\"decimal_age\", \"sex\"),\n        # careful deltas greater than 25 min in magnitude induce negative compositions\n        # predict_delta_comps() will warn you about this :-)\n        deltas =  seq(-20, 20, by = 5) / (24 * 60), \n        comparisons = \"prop-realloc\", # or try \"one-v-one\"\n        alpha = 0.05\n    )\n\nplot_delta_comp(\n    pred_df, # provide the returned object from predict_delta_comps()\n    # x-axis can be converted from propotion of composition to meaningful units\n    comp_total = 24 * 60, # minutes available in the composition\n    units_lab = \"min\" # just a label for plotting\n)\n\n\n```\n\n\n![](https://github.com/tystan/codaredistlm/blob/master/inst/img/delta_comps2.png)\n\n\n### 5.1. Prediction for the mean composition\n\nThe function `predict_delta_comps()` now outputs the predicted outcome value (with `100 * (1 - alpha)`% confidence interval). This data is printed to the console but also can be extracted from the output of `predict_delta_comps()` as per the below code:\n\n```R\n\n# produces a 1 line data.frame that contains \n#    the (simplex/geometric) mean composition,\n#    the \"average\" covariates (the median of the factor variables in order of the levels are taken as default),\n#    the ilr coords of the (simplex/geometric) mean composition, and\n#    the predicted outcome value with 100*(1-alpha)% confidence interval\nattr(pred_df, \"mean_pred\")\n\n\n```\n\n\n## 6. Release notes\n\nSee [/change-notes.md](https://github.com/tystan/codaredistlm/blob/master/change-notes.md).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftystan%2Fcodaredistlm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftystan%2Fcodaredistlm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftystan%2Fcodaredistlm/lists"}