Package **EmaCalc** implements probabilistic Bayesian analysis
of *Ecological Momentary Assessment (EMA)* data.
The EMA methodology can be used to evaluate
the effect of any kind of psycho-socio-medical intervention,
for example, the subjective performance of hearing aids,
in the everyday life of the user or client,
## EMA Experiments
In an EMA study, each participant is requested to respond to a questionnaire
during normal everyday life, typically several times per day.
Some questions may address the current real-life *Situation*,
i.e., the physical environment and the user's activity and intentions.
The participant may also be asked to rate any
perceptual *Attribute* of interest in the study,
for example,
the ease of speech understanding in the current situation.
Thus, EMA data usually include both *nominal* and *ordinal* results.
Typically, many records are collected from each participant,
but the number of records may vary a lot among respondents.
This causes some interesting challenges for the statistical
analysis (Oleson et al., 2021).
The present analysis model estimates *Attribute* values
numerically on an objective *interval scale*,
given the Situation,
although the raw input data are *subjective*
and indicate only *ordinal* judgments for each Attribute,
and *nominal* categories for the Situations.
This package does *not* include functions to handle the data collection;
it can only use existing files with data recorded earlier.
The package can analyze data from simple or rather complex experimental designs,
including the following features:
1. The complete EMA study may include one or more test **Phases**,
for example, *before* and *after* some kind of intervention.
2. Each EMA record may characterize the current situation
in one or more pre-defined **Situation Dimensions**.
For example, one dimension may be specified
by the *Common Sound Scenarios (CoSS)* (Wolters et al., 2016),
which is a list of broad categories of situational intentions and tasks.
Other dimensions may specify the *Importance* of the situation,
and/or the *Hearing-Aid Program* currently used.
3. Each EMA record may also include discrete *ratings* for
one or more perceptual **Attributes**.
For example, one Attribute may be *Speech Understanding*,
with ordinal grades *Bad*, *Fair*, *Good*, *Perfect*.
Another attribute may be *Comfort*, with grades *Bad*, *Good*.
4. For each *Situation Dimension*, a list of allowed **Situation Categories** must be pre-defined.
An assessment event is defined by a combination
of exactly one selected Category from each Dimension.
5. For each perceptual *Attribute*, a list of discrete ordinal **Attribute Grades**
must be pre-defined.
Ordinal scales may be unique for each attribute,
or shared by more than one attribute.
6. An EMA study may involve one or more distinct **Populations**,
from which separate groups of participants have been recruited.
7. Populations are distinguished by a combination of
categories from one or more **Group Dimensions**.
For example, one dimension may be *Age*,
with categories *Young*, *Middle*, or *Old*.
Another dimension may be, e.g.,*Gender*,
with categories *Female*, *Male*, or *Unknown*.
8. The analysis model *does not require* anything about
the number of participants from each population,
or the number of assessments by each participant.
Of course, the reliability is improved
if there are many participants from each population,
each reporting a large number of EMA records.
## EMA Data Analysis
The analysis uses the recorded data to
learn a probabilistic model,
representing the statistically most relevant aspects of the data.
The analysis includes a regression model to show how the Attribute values
vary across Situations.
1. The analysis results will show predictive **Situation Probabilities**
for each population, credible differences between situation probabilities within each
population, and credible differences between populations.
2. The analysis results will also show perceptual **Attribute Values**
for each population, credible differences between Attribute Values
in separate situations,
and credible Attribute Differences between populations.
3. **Differences between populations** can be shown as main effects
in only one or a few of the pre-defined Group Dimensions,
or as complete interaction effects of categories in all Group Dimensions.
The Bayesian analysis automatically estimates the *statistical credibility*
of all analysis results, given the amount of collected data.
The Bayesian model is hierarchical.
The package can estimate results for
1. an unseen *random individual* in the population from which the participants were recruited,
2. the *population mean*,
3. each individual *participant*.
The first of these probability measures may be most important
in a study designed, e.g., by a hearing-aid manufacturer
to predict the future marketing success of some new hearing aid feature.
The second probability measure is most closely related
to the statistical significance as estimated by conventional hypothesis tests.
The third measure might be most important
in a clinical study to quantify the benefit of an intervention for individual clients.
The package can also quantify
individual rating differences by the
*Non-overlap of All Pairs (NAP)* effect measure
(Parker & Vannest, 2009),
including approximate confidence intervals calculated by
the *"MW-N" method* recommended by Feng et al. (2017).
## Package Documentation
General information and version history is given in the package doc-string that may be accessed by commands
`import EmaCalc`, `help(EmaCalc)`
in an interactive Python environment.
Input EMA data can be accessed from files in several
of the formats that package Pandas can handle, e.g., .csv, .xlsx.
Specific information about the organization of input data files
is presented in the doc-string of module ema_data,
accessible by commands
`import EmaCalc.ema_data`, `help(EmaCalc.ema_data)`.
After running an analysis, the logging output briefly explains
the analysis results presented in figures and tables.
Figures can be saved in any file format
allowed by Matplotlib.
Result tables can be saved in many of the
file formats that Pandas can handle,
e.g., .csv, .txt, .tex, as defined in module `ema_file`.
Thus, the results can easily be imported to a word-processing document
or to other statistical packages.
## Usage
1. Install the most recent package version:
`python3 -m pip install --upgrade EmaCalc`
2. For an introduction to the analysis results and the input data format,
you may want to study and run the included simulation script: `python3 run_sim.py`.
3. Copy the template script `run_ema.py`, rename it, and
edit the copy as suggested in the template, to specify
- your experimental layout,
- the top input data directory,
- a directory where all output result files will be stored.
4. Run your edited script: `python3 run_my_ema.py`
5. In the planning phase, complete analysis results
may also be calculated for synthetic data
generated from simulated experiments.
Simulated experiments allow the same design variants as real experiments.
Copy the template script `run_sim.py`, rename it,
edit the copy, and run your own EMA simulation.
## Requirements
This package requires Python 3.9 or newer,
with recent versions of Numpy, Scipy, and Matplotlib,
as well as a support package samppy.
Package Pandas is used to handle input data and result tables
and requires openpyxl to access Excel (.xlsx) files.
The pip installer will check and install these packages if needed.
Pandas can also access input files in other formats,
but may then need other support packages that must be installed manually.
## New in version 1.1
Flexible user control of result display styles.
Population differences can be shown in one and/or several of the predefined
Group Dimensions, as selected by the user.
## New in version 1.1.2
Clarified names and headings of table files with situation differences.
## References
A. Leijon, P. von Gablenz, I. Holube, J. Taghia, and K. Smeds (2023).
Bayesian analysis of ecological momentary assessment (EMA) data
collected in adults before and after hearing rehabilitation.
*Frontiers in Digital Health*, 5(1100705).
[download](https://www.frontiersin.org/articles/10.3389/fdgth.2023.1100705/full)
A. Leijon et al. (2023).
Bayesian Analysis of Ecological Momentary Assessment (EMA) Data.
*Documentation: Theory, Code usage, Validation, and Computational Details.*
Contact the author for a copy.
D. Feng, G. Cortese, and R. Baumgartner (2017).
A comparison of confidence/credible interval methods for the area under the ROC curve
for continuous diagnostic tests with small sample size.
*Statistical Methods in Medical Research*, 26(6):2603–2621.
[download](https://journals.sagepub.com/doi/10.1177/0962280215602040)
J. J. Oleson, M. A. Jones, E. J. Jorgensen, and Y.-H. Wu (2021).
Statistical considerations for analyzing ecological momentary assessment data.
*J Sp Lang Hear Res*, ePub:1–17.
[download](https://pubs.asha.org/doi/10.1044/2021_JSLHR-21-00081)
R. I. Parker and K. Vannest (2009).
An improved effect size for single-case research: Nonoverlap of all pairs.
*Behavior Therapy*, 40(4):357–367.
[download](https://www.sciencedirect.com/science/article/pii/S0005789408000816?via%3Dihub)
K. Smeds, F. Wolters, J. Larsson, P. Herrlin, and M. Dahlquist (2018).
Ecological momentary assessments for evaluation of hearing-aid preference.
*J Acoust Soc Amer* 143(3):1742–1742.
[download](https://asa.scitation.org/doi/10.1121/1.5035685)
F. Wolters, K. Smeds, E. Schmidt, and C. Norup (2016).
Common sound scenarios: A context-driven categorization of everyday sound environments
for application in hearing-device research.
*J Amer Acad Audiol*, 27(7):527–540.
[download](https://www.thieme-connect.de/products/ejournals/abstract/10.3766/jaaa.15105)
Raw data
{
"_id": null,
"home_page": null,
"name": "EmaCalc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "Momentary Assessment, Nominal Categories, Ordinal Ratings, Bayesian",
"author": "Arne Leijon",
"author_email": "leijon@kth.se",
"download_url": "https://files.pythonhosted.org/packages/32/01/857225b5184b14db6a0b3eae0d213ff083414b045657a09bf7b862323e3a/emacalc-1.1.2.tar.gz",
"platform": null,
"description": "Package **EmaCalc** implements probabilistic Bayesian analysis\nof *Ecological Momentary Assessment (EMA)* data. \nThe EMA methodology can be used to evaluate \nthe effect of any kind of psycho-socio-medical intervention,\nfor example, the subjective performance of hearing aids,\nin the everyday life of the user or client, \n\n## EMA Experiments\nIn an EMA study, each participant is requested to respond to a questionnaire\nduring normal everyday life, typically several times per day. \nSome questions may address the current real-life *Situation*,\ni.e., the physical environment and the user's activity and intentions.\nThe participant may also be asked to rate any \nperceptual *Attribute* of interest in the study,\nfor example, \nthe ease of speech understanding in the current situation.\n\nThus, EMA data usually include both *nominal* and *ordinal* results.\nTypically, many records are collected from each participant, \nbut the number of records may vary a lot among respondents.\n\nThis causes some interesting challenges for the statistical\nanalysis (Oleson et al., 2021).\nThe present analysis model estimates *Attribute* values \nnumerically on an objective *interval scale*,\ngiven the Situation,\nalthough the raw input data are *subjective*\nand indicate only *ordinal* judgments for each Attribute,\nand *nominal* categories for the Situations. \n\nThis package does *not* include functions to handle the data collection;\nit can only use existing files with data recorded earlier.\nThe package can analyze data from simple or rather complex experimental designs,\nincluding the following features:\n\n\n1. The complete EMA study may include one or more test **Phases**,\nfor example, *before* and *after* some kind of intervention.\n\n2. Each EMA record may characterize the current situation\nin one or more pre-defined **Situation Dimensions**. \nFor example, one dimension may be specified\nby the *Common Sound Scenarios (CoSS)* (Wolters et al., 2016),\nwhich is a list of broad categories of situational intentions and tasks. \nOther dimensions may specify the *Importance* of the situation,\nand/or the *Hearing-Aid Program* currently used.\n \n3. Each EMA record may also include discrete *ratings* for \none or more perceptual **Attributes**. \nFor example, one Attribute may be *Speech Understanding*, \nwith ordinal grades *Bad*, *Fair*, *Good*, *Perfect*. \nAnother attribute may be *Comfort*, with grades *Bad*, *Good*.\n\n4. For each *Situation Dimension*, a list of allowed **Situation Categories** must be pre-defined. \nAn assessment event is defined by a combination \nof exactly one selected Category from each Dimension.\n\n5. For each perceptual *Attribute*, a list of discrete ordinal **Attribute Grades**\nmust be pre-defined. \nOrdinal scales may be unique for each attribute, \nor shared by more than one attribute. \n \n6. An EMA study may involve one or more distinct **Populations**,\nfrom which separate groups of participants have been recruited.\n\n7. Populations are distinguished by a combination of \ncategories from one or more **Group Dimensions**.\nFor example, one dimension may be *Age*,\nwith categories *Young*, *Middle*, or *Old*.\nAnother dimension may be, e.g.,*Gender*, \nwith categories *Female*, *Male*, or *Unknown*.\n\n8. The analysis model *does not require* anything about \nthe number of participants from each population,\nor the number of assessments by each participant.\nOf course, the reliability is improved\nif there are many participants from each population, \neach reporting a large number of EMA records.\n\n## EMA Data Analysis\nThe analysis uses the recorded data to\nlearn a probabilistic model,\nrepresenting the statistically most relevant aspects of the data.\nThe analysis includes a regression model to show how the Attribute values \nvary across Situations. \n\n1. The analysis results will show predictive **Situation Probabilities** \n for each population, credible differences between situation probabilities within each \n population, and credible differences between populations.\n\n2. The analysis results will also show perceptual **Attribute Values** \nfor each population, credible differences between Attribute Values\nin separate situations, \nand credible Attribute Differences between populations.\n3. **Differences between populations** can be shown as main effects \nin only one or a few of the pre-defined Group Dimensions,\nor as complete interaction effects of categories in all Group Dimensions.\n\n\nThe Bayesian analysis automatically estimates the *statistical credibility*\nof all analysis results, given the amount of collected data.\nThe Bayesian model is hierarchical. \nThe package can estimate results for\n\n1. an unseen *random individual* in the population from which the participants were recruited,\n2. the *population mean*,\n3. each individual *participant*.\n\nThe first of these probability measures may be most important \nin a study designed, e.g., by a hearing-aid manufacturer \nto predict the future marketing success of some new hearing aid feature. \nThe second probability measure is most closely related \nto the statistical significance as estimated by conventional hypothesis tests. \nThe third measure might be most important \nin a clinical study to quantify the benefit of an intervention for individual clients.\n\nThe package can also quantify \nindividual rating differences by the \n*Non-overlap of All Pairs (NAP)* effect measure\n(Parker & Vannest, 2009), \nincluding approximate confidence intervals calculated by\nthe *\"MW-N\" method* recommended by Feng et al. (2017).\n\n## Package Documentation\nGeneral information and version history is given in the package doc-string that may be accessed by commands\n`import EmaCalc`, `help(EmaCalc)` \nin an interactive Python environment.\n\nInput EMA data can be accessed from files in several \nof the formats that package Pandas can handle, e.g., .csv, .xlsx.\nSpecific information about the organization of input data files\nis presented in the doc-string of module ema_data, \naccessible by commands\n`import EmaCalc.ema_data`, `help(EmaCalc.ema_data)`.\n\nAfter running an analysis, the logging output briefly explains\nthe analysis results presented in figures and tables.\nFigures can be saved in any file format \nallowed by Matplotlib.\nResult tables can be saved in many of the \nfile formats that Pandas can handle,\ne.g., .csv, .txt, .tex, as defined in module `ema_file`.\nThus, the results can easily be imported to a word-processing document \nor to other statistical packages.\n\n## Usage\n\n1. Install the most recent package version:\n `python3 -m pip install --upgrade EmaCalc`\n\n2. For an introduction to the analysis results and the input data format, \nyou may want to study and run the included simulation script: `python3 run_sim.py`.\n\n3. Copy the template script `run_ema.py`, rename it, and\nedit the copy as suggested in the template, to specify\n - your experimental layout,\n - the top input data directory,\n - a directory where all output result files will be stored.\n\n4. Run your edited script: `python3 run_my_ema.py`\n\n5. In the planning phase, complete analysis results \nmay also be calculated for synthetic data \ngenerated from simulated experiments. \nSimulated experiments allow the same design variants as real experiments.\nCopy the template script `run_sim.py`, rename it,\nedit the copy, and run your own EMA simulation.\n\n## Requirements\nThis package requires Python 3.9 or newer,\nwith recent versions of Numpy, Scipy, and Matplotlib,\nas well as a support package samppy. \nPackage Pandas is used to handle input data and result tables \nand requires openpyxl to access Excel (.xlsx) files.\nThe pip installer will check and install these packages if needed.\n\nPandas can also access input files in other formats, \nbut may then need other support packages that must be installed manually.\n\n## New in version 1.1\nFlexible user control of result display styles.\n\nPopulation differences can be shown in one and/or several of the predefined \nGroup Dimensions, as selected by the user.\n\n## New in version 1.1.2\nClarified names and headings of table files with situation differences.\n\n\n## References\n\nA. Leijon, P. von Gablenz, I. Holube, J. Taghia, and K. Smeds (2023).\nBayesian analysis of ecological momentary assessment (EMA) data\ncollected in adults before and after hearing rehabilitation. \n*Frontiers in Digital Health*, 5(1100705).\n[download](https://www.frontiersin.org/articles/10.3389/fdgth.2023.1100705/full)\n\nA. Leijon et al. (2023).\nBayesian Analysis of Ecological Momentary Assessment (EMA) Data. \n*Documentation: Theory, Code usage, Validation, and Computational Details.* \nContact the author for a copy.\n\nD. Feng, G. Cortese, and R. Baumgartner (2017).\nA comparison of confidence/credible interval methods for the area under the ROC curve\nfor continuous diagnostic tests with small sample size.\n*Statistical Methods in Medical Research*, 26(6):2603\u20132621.\n[download](https://journals.sagepub.com/doi/10.1177/0962280215602040)\n\nJ. J. Oleson, M. A. Jones, E. J. Jorgensen, and Y.-H. Wu (2021).\nStatistical considerations for analyzing ecological momentary assessment data. \n*J Sp Lang Hear Res*, ePub:1\u201317. \n[download](https://pubs.asha.org/doi/10.1044/2021_JSLHR-21-00081)\n\nR. I. Parker and K. Vannest (2009).\nAn improved effect size for single-case research: Nonoverlap of all pairs.\n*Behavior Therapy*, 40(4):357\u2013367. \n[download](https://www.sciencedirect.com/science/article/pii/S0005789408000816?via%3Dihub)\n\nK. Smeds, F. Wolters, J. Larsson, P. Herrlin, and M. Dahlquist (2018).\nEcological momentary assessments for evaluation of hearing-aid preference.\n*J Acoust Soc Amer* 143(3):1742\u20131742.\n[download](https://asa.scitation.org/doi/10.1121/1.5035685)\n\nF. Wolters, K. Smeds, E. Schmidt, and C. Norup (2016).\nCommon sound scenarios: A context-driven categorization of everyday sound environments\nfor application in hearing-device research.\n*J Amer Acad Audiol*, 27(7):527\u2013540. \n[download](https://www.thieme-connect.de/products/ejournals/abstract/10.3766/jaaa.15105)\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Statistical Analysis of Ecological Momentary Assessment (EMA) Data",
"version": "1.1.2",
"project_urls": null,
"split_keywords": [
"momentary assessment",
" nominal categories",
" ordinal ratings",
" bayesian"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a4b1a274fd6210ebca9490a8b3bca507eb55b67a83cd0610c48448279cb084ff",
"md5": "433a7ca31436794bbaf6d9782fe2395e",
"sha256": "1c94dae1fa9c80d72155c152f62d38ee648566e979be49ee2d6f0595bc05305b"
},
"downloads": -1,
"filename": "EmaCalc-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "433a7ca31436794bbaf6d9782fe2395e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 124049,
"upload_time": "2024-07-04T16:11:18",
"upload_time_iso_8601": "2024-07-04T16:11:18.211901Z",
"url": "https://files.pythonhosted.org/packages/a4/b1/a274fd6210ebca9490a8b3bca507eb55b67a83cd0610c48448279cb084ff/EmaCalc-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3201857225b5184b14db6a0b3eae0d213ff083414b045657a09bf7b862323e3a",
"md5": "cb1d9fb2beef4651b1c55b8d6852d507",
"sha256": "74ba7a9f940276139c21b04f13eeab5878bb209fbcb3a55c14996ec7dec84c84"
},
"downloads": -1,
"filename": "emacalc-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "cb1d9fb2beef4651b1c55b8d6852d507",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 114702,
"upload_time": "2024-07-04T16:11:20",
"upload_time_iso_8601": "2024-07-04T16:11:20.190988Z",
"url": "https://files.pythonhosted.org/packages/32/01/857225b5184b14db6a0b3eae0d213ff083414b045657a09bf7b862323e3a/emacalc-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-04 16:11:20",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "emacalc"
}
JSON