{"id":26199253,"url":"https://github.com/michael-franke/faintr","last_synced_at":"2025-03-12T02:57:56.635Z","repository":{"id":39270092,"uuid":"446838129","full_name":"michael-franke/faintr","owner":"michael-franke","description":"R package 'faintr' for interpretation of BRMS model fits for data from factorial design experiment","archived":false,"fork":false,"pushed_at":"2023-04-12T07:55:59.000Z","size":10869,"stargazers_count":1,"open_issues_count":7,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-03-19T03:32:52.970Z","etag":null,"topics":["bayesian","brms","contrast-coding","factorial-design","r-package","regression","rstats","stan"],"latest_commit_sha":null,"homepage":"https://michael-franke.github.io/faintr/index.html","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/michael-franke.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-01-11T13:45:21.000Z","updated_at":"2024-03-19T03:32:52.971Z","dependencies_parsed_at":"2023-02-09T16:46:16.464Z","dependency_job_id":null,"html_url":"https://github.com/michael-franke/faintr","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/michael-franke%2Ffaintr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michael-franke%2Ffaintr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michael-franke%2Ffaintr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michael-franke%2Ffaintr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/michael-franke","download_url":"https://codeload.github.com/michael-franke/faintr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243147137,"owners_count":20243746,"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":["bayesian","brms","contrast-coding","factorial-design","r-package","regression","rstats","stan"],"created_at":"2025-03-12T02:57:55.929Z","updated_at":"2025-03-12T02:57:56.629Z","avatar_url":"https://github.com/michael-franke.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r setup, include = FALSE}\nknitr::opts_chunk$set(\n  echo = TRUE, \n  warning = FALSE,\n  message = FALSE, \n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n\nlibrary(faintr)\nlibrary(brms)\nlibrary(posterior)\nlibrary(dplyr)\nlibrary(tidyr)\nlibrary(ggplot2)\nlibrary(aida)\n\ntheme_set(theme_bw() + theme(plot.background = element_blank()))\n\ncustom_palette \u003c- c(\"#009E73\", \"#B22222\", \"#0072B2\", \"#D55E00\")\n\nscale_colour_discrete \u003c- function(...) {\n  scale_colour_manual(..., values = custom_palette)\n}\nscale_fill_discrete \u003c- function(...) {\n   scale_fill_manual(..., values = custom_palette)\n}\n```\n\n# faintr \u003cimg align=\"right\" src=\"man/figures/faintr-logo.png\" alt=\"logo\" width=160\u003e \n\n\u003c!-- badges: start --\u003e\n[![R-CMD-check](https://github.com/michael-franke/faintr/workflows/R-CMD-check/badge.svg)](https://github.com/michael-franke/faintr/actions)\n[![Codecov test coverage](https://codecov.io/gh/michael-franke/faintr/branch/main/graph/badge.svg)](https://app.codecov.io/gh/michael-franke/faintr?branch=main)\n\u003c!-- badges: end --\u003e\n\n## Overview\n\nThe **faintr** (FActorINTerpreteR) package provides convenience functions for \ninterpreting [**brms**](https://paul-buerkner.github.io/brms/) model fits for data \nfrom factorial designs. It allows for the extraction and comparison of posterior \ndraws for a given design cell, irrespective of the encoding scheme used in the model.\n\nCurrently, **faintr** provides the following functions:\n\n* `get_cell_definitions` returns information on the predictor variables and how \nthey are encoded in the model.\n* `extract_cell_draws` returns posterior draws and additional metadata\nfor all design cells.\n* `filter_cell_draws` returns posterior draws and additional metadata\nfor one subset of design cells.\n* `compare_groups` returns summary statistics of comparing two subsets of design cells.\n\n## Installation\n\nYou can install the development version from GitHub with:\n\n``` r\n# install.packages(\"devtools\")\ndevtools::install_github(\"michael-franke/faintr\")\n```\n\n## Examples\n\nIn this section, we shortly introduce how to use the package. For a more detailed \noverview, please refer to the [vignette](https://michael-franke.github.io/faintr/articles/faintr_basics.html).\n\nWe will use a preprocessed version of the mouse-tracking data set from the [**aida**](https://github.com/michael-franke/aida-package) package:\n\n```{r data-import, echo=FALSE}\ndata \u003c- aida::data_MT\n\ndata \u003c- data %\u003e% \n  mutate(\n    prototype_label = case_when(\n      prototype_label %in% c('curved', 'straight') ~ prototype_label,\n      TRUE ~ 'CoM'\n      ),\n    prototype_label = factor(prototype_label,\n                             levels = c('straight', 'curved', 'CoM')))\n```\n\n```{r data}\ndata %\u003e% \n  select(RT, group, condition, prototype_label) %\u003e%\n  head()\n```\n\nThe variables relevant for us are:\n\n* `RT`: Reaction time in milliseconds\n* `group`: Whether a category is selected by click vs touch\n* `condition`: Whether the animal is a typical vs atypical representative of its category\n* `prototype_label`: The type of prototypical movement strategy (straight vs curved vs CoM)\n\nBelow, we regress the log-transformed reaction times as a function of factors \n`group`, `condition`, `prototype_label`, and their three-way interaction using a \nlinear regression model fitted with [**brms**](https://paul-buerkner.github.io/brms/):\n\n```{r model-fitting, results='hide'}\nfit \u003c- brms::brm(formula = log(RT) ~ group * condition * prototype_label,\n                 data = data,\n                 seed = 123\n                 )\n```\n\nTo obtain information on the factors and the coding scheme used in the model, \nwe can use `get_cell_definitions`:\n\n```{r cell-defs}\nget_cell_definitions(fit)\n```\n\nThe output shows that factors `group`, `condition` and `prototype_label` are\ndummy-coded, with `click`, `Atypical`, and `straight` being the reference levels, respectively.\n\nTo extract posterior draws for all design cells, we can use `extract_cell_draws`:\n\n```{r extract-cell-draws}\nextract_cell_draws(fit)\n```\n\nWith `filter_cell_draws` we can obtain posterior draws for a specific design cell.\nFor instance, draws for typical exemplars in click trials, averaged over factor `prototype_label`,\ncan be extracted like so:\n\n```{r filter-cell-draws}\nfilter_cell_draws(fit, condition == \"Typical\" \u0026 group == \"click\")\n```\n\nParameter `colname` allows changing the default column name in the output, which\nfacilitates post-processing of cell draws, e.g., for plotting or summary statistics.\nHere, we extract the draws for each level of `prototype_label` (averaged over `group` \nand `condition`) and visualize the results:\n\n```{r plot, out.width=\"70%\"}\ndraws_straight \u003c- filter_cell_draws(fit, prototype_label == \"straight\", colname = \"straight\")\ndraws_curved \u003c- filter_cell_draws(fit, prototype_label == \"curved\", colname = \"curved\")\ndraws_CoM \u003c- filter_cell_draws(fit, prototype_label == \"CoM\", colname = \"CoM\")\n\ndraws_prototype \u003c- posterior::bind_draws(draws_straight, draws_curved, draws_CoM) %\u003e%\n  pivot_longer(cols = posterior::variables(.), names_to = \"prototype\", values_to = \"value\")\n\ndraws_prototype %\u003e%\n  ggplot(aes(x = value, color = prototype, fill = prototype)) +\n  geom_density(alpha = 0.4)\n```\n\nFinally, we can compare two subsets of design cells with `compare_groups`. Here,\nwe compare the estimates for atypical exemplars in click trials against typical \nexemplars in click trials (averaged over the three prototypical movement strategies):\n\n```{r group-comp}\ncompare_groups(fit,\n               higher = condition == \"Atypical\" \u0026 group == \"click\",\n               lower = condition == \"Typical\" \u0026 group == \"click\"\n               )\n```\n\nIf one of two group specifications is left out, we compare against the grand mean:\n\n```{r group-comp-grand-mean}\ncompare_groups(fit,\n               higher = group == \"click\"\n               )\n```\n\nIf the Boolean flag `include_bf` is set to `TRUE` (default is `FALSE`), Bayes Factors \nfor the inequality (higher \u003e lower) are approximated in comparison to the \"negated hypothesis\" \n(lower \u003c= higher). However, this requires specifying proper priors for all parameters:\n\n```{r model-fitting-with-priors, results='hide'}\nfit_with_priors \u003c- brms::brm(formula = log(RT) ~ group * condition * prototype_label,\n                             prior = prior(student_t(1, 0, 3), class = \"b\"),\n                             data = data,\n                             seed = 123\n                             )\n```\n\n```{r group-comp-with-bf}\ncompare_groups(fit_with_priors,\n               higher = prototype_label != \"straight\",\n               lower = prototype_label == \"straight\",\n               include_bf = TRUE\n               )\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichael-franke%2Ffaintr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmichael-franke%2Ffaintr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichael-franke%2Ffaintr/lists"}