Documentation edits

docs/build/html/_sources/index.rst.txt

@@ -10,8 +10,9 @@ Contents:
    :maxdepth: 2
 
    intro
+   installation
    reference
-   basic-parametric
+   practical-examples
 
 
 ==================

docs/build/html/_sources/installation.rst.txt

@@ -0,0 +1,38 @@
+============
+Installation
+============
+
+Currently, `pwrcalc` has not been released on CRAN, so you must rely upon either an external package for installing `pwrcalc` or you can install the package manually.
+
+----
+ghit
+----
+
+`ghit` is a user-written package to install packages from GitHub, which is were `pwrcalc` lives. Run the following two-lines of code and you should be up and running with `pwrcalc`.
+
+.. code-block:: r
+
+	install.packages('ghit')
+	ghit::install_github('vikjam/pwrcalc')
+
+
+--------
+devtools
+--------
+
+Alternatively, `devtools` is another user-written package that allows you to install packages from GitHub. `devtools` mainly helps users create R packages, so you'll get a lot of other tools that come along with `devtools`.
+
+.. code-block:: r
+
+	install.packages('devtools')
+	devtools::install_github('vikjam/pwrcalc')
+
+
+-------------------
+Manual installation
+-------------------
+
+Finally, if neither of the previous installations options work for you. You can download the latest release_ from GitHub. Download the file with the extensions `.tar.gz`. And then use these instructions_ to install the downloaded file.
+
+.. _release: https://github.com/vikjam/pwrcalc/releases
+.. _instructions: http://outmodedbonsai.sourceforge.net/InstallingLocalRPackages.html

docs/build/html/_sources/practical-examples.rst.txt

@@ -0,0 +1,118 @@
+==================
+Practical Examples
+==================
+
+-----------------
+Two sample t-test
+-----------------
+
+Load the included Balsakhi data set, which we'll use to estimate the control mean.
+
+.. code-block:: r
+
+    library(pwrcalc)
+    data(balsakhi)
+    control_data <- balsakhi[which(balsakhi$bal == 0), ]
+    control_mean <- mean(control_data$post_totnorm, na.rm = TRUE)
+    control_sd   <- sd(control_data$post_totnorm, na.rm = TRUE)
+
+Let's inspect the results to make sure we're all on the same page.
+
+.. code-block:: rconsole
+
+    > print(control_mean)
+    [1] 0.4288781
+    > print(control_sd)
+    [1] 1.15142
+
+Let's say, based on other studies, that we expect an effect size of a tenth of a standard deviation. Now let's calculate the sample size for our anticipated effect size.
+
+.. code-block:: r
+
+    expected_effect <- control_sd / 10
+    treated_mean    <- control_mean + expected_effect
+
+We can now calculate the sample size needed to test that hypothesis at the significance level of 0.05 and power of 0.8.
+
+.. code-block:: rconsole
+
+    > twomeans(m1 = control_mean, m2 = treated_mean, sd = control_sd)
+
+         Two-sample t-test power calculation 
+
+                 m1 = 0.4288781
+                 m2 = 0.5440201
+                 n1 = 1570
+                 n2 = 1570
+          sig.level = 0.05
+              power = 0.8
+        alternative = two.sided
+
+    NOTE: 
+    m1 and m2 are the means of group 1 and 2, respectively.
+    n1 and n2 are the obs. of group 1 and 2, respectively.
+
+Now imagine we anticipate an effect half as large as the previous example. In particular, we now expect 1/20 of a standard deviation.
+
+.. code-block:: r
+
+    smaller_expected_effect <- control_sd / 20
+    smaller_treated_mean    <- control_mean + smaller_expected_effect
+
+.. code-block:: rconsole
+
+    > twomeans(m1 = control_mean, m2 = smaller_treated_mean, sd = control_sd)
+
+         Two-sample t-test power calculation 
+
+                 m1 = 0.4288781
+                 m2 = 0.4864491
+                 n1 = 6280
+                 n2 = 6280
+          sig.level = 0.05
+              power = 0.8
+        alternative = two.sided
+
+    NOTE: 
+    m1 and m2 are the means of group 1 and 2, respectively.
+    n1 and n2 are the obs. of group 1 and 2, respectively.
+
+Notice now we need four times as many observations as the previous example.
+
+-------------------------------------
+Two sample t-test with group clusters
+-------------------------------------
+
+Many designs randomize at the group level instead of at the individual level. For such designs, we need to adjust our power calculations so that they incorporate the fact that individuals within the same group may be subject to similar shocks, and thereby have correlated outcomes. Duflo et al. presents a modified parametric approach, which takes into account the intra-cluster correlation (ICC) that arises from randomization at the group level.
+
+.. code-block:: r
+
+    library(ICC)
+    icc_sample <- control_data[!is.na(divid) & !is.na(post_totnorm), ]
+    control_subset$divid = as.factor(control_subset$divid)
+    icc <- ICCest(divid, post_totnorm, data = control_subset)
+    rho <- icc$ICC
+
+.. code-block:: rconsole
+
+    > twomeans(m1 = control_mean, m2 = treated_mean, sd = control_sd) %>% clustered(obsclus = 10, rho = 0.3)
+
+         Two-sample t-test power calculation 
+
+                            m1 = 0.4288781
+                            m2 = 0.5440201
+               n1 (unadjusted) = 1570
+               n2 (unadjusted) = 1570
+                           rho = 0.3
+           Average per cluster = 10
+    Mininum number of clusters = 1162
+                 n1 (adjusted) = 5809
+                 n2 (adjusted) = 5809
+                     sig.level = 0.05
+                         power = 0.8
+                   alternative = two.sided
+
+    NOTE: 
+    - m1 and m2 are the means of group 1 and 2, respectively.
+    - n1 (unadjusted) and n2 (unadjusted) are the obs. of group 1 and 2 ignoring clustering.
+    - n1 (adjusted) and n2 (adjusted) are the obs. of group 1 and 2 adjusting for clustering.

docs/build/html/_sources/reference.rst.txt

@@ -22,6 +22,26 @@ twomeans
     :param power: one minus the probability of type II error, default is power = 0.8
     :rtype: A power.htest object with results in a structured list
 
+:Example:
+
+.. code-block:: rconsole
+
+    > twomeans(m1 = 12, m2 = 16, sd = 5)
+
+         Two-sample t-test power calculation 
+
+                 m1 = 12
+                 m2 = 16
+                 n1 = 25
+                 n2 = 25
+          sig.level = 0.05
+              power = 0.8
+        alternative = two.sided
+
+    NOTE: 
+    m1 and m2 are the means of group 1 and 2, respectively.
+    n1 and n2 are the obs. of group 1 and 2, respectively.
+
 ---------
 clustered
 ---------
@@ -35,3 +55,30 @@ clustered
     :params obsclus: Number of observations in each cluster
     :params numclus: Maximum number of clusters
     :rtype: A power.htest object with results in a structured list
+
+:Example:
+
+.. code-block:: rconsole
+
+    > twomeans(m1 = 12, m2 = 16, sd = 5) %>% clustered(obsclus = 10, rho = 0.3)
+
+         Two-sample t-test power calculation 
+
+                            m1 = 12
+                            m2 = 16
+               n1 (unadjusted) = 25
+               n2 (unadjusted) = 25
+                           rho = 0.3
+           Average per cluster = 10
+    Mininum number of clusters = 19
+                 n1 (adjusted) = 93
+                 n2 (adjusted) = 93
+                     sig.level = 0.05
+                         power = 0.8
+                   alternative = two.sided
+
+    NOTE: m1 and m2 are the means of group 1 and 2, respectively.
+    n1 and n2 are the obs. of group 1 and 2, respectively.
+
+
+

docs/build/html/_static/pygments.css

@@ -47,8 +47,10 @@
 .highlight .mh { color: #208050 } /* Literal.Number.Hex */
 .highlight .mi { color: #208050 } /* Literal.Number.Integer */
 .highlight .mo { color: #208050 } /* Literal.Number.Oct */
+.highlight .sa { color: #4070a0 } /* Literal.String.Affix */
 .highlight .sb { color: #4070a0 } /* Literal.String.Backtick */
 .highlight .sc { color: #4070a0 } /* Literal.String.Char */
+.highlight .dl { color: #4070a0 } /* Literal.String.Delimiter */
 .highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
 .highlight .s2 { color: #4070a0 } /* Literal.String.Double */
 .highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
@@ -59,7 +61,9 @@
 .highlight .s1 { color: #4070a0 } /* Literal.String.Single */
 .highlight .ss { color: #517918 } /* Literal.String.Symbol */
 .highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */
+.highlight .fm { color: #06287e } /* Name.Function.Magic */
 .highlight .vc { color: #bb60d5 } /* Name.Variable.Class */
 .highlight .vg { color: #bb60d5 } /* Name.Variable.Global */
 .highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */
+.highlight .vm { color: #bb60d5 } /* Name.Variable.Magic */
 .highlight .il { color: #208050 } /* Literal.Number.Integer.Long */

docs/build/html/basic-parametric.html

@@ -133,7 +133,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer" role="contentinfo">
         &#169; Copyright 2017.
-      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.5.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
     </div>
   </body>
 </html>

docs/build/html/genindex.html

@@ -104,7 +104,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer" role="contentinfo">
         &#169; Copyright 2017.
-      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.5.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
     </div>
   </body>
 </html>

docs/build/html/index.html

@@ -58,12 +58,22 @@ <h1>Documentation for the R package pwrcalc<a class="headerlink" href="#document
 <li class="toctree-l2"><a class="reference internal" href="intro.html#why-another-power-analysis-package-for-r">Why Another Power Analysis Package for R?</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="installation.html#ghit">ghit</a></li>
+<li class="toctree-l2"><a class="reference internal" href="installation.html#devtools">devtools</a></li>
+<li class="toctree-l2"><a class="reference internal" href="installation.html#manual-installation">Manual installation</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">Reference</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#twomeans">twomeans</a></li>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#clustered">clustered</a></li>
 </ul>
 </li>
-<li class="toctree-l1"><a class="reference internal" href="basic-parametric.html">Basic Parametric example</a></li>
+<li class="toctree-l1"><a class="reference internal" href="practical-examples.html">Practical Examples</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="practical-examples.html#two-sample-t-test">Two sample t-test</a></li>
+<li class="toctree-l2"><a class="reference internal" href="practical-examples.html#two-sample-t-test-with-group-clusters">Two sample t-test with group clusters</a></li>
+</ul>
+</li>
 </ul>
 </div>
 </div>
@@ -126,7 +136,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer" role="contentinfo">
         &#169; Copyright 2017.
-      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.5.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
     </div>
   </body>
 </html>