internal documentation

DESCRIPTION

@@ -1,9 +1,10 @@
 Package: capybara
 Type: Package
-Title: Capybaras are cool
-Version: 2022.03.21
+Title: Fast and Memory Efficient Fitting of Linear Models With High-Dimensional
+    Fixed Effects
+Version: 2024.01.15
 Authors@R: c(
-    person("Mauricio", "Vargas",
+    person("Mauricio", "Vargas Sepulveda",
         role = c("aut", "cre"),
         email = "[email protected]",
         c(ORCID = "0000-0003-1017-7574"))
@@ -17,7 +18,11 @@ Suggests:
     knitr,
     rmarkdown
 Depends: R(>= 3.5.0)
-Description: Add some description later. This is about linear algebra.
+Description: Fast and user-friendly estimation of generalized linear models with
+    multiple fixed effects and cluster the standard errors. The method to obtain
+    the estimated fixed-effects coefficients is based on Stammann (2018) 
+    <https://arxiv.org/abs/1707.01815> and Gaure (2013)
+    <https://dx.doi.org/10.1016/j.csda.2013.03.024>.
 License: MIT + file LICENSE
 BugReports: https://github.com/pachadotdev/capybara/issues
 URL: https://pacha.dev/capybara/, https://github.com/pachadotdev/capybara

NAMESPACE

@@ -1,33 +1,35 @@
 # Generated by roxygen2: do not edit by hand
 
-S3method(coef,APEs)
+S3method(coef,apes)
 S3method(coef,feglm)
 S3method(coef,felm)
-S3method(coef,summary.APEs)
+S3method(coef,summary.apes)
 S3method(coef,summary.feglm)
+S3method(coef,summary.felm)
 S3method(fitted,feglm)
 S3method(fitted,felm)
 S3method(predict,feglm)
-S3method(print,APEs)
+S3method(predict,felm)
+S3method(print,apes)
 S3method(print,feglm)
 S3method(print,felm)
-S3method(print,summary.APEs)
+S3method(print,summary.apes)
 S3method(print,summary.feglm)
 S3method(print,summary.felm)
-S3method(summary,APEs)
+S3method(summary,apes)
 S3method(summary,feglm)
 S3method(summary,felm)
-S3method(vcov,APEs)
+S3method(vcov,apes)
 S3method(vcov,feglm)
 S3method(vcov,felm)
-export(biasCorr)
+export(apes)
+export(bias_corr)
 export(feglm)
-export(feglm.control)
-export(feglm.nb)
-export(feglmControl)
-export(getAPEs)
-export(getFEs)
-export(simGLM)
+export(feglm_control)
+export(felm)
+export(fenegbin)
+export(fepoisson)
+export(fixed_effects)
 importFrom(Formula,Formula)
 importFrom(MASS,negative.binomial)
 importFrom(MASS,theta.ml)
@@ -37,6 +39,7 @@ importFrom(data.table,setDT)
 importFrom(data.table,setkeyv)
 importFrom(stats,as.formula)
 importFrom(stats,binomial)
+importFrom(stats,gaussian)
 importFrom(stats,model.matrix)
 importFrom(stats,na.omit)
 importFrom(stats,pnorm)

README.Rmd

@@ -6,10 +6,10 @@ output: github_document
 
 ```{r, include = FALSE}
 knitr::opts_chunk$set(
-  collapse = TRUE,
-  comment = "#>",
-  fig.path = "man/figures/README-",
-  out.width = "100%"
+    collapse = TRUE,
+    comment = "#>",
+    fig.path = "man/figures/README-",
+    out.width = "100%"
 )
 ```
 
@@ -25,33 +25,12 @@ The goal of capybara is to ...
 You can install the development version of capybara like so:
 
 ``` r
-# FILL THIS IN! HOW CAN PEOPLE INSTALL YOUR DEV PACKAGE?
+remotes::install_github("pachadotdev/capybara")
 ```
 
-## Example
+## Examples
 
-This is a basic example which shows you how to solve a common problem:
-
-```{r example}
-library(capybara)
-## basic example code
-```
-
-What is special about using `README.Rmd` instead of just `README.md`? You can include R chunks like so:
-
-```{r cars}
-summary(cars)
-```
-
-You'll still need to render `README.Rmd` regularly, to keep `README.md` up-to-date. `devtools::build_readme()` is handy for this.
-
-You can also embed plots, for example:
-
-```{r pressure, echo = FALSE}
-plot(pressure)
-```
-
-In that case, don't forget to commit and push the resulting figure files, so they display on GitHub and CRAN.
+See the documentation in progress: https://pacha.dev/capybara
 
 # Debugging
 

README.md

@@ -0,0 +1,110 @@
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+# capybara
+
+<!-- badges: start -->
+
+<!-- badges: end -->
+
+The goal of capybara is to …
+
+## Installation
+
+You can install the development version of capybara like so:
+
+``` r
+remotes::install_github("pachadotdev/capybara")
+```
+
+## Examples
+
+See the documentation in progress: <https://pacha.dev/capybara>
+
+# Debugging
+
+*This debugging is about code quality, not about statistical quality.*
+*There is a full set of numerical tests for testthat to check the math.*
+*In this section of the test, I can write pi = 3 and if there are no
+memory leaks, it will pass the test.*
+
+I run `r_valgrind "dev/test_get_alpha.r" "dev/test_get_alpha.txt"` or
+the corresponding test from the project’s root in a new terminal (bash).
+
+This works because I previously defined this in `.bashrc`, to make it
+work you need to run `source ~/.bashrc` or reboot:
+
+    # create an alias for R
+    alias r="R"
+
+    alias rvalgrind="R --vanilla -d 'valgrind -s --track-origins=yes'"
+
+    function r_debug_symbols () {
+        # if src/Makevars does not exist, exit
+        if [ ! -f src/Makevars ]; then
+            echo "File src/Makevars does not exist"
+            return 1
+        fi
+
+        # if src/Makevars contains a line that says "PKG_CPPFLAGS"
+        # but there is no "-UDEBUG -g" on it
+        # then add "PKG_CPPFLAGS += -UDEBUG -g" at the end
+        if grep -q "PKG_CPPFLAGS" src/Makevars; then
+            if ! grep -q "PKG_CPPFLAGS.*-UDEBUG.*-g" src/Makevars; then
+                echo "PKG_CPPFLAGS += -UDEBUG -g" >> src/Makevars
+            fi
+        fi
+
+        # if src/Makevars does not contain a line that reads
+        # PKG_CPPFLAGS ...something... -UDEBUG -g ...something...
+        # then add PKG_CPPFLAGS = -UDEBUG -g to it
+        if ! grep -q "PKG_CPPFLAGS.*-UDEBUG.*-g" src/Makevars; then
+            echo "PKG_CPPFLAGS = -UDEBUG -g" >> src/Makevars
+        fi
+    }
+
+    function r_valgrind () {
+        # if no argument is provided, ask for a file
+        if [ -z "$1" ]; then
+            read -p "Enter the script to debug: " script
+        else
+            script=$1
+        fi
+
+        # if no output file is provided, use dev/valgrind.txt
+        if [ -z "$2" ]; then
+            output="dev/valgrind.txt"
+        else
+            output=$2
+        fi
+
+        # if the file does not exist, exit
+        if [ ! -f "$script" ]; then
+            echo "File $script does not exist"
+            return 1
+        fi
+
+        # if the file does not end in .R/.r, exit
+        shopt -s nocasematch
+        if [[ "$script" != *.R ]]; then
+            echo "File $script does not end in .R or .r"
+            return 1
+        fi
+        shopt -u nocasematch
+
+        # run R in debug mode, but after that we compiled with debug symbols
+        # see https://reside-ic.github.io/blog/debugging-memory-errors-with-valgrind-and-gdb/
+        # R -d 'valgrind -s --leak-check=full --show-leak-kinds=all --track-origins=yes' -f $script 2>&1 | tee valgrind.txt
+        R --vanilla -d 'valgrind -s --track-origins=yes' -f $script 2>&1 | tee $output
+    }
+
+`r_debug_symbols()` makes everything slower, but makes sure that all
+compiler optimizations are disabled and then valgrind will point us to
+the lines that create memory leaks.
+
+`r_valgrind()` will run an R script and use Linux system tools to test
+for initialized values and all kinds of problems that result in memory
+leaks.
+
+When you are ready testing, you need to remove `-UDEGUG` from
+`src/Makevars`.