documentation

inst/doc/fbadstats.R

@@ -0,0 +1,35 @@
+## ----set-options, echo=FALSE, cache=FALSE-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+## save current width option, set to a large value, then resets back at end of code
+curwid <- getOption('width')
+options(width = 750)
+
+## ---- message=FALSE---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+## load the package
+library(FBadstats)
+## now call the function and provide parameters as desired
+fbadGstats(filerd = "example_PerfClk_AgeGender.csv", grphout = "NO", tblout = "BOTH")
+
+## ----fig.width = 10, fig.height = 4.5, fig.align = 'center'-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+fbadGstats(filerd = "example_PerfClk_AgeGender.csv", grphout = "YES", tblout = "BEST")
+
+## ---- eval = FALSE----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+#  NA
+
+## ---- eval = FALSE----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+#  fbadGstats()
+
+## ---- eval = FALSE----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+#  fbadGstats(choosedir  = "YES")
+
+## ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+fbadGstats(filerd = "example_DMA.csv", grphout = "NO", tblout = "WORST")
+
+## ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+fbadGstats(filerd = "example_DMA.csv", grphout = "NO", tblout = "WORST", spentlim = 5)
+
+## ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+fbadGstats(filerd = "example_DMA.csv", grphout = "NO", tblout = "WORST", sumvar = "Regist", prtrow = 15, minevent = 2)
+
+## ----echo=FALSE, cache=FALSE---------------------------------------------
+options(width = curwid)
+

inst/doc/fbadstats.Rmd

@@ -0,0 +1,72 @@
+---
+title: "Statistics for the worst and performing breakdown groups across Facebook ads"
+author: "Rick Pack"
+date: "`r Sys.Date()`"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{fbadGstats examples}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+```{r set-options, echo=FALSE, cache=FALSE}
+## save current width option, set to a large value, then resets back at end of code
+curwid <- getOption('width')
+options(width = 750)
+```
+
+The `fbadGstats` function aggregates across all of the Facebook (FB) ads performance data one provides from FB Ads Manager and indicates the best and worst performers per subgroup / breakdown group. *Disclaimer: This function and the entire `FBadstats` package are not supported or endorsed by Facebook, Inc. Only the user is responsible for its use.*
+
+## How to use `fbadGstats`
+
+We will first use the included **example_PerfClk_AgeGender** CSV file that represents exported data from ads dedicated to acquiring "Leads" (email addresses for potential customers AKA "an email funnel").
+
+The "PerfClk" in the name indicates that the "Performance and Clicks" view was used in Ads Manager at the time of the export, which is the best view to first try - others may fail. I will add to the error messages over time so one better understands why a view failed, and a view may succeed as the function evolves. The "AgeGender" in the filename expresses that the selected breakdown was a *combination* of age and gender.
+
+### Show only the table output (not a graph and its complementing table):
+Setting the `tblout` parameter to BOTH causes the best and worst performers to appear in the table
+**Note:** The filerd parameter, if used, must have the full path to a CSV file with slashes, not backslashes (e.g., `filerd` = *'c:/users/Users/RickPack/Documents/R/LeadData.csv'*).
+    Example files included with the `FBadstats` package are exceptions.
+```{r, message=FALSE}
+## load the package
+library(FBadstats)
+## now call the function and provide parameters as desired
+fbadGstats(filerd = "example_PerfClk_AgeGender.csv", grphout = "NO", tblout = "BOTH")
+```
+### Show only the best breakdown groups in the table:
+**Note:** `fbadGstats` graphs *always* show only the best breakdown groups.
+```{r fig.width = 10, fig.height = 4.5, fig.align = 'center'}
+fbadGstats(filerd = "example_PerfClk_AgeGender.csv", grphout = "YES", tblout = "BEST")
+```
+```{r, eval = FALSE}
+```
+### Choose your own CSV file
+[Windows-Only] Running the function without a `filerd` parameter will prompt you with a window in which you choose your CSV file.
+This would present such a window and use all of the default fbadGstats options to generate the output.
+```{r, eval = FALSE}
+fbadGstats()
+```
+### Choose a folder
+[Windows-Only] Running the function with `choosedir` set to "YES" prompts you with a window in which you can select a folder and run `fbadgstats` on every file in that directory / folder.
+```{r, eval = FALSE}
+fbadGstats(choosedir  = "YES")
+```
+### Parameter highlight: `spentlim`
+I enjoy exploring DMAs (Designated Market Areas) as targets for advertising. Let's look at the worst performers.
+```{r} 
+fbadGstats(filerd = "example_DMA.csv", grphout = "NO", tblout = "WORST")
+```
+Look at all the regions with small amounts spent on them like #19 *Dayton* ($1.88). Perhaps not enough money has been spent in those regions, at least yet, to make their exclusion worthwhile.
+
+We can use the `spentlim` parameter to specify a minimum amount spent and therefore capture the DMAs that are proportionally more wasteful. By setting the minimum spent to $5, DMAs including *Dayton* no longer appear and *New York* rises to the second worst slot.
+```{r} 
+fbadGstats(filerd = "example_DMA.csv", grphout = "NO", tblout = "WORST", spentlim = 5)
+```
+### Parameter highlight: `prtrow`, `minevent`, `sumvar`
+Finally, the 15 worst with respect to *WEBSITE.REGISTRATIONS.COMPLETED* using the `sumvar` parameter. Notice that the entire column entry does not need to be typed for this case-insensitive parameter. "Regist" was sufficient.
+No limit on the amount spent (i.e., no `minspent` paramter in function call) but at least two *WEBSITE.REGISTRATIONS.COMPLETED* must have occurred:
+```{r} 
+fbadGstats(filerd = "example_DMA.csv", grphout = "NO", tblout = "WORST", sumvar = "Regist", prtrow = 15, minevent = 2)
+```
+```{r echo=FALSE, cache=FALSE}
+options(width = curwid)
+```