Merge pull request #201 from easystats/dev

dev

.Rbuildignore

@@ -1,4 +1,5 @@
 ^\.Rprofile$
+^\.github
 ^.*\.Rproj$
 ^\.Rproj\.user$
 ^\.travis.yml

.github/CONDUCT.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [INSERT EMAIL ADDRESS]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org

.github/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contribution Guidelines 
+
+<sup>easystats guidelines 0.1.0</sup>
+
+**All people are very much welcome to contribute to code, documentation, testing and suggestions.**
+
+This package aims at being beginner-friendly. Even if you're new to this open-source way of life, new to coding and github stuff, we encourage you to try submitting pull requests (PRs). 
+
+- **"I'd like to help, but I'm not good enough with programming yet"**
+
+It's alright, don't worry! You can always dig in the code, in the documentation or tests. There are always some typos to fix, some docs to improve, some details to add, some code lines to document, some tests to add... **Even the smaller PRs are appreciated**.
+
+- **"I'd like to help, but I don't know where to start"**
+
+You can look around the **issue section** to find some features / ideas / bugs to start working on. You can also open a new issue **just to say that you're there, interested in helping out**. We might have some ideas adapted to your skills.
+
+- **"I'm not sure if my suggestion or idea is worthwile"**
+
+Enough with the impostor syndrom! All suggestions and opinions are good, and even if it's just a thought or so, it's always good to receive feedback.
+
+- **"Why should I waste my time with this? Do I get any credit?"**
+
+Software contributions are getting more and more valued in the academic world, so it is a good time to collaborate with us! Authors of substantial contributions will be added within the **authors** list. We're also very keen on including them to eventual academic publications.
+
+
+**Anyway, starting is the most important! You will then enter a *whole new world, a new fantastic point of view*... So fork this repo, do some changes and submit them. We will then work together to make the best out of it :)**
+
+
+## Code
+
+- Please document and comment your code, so that the purpose of each step (or code line) is stated in a clear and understandable way.
+- Before submitting a change, please read the [**R style guide**](https://style.tidyverse.org/) to keep some consistency in code formatting.
+- Regarding the style guide, note this exception: we put readability and clarity before everything. Thus, we like underscores and full names (prefer `model_performance` over `modelperf` and `interpret_odds_logistic` over `intoddslog`).
+- Before you start to code, make sure you're on the `dev` branch (the most "advanced"). Then, you can create a new branch named by your feature (e.g., `feature_lightsaber`) and do your changes. Finally, submit your branch to be merged into the `dev` branch. Then, every now and then, the dev branch will merge into `master`, as a new package version.
+
+## Checks to do before submission
+
+- Make sure **documentation** (roxygen) is good
+- Make sure to add **tests** for the new functions
+- Run:
+
+  - `styler::style_pkg()`: Automatic style formatting
+  - `lintr::lint_package()`: Style checks
+  - `devtools::check()`: General checks
+
+
+
+## Useful Materials
+
+- [Understanding the GitHub flow](https://guides.github.com/introduction/flow/)
+
+

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,24 @@
+---
+name: Bug report
+about: Create a report to help us improve
+
+---
+
+**Describe the bug**
+A description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behaviour:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behaviour**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Specifiations (please complete the following information):**
+ - Package Version [e.g. 0.2.1]

.github/ISSUE_TEMPLATE/feature-idea.md

@@ -0,0 +1,11 @@
+---
+name: Feature idea
+about: Suggest an idea for this project
+
+---
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**How could we do it?**
+A description of actual ways of implementing a feature.

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,7 @@
+---
+name: Question
+about: You didn't understand something?
+
+---
+
+**Question and context**

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+# Description
+
+This PR aims at adding this feature...
+
+# Proposed Changes
+
+I changed the `foo` function so that ...

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: bayestestR
 Type: Package
 Title: Understand and Describe Bayesian Models and Posterior Distributions
-Version: 0.2.4
+Version: 0.2.5
 Authors@R: c(
     person("Dominique", 
         "Makowski", 
@@ -26,7 +26,11 @@ Authors@R: c(
 	person("Paul-Christian", 
 		"Bürkner", 
 		role = c("rev"), 
-		email = "[email protected]")
+		email = "[email protected]"),
+	person("Tristan", 
+		"Mahr", 
+		role = c("rev"), 
+		email = "[email protected]")
 	)
 Maintainer: Dominique Makowski <[email protected]>
 URL: https://github.com/easystats/bayestestR

NAMESPACE

@@ -101,6 +101,7 @@ S3method(plot,equivalence_test)
 S3method(plot,estimate_density)
 S3method(plot,eti)
 S3method(plot,hdi)
+S3method(plot,map_estimate)
 S3method(plot,p_direction)
 S3method(plot,point_estimate)
 S3method(plot,rope)
@@ -165,7 +166,6 @@ export(distribution_uniform)
 export(effective_sample)
 export(equivalence_test)
 export(estimate_density)
-export(estimate_probability)
 export(eti)
 export(hdi)
 export(map_estimate)
@@ -177,7 +177,6 @@ export(p_to_pd)
 export(pd)
 export(pd_to_p)
 export(point_estimate)
-export(probability_at)
 export(reshape_ci)
 export(rnorm_perfect)
 export(rope)

R/bayesfactor_parameters.R

@@ -274,7 +274,7 @@ bayesfactor_parameters.data.frame <- function(posterior, prior = NULL,
 
   class(bf_val) <- unique(c(
     "bayesfactor_parameters",
-    "see_bayesfactor_savagedickey",
+    "see_bayesfactor_parameters",
     class(bf_val)
   ))
 

R/estimate_density.R

@@ -60,10 +60,6 @@ estimate_density <- function(x, method = "kernel", precision = 2^10, extend = FA
   UseMethod("estimate_density")
 }
 
-#' @rdname estimate_density
-#' @export
-estimate_probability <- estimate_density
-
 
 
 #' @keywords internal
@@ -200,9 +196,9 @@ as.data.frame.density <- function(x, ...) {
 
 
 
-#' Probability of a Given Point
+#' Density Probability at a Given Value
 #'
-#' Compute the density of a given point of a distribution.
+#' Compute the density value at a given point of a distribution (i.e., the value of the \code{y} axis of a value \code{x} of a distribution).
 #'
 #' @param posterior Vector representing a posterior distribution.
 #' @param x The value of which to get the approximate probability.
@@ -220,8 +216,3 @@ density_at <- function(posterior, x, precision = 2^10, ...) {
   stats::approx(density$x, density$y, xout = x)$y
 }
 
-
-
-#' @rdname density_at
-#' @export
-probability_at <- density_at

R/map_estimate.R

@@ -63,7 +63,10 @@ map_estimate.numeric <- function(x, precision = 2^10, ...) {
   out <- hdp_x
   attr(out, "MAP_density") <- hdp_y
 
-  class(out) <- unique(c("map_estimate", class(out)))
+  attr(out, "data") <- x
+  attr(out, "centrality") <- "map"
+  class(out) <- unique(c("map_estimate", "see_point_estimate", class(out)))
+
   out
 }
 
@@ -86,6 +89,10 @@ map_estimate.numeric <- function(x, precision = 2^10, ...) {
   )
 
   attr(out, "MAP_density") <- sapply(l, attr, "MAP_density")
+  attr(out, "object_name") <- deparse(substitute(x), width.cutoff = 500)
+  attr(out, "centrality") <- "map"
+  class(out) <- unique(c("map_estimate", "see_point_estimate", class(out)))
+
   class(out) <- unique(c("map_estimate", class(out)))
   out
 }

R/p_map.R

@@ -1,6 +1,6 @@
 #' Bayesian p-value based on the density at the Maximum A Posteriori (MAP)
 #'
-#' Compute a Bayesian equivalent of the p-value, related to the odds that a parameter (described by its posterior distribution) has against the null hypothesis (\emph{h0}) using Mills' (2014, 2017) \emph{Objective Bayesian Hypothesis Testing} framework. It corresponds to the density value at 0 divided by the density at the Maximum A Posteriori (MAP).
+#' Compute a Bayesian equivalent of the \emph{p}-value, related to the odds that a parameter (described by its posterior distribution) has against the null hypothesis (\emph{h0}) using Mills' (2014, 2017) \emph{Objective Bayesian Hypothesis Testing} framework. It corresponds to the density value at 0 divided by the density at the Maximum A Posteriori (MAP).
 #'
 #'
 #' @param precision Number of points for density estimation. See the \code{n}-parameter in \link[=density]{density}.

R/p_rope.R

@@ -1,9 +1,9 @@
 #' ROPE-based p-value
 #'
-#' Compute the ROPE-based p-value, an exploratory index representing the maximum percentage of \link[=hdi]{HDI} that does not contain (positive values) or is entirely contained (negative values) in the negligible values space defined by the \link[=rope]{ROPE}. It differs from the ROPE percentage, \emph{i.e.}, from the proportion of a given CI in the ROPE, as it represents the maximum CI to reach a ROPE proportion of 0\% (positive values) or 100\% (negative values). A ROPE-based \emph{p} of 97\% means that there is a probability of .97 that a parameter (described by its posterior distribution) is outside the ROPE. On the contrary, a ROPE-based p of -97\% means that there is a probability of .97 that the parameter is inside the ROPE.
+#' The ROPE-based \emph{p}-value is an exploratory and non-validated index representing the maximum percentage of \link[=hdi]{HDI} that does not contain (or is entirely contained, in which case the value is prefixed with a negative sign), in the negligible values space defined by the \link[=rope]{ROPE}. It differs from the ROPE percentage, \emph{i.e.}, from the proportion of a given CI in the ROPE, as it represents the maximum CI values needed to reach a ROPE proportion of 0\% or 100\%. Whether the index reflects the ROPE reaching 0\% or 100\% is indicated through the sign: a negative sign is added to indicate that the probability corresponds to the probability of a not significant effect (a percentage in ROPE of 100\%). For instance, a ROPE-based \emph{p} of 97\% means that there is a probability of .97 that a parameter (described by its posterior distribution) is outside the ROPE. In other words, the 97\% HDI is the maximum HDI level for which the percentage in ROPE is 0\%. On the contrary, a ROPE-based p of -97\% indicates that there is a probability of .97 that the parameter is inside the ROPE (percentage in ROPE of 100\%). A value close to 0\% would indicate that the mode of the distribution falls perfectly at the edge of the ROPE, in which case the percentage of HDI needed to be on either side of the ROPE becomes infinitely small. Negative values do not refer to negative values \emph{per se}, simply indicating that the value corresponds to non-significance rather than significance.
 #'
 #'
-#' @param range ROPE's lower and higher bounds. Should be a list of two values (e.g., \code{c(-0.1, 0.1)}) or \code{"default"}. If \code{"default"}, the range is set to \code{c(0.1, 0.1)} if input is a vector and \code{x +- 0.1*SD(response)} if a Bayesian model is provided.
+#' @inheritParams rope
 #' @param precision The precision by which to explore the ROPE space (in percentage). Lower values increase the precision of the returned p value but can be quite computationaly costly.
 #'
 #' @inheritParams hdi

R/plot.R

@@ -25,6 +25,15 @@ plot.point_estimate <- function(x, ...) {
 }
 
 
+#' @export
+plot.map_estimate <- function(x, ...) {
+  if (!requireNamespace("see", quietly = TRUE)) {
+    stop("Package 'see' needed to plot point-estimates. Please install it by running `install.packages('see')`.")
+  }
+  NextMethod()
+}
+
+
 #' @export
 plot.rope <- function(x, ...) {
   if (!requireNamespace("see", quietly = TRUE)) {