### Install and Load EdSurvey Packages

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/articles/introduction.html

Installs the EdSurvey and tidyEdSurvey packages and loads them into the R environment. This setup is required to perform data management and analysis on NCES datasets.

```R
install.packages(c("EdSurvey", "tidyEdSurvey"))
require(tidyEdSurvey)
options(EdSurvey_round_output = TRUE)
```

--------------------------------

### Install EdSurvey Development Version (R)

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/README.md

Installs the development version of the EdSurvey package from GitHub. Requires the devtools package to be installed first.

```r
install.packages("devtools")
devtools::install_github("American-Institutes-for-Research/edsurvey")
```

--------------------------------

### Achievement Levels Function Examples

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/achievementLevels.html

Provides R code examples demonstrating the usage of the `achievementLevels` function for analyzing discrete and cumulative achievement levels, with various aggregation and customization options.

```APIDOC
## achievementLevels Function Examples

### Description
This section provides R code examples for the `achievementLevels` function, illustrating its use for analyzing achievement levels with different configurations.

### Method
R Code Examples

### Endpoint
N/A (Function within a package)

### Parameters
- `achievementVars` (character vector) - Variables to analyze.
- `aggregateBy` (character or NULL) - Variable to aggregate by.
- `data` (data.frame) - The input data frame.
- `returnCumulative` (logical) - Whether to return cumulative levels.
- `cutpoints` (numeric vector) - Custom cutpoints for achievement levels.
- `recode` (list) - Recoding rules for variables.

### Request Example
```R
# read in the example data (generated, not real student data)
sdf <- readNAEP(path=system.file("extdata/data", "M36NT2PM.dat", package="NAEPprimer"))

# discrete achievement levels
achievementLevels(achievementVars=c("composite"), aggregateBy=NULL, data=sdf)

# discrete achievement levels with a different subscale
achievementLevels(achievementVars=c("num_oper"), aggregateBy=NULL, data=sdf)

# cumulative achievement levels
achievementLevels(achievementVars=c("composite"), aggregateBy=NULL, data=sdf, 
                  returnCumulative=TRUE)

# cumulative achievement levels with a different subscale
achievementLevels(achievementVars=c("num_oper"), aggregateBy=NULL, data=sdf, 
                  returnCumulative=TRUE)

# achievement levels as independent variables, by sex aggregated by composite
achievementLevels(achievementVars=c("composite", "dsex"), aggregateBy="composite",
                  data=sdf, returnCumulative=TRUE)

# achievement levels as independent variables, by sex aggregated by sex
achievementLevels(achievementVars=c("composite", "dsex"), aggregateBy="dsex", 
                  data=sdf, returnCumulative=TRUE)

# achievement levels as independent variables, by race aggregated by race
achievementLevels(achievementVars=c("composite", "sdracem"),
                      aggregateBy="sdracem", data=sdf, returnCumulative=TRUE)

# use customized cutpoints
achievementLevels(achievementVars=c("composite"), aggregateBy=NULL, data=sdf, 
                  cutpoints = c("Customized Basic" = 200, 
                                "Customized Proficient" = 300, 
                                "Customized Advanced" = 400))

# use recode to change values for specified variables:
achievementLevels(achievementVars=c("composite", "dsex", "b017451"),
                      aggregateBy = "dsex", sdf,
                      recode=list(b017451=list(from=c("Never or hardly ever",
                                                      "Once every few weeks",
                                                      "About once a week"),
                                               to="Infrequently"),
                                  b017451=list(from=c("2 or 3 times a week",
                                                      "Every day"),
                                               to="Frequently")))
```

### Response
N/A (Function output depends on input and data)
```

--------------------------------

### Install EdSurvey Package

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/index.html

Provides commands to install the EdSurvey package from either CRAN for the stable release or GitHub for the latest development version. The development installation requires the devtools package.

```R
# Install the released version from CRAN
install.packages("EdSurvey")

# Install the development version from GitHub
install.packages("devtools")
devtools::install_github("American-Institutes-for-Research/edsurvey")
```

--------------------------------

### Importing and Analyzing ePIRLS Data

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/read_ePIRLS.html

This example demonstrates how to load ePIRLS data for a specific country, extract variables using getData, and perform a basic analysis using edsurveyTable.

```R
usa <- read_ePIRLS("~/ePIRLS/2016", countries = c("usa"))
gg <- getData(data=usa, varnames=c("itsex", "totwgt", "erea"))
head(gg)
edsurveyTable(formula=erea ~ itsex, data=usa)
```

--------------------------------

### Install Development Dependencies with devtools

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/CONTRIBUTING.html

This R code snippet shows how to install all necessary development dependencies for the EdSurvey package using the `devtools` package. It's crucial for ensuring the package can be built and checked correctly.

```R
devtools::install_dev_deps()
```

--------------------------------

### Importing and Analyzing ICILS Data

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/readICILS.html

This example demonstrates how to read ICILS student data for a specific country, extract variables using getData, and perform a basic edsurveyTable analysis.

```R
pol <- readICILS("~/ICILS/2013", countries = "pol", dataSet = "student")
gg <- getData(data=pol, varnames=c("idstud", "cil", "is1g18b"))
head(gg)
edsurveyTable(formula=cil ~ is1g18b, pol)
```

--------------------------------

### Example Usage of getAttributes and setAttributes

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/edsurvey-class.html

Demonstrates how to extract and update attributes, specifically 'omittedLevels', using getAttributes and setAttributes.

```APIDOC
## Example Usage of getAttributes and setAttributes

### Description
This example illustrates reading data, performing basic data manipulation, and then using `getAttributes` to inspect and `setAttributes` to modify the `omittedLevels` attribute.

### Code Example
```R
# Read in the example data
sdf <- readNAEP(path=system.file("extdata/data", "M36NT2PM.dat", package="NAEPprimer"))

# Extract default omitted levels
omitted_levels_before <- getAttributes(data=sdf, attribute="omittedLevels")
print(omitted_levels_before)
# Expected output: [1] "Multiple" NA         "Omitted"

# Update omitted levels
sdf <- setAttributes(data=sdf,
                   attribute="omittedLevels",
                   value=c("Multiple", "Omitted", NA, "(Missing)"))

# Extract updated omitted levels
omitted_levels_after <- getAttributes(data=sdf, attribute="omittedLevels")
print(omitted_levels_after)
# Expected output: [1] "Multiple"  "Omitted"   NA          "(Missing)"
```
```

--------------------------------

### Install EdSurvey CRAN Release Version (R)

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/README.md

Installs the latest stable release of the EdSurvey package from CRAN. This is the recommended method for most users.

```r
install.packages("EdSurvey")
```

--------------------------------

### Getting a light.edsurvey.data.frame

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/edsurvey-class.html

Explains how to obtain a light.edsurvey.data.frame object using the getData method.

```APIDOC
## Getting a light.edsurvey.data.frame

### Description
Users can obtain a `light.edsurvey.data.frame` object by utilizing the `getData` method with the `addAttributes` parameter set to `TRUE`.

### Method
- **`getData(data, addAttributes = TRUE)`**
  - **Parameters**:
    - **`data`** (edsurvey.data.frame) - The input data object.
    - **`addAttributes`** (boolean) - If `TRUE`, returns a `light.edsurvey.data.frame` with basic survey design attributes.
```

--------------------------------

### Perform Direct Estimation with TIMSS Data

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/mml.sdf.html

Shows the process of downloading and reading TIMSS data, followed by fitting a direct estimation model. This example highlights the use of specific weight variables and variance estimation settings required for TIMSS analysis.

```R
downloadTIMSS("~/", year=2015)
sdfTIMSS <- readTIMSS(path="~/TIMSS/2015", countries="usa", grade = "4")
mmlTIMSS <- mml.sdf(formula=mmat ~ itsex + asbg04, data=sdfTIMSS, weightVar='totwgt')
summary(mmlTIMSS, varType="Taylor", strataVar="jkzone", PSUVar="jkrep")
```

--------------------------------

### Load ECLS–K 2011 Data

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/readECLS_K2011.html

Demonstrates how to initialize an edsurvey.data.frame using the readECLS_K2011 function. The example shows both default usage and explicit parameter configuration for loading specific files.

```R
# Read-in student file with defaults
eclsk_df <- readECLS_K2011(path="~/ECLS_K/2011")
d <- getData(data=eclsk_df, varnames=c("childid", "c1hgt1", "c1wgt1"))
summary(d)

# Read-in with parameters specified
eclsk_df <- readECLS_K2011(path = "~/ECLS_K/2011",
                           filename = "childK5p.dat",
                           layoutFilename = "ECLSK2011_K5PUF.sps",
                           forceReread = FALSE,
                           verbose = TRUE)
```

--------------------------------

### jQuery CSS Setting and Getting

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/README.html

Demonstrates how to set and retrieve CSS properties for elements using jQuery's `.css()` method. It handles various property types, including those requiring units like 'px'.

```javascript
S.extend({
    cssHooks: {
        opacity: {
            get: function(e, t) {
                if (t) {
                    var n = We(e, "opacity");
                    return "" === n ? "1" : n
                }
            }
        }
    },
    cssNumber: {
        animationIterationCount: !0,
        columnCount: !0,
        fillOpacity: !0,
        flexGrow: !0,
        flexShrink: !0,
        fontWeight: !0,
        gridArea: !0,
        gridColumn: !0,
        gridColumnEnd: !0,
        gridColumnStart: !0,
        gridRow: !0,
        gridRowEnd: !0,
        gridRowStart: !0,
        lineHeight: !0,
        opacity: !0,
        order: !0,
        orphans: !0,
        widows: !0,
        zIndex: !0,
        zoom: !0
    },
    cssProps: {},
    style: function(e, t, n, r) {
        if (e && 3 !== e.nodeType && 8 !== e.nodeType && e.style) {
            var i, o, a, s = X(t),
                u = Xe.test(t),
                l = e.style;
            if (u || (t = ze(s)), a = S.cssHooks[t] || S.cssHooks[s], void 0 === n) return a && "get" in a && void 0 !== (i = a.get(e, !1, r)) ? i : l[t];
            "string" === (o = typeof n) && (i = te.exec(n)) && i[1] && (n = se(e, t, i), o = "number"), null != n && n == n && ("number" !== o || u || (n += i && i[3] || (S.cssNumber[s] ? "" : "px")), y.clearCloneStyle || "" !== n || 0 !== t.indexOf("background") || (l[t] = "inherit"), a && "set" in a && void 0 === (n = a.set(e, n, r)) || (u ? l.setProperty(t, n) : l[t] = n))
        }
    },
    css: function(e, t, n, r) {
        var i, o, a, s = X(t);
        return Xe.test(t) || (t = ze(s)), (a = S.cssHooks[t] || S.cssHooks[s]) && "get" in a && (i = a.get(e, !0, n)), void 0 === i && (i = We(e, t, r)), "normal" === i && t in Ge && (i = Ge[t]), "" === n || n ? (o = parseFloat(i), !0 === n || isFinite(o) ? o || 0 : i) : i
    }
}), S.each(["height", "width"], function(e, u) {
    S.cssHooks[u] = {
        get: function(e, t, n) {
            if (t) return !Ue.test(S.css(e, "display")) || e.getClientRects().length && e.getBoundingClientRect().width ? Je(e, u, n) : Me(e, Ve, function() {
                return Je(e, u, n)
            })
        },
        set: function(e, t, n) {
            var r, i = Re(e), 
                o = !y.scrollboxSize() && "absolute" === i.position,
                a = (o || n) && "border-box" === S.css(e, "boxSizing", !1, i),
                s = n ? Qe(e, u, n, a, i) : 0;
            return a && o && (s -= Math.ceil(e["offset" + u[0].toUpperCase() + u.slice(1)] - parseFloat(i[u]) - Qe(e, u, "border", !1, i) - .5)), s && (r = te.exec(t)) && "px" !== (r[3] || "px") && (e.style[u] = t, t = S.css(e, u)), Ye(0, t, s)
        }
    }
}), S.cssHooks.marginLeft = Fe(y.reliableMarginLeft, function(e, t) {
    if (t) return (parseFloat(We(e, "marginLeft")) || e.getBoundingClientRect().left - Me(e, {
        marginLeft: 0
    }, function() {
        return e.getBoundingClientRect().left
    })) + "px"
}), S.each({
    margin: "",
    padding: "",
    border: "Width"
}, function(i, o) {
    S.cssHooks[i + o] = {
        expand: function(e) {
            for (var t = 0, n = {}, r = "string" == typeof e ? e.split(" ") : [e]; t < 4; t++)
                n[i + ne[t] + o] = r[t] || r[t - 2] || r[0];
            return n
        }
    },
    "margin" !== i && (S.cssHooks[i + o].set = Ye)
}), S.fn.extend({
    css: function(e, t) {
        return $(this, function(e, t, n) {
            var r, i, o = {}, a = 0;
            if (Array.isArray(t)) {
                for (r = Re(e), i = t.length; a < i; a++) o[t[a]] = S.css(e, t[a], !1, r);
                return o
            }
            return void 0 !== n ? S.style(e, t, n) : S.css(e, t)
        }, e, t, 1 < arguments.length)
    }
}), ((S.Tween = Ke).prototype = {
    constructor: Ke,
    init: function(e, t, n, r, i, o) {
        this.elem = e,
        this.prop = n,
        this.easing = i || S.easing._default,
        this.options = t,
        this.start = this.now = this.cur(),
        this.end = r,
        this.unit = o || (S.cssNumber[n] ? "" : "px")
    },
    cur: function() {
        var e = Ke.propHooks[this.prop];
        return e && e.get ? e.get(this) : Ke.propHooks._default.get(this)
    },
    r
```

--------------------------------

### Retrieve IRT Item Variables using getAllItems

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/getAllItems.html

This example demonstrates how to use getAllItems to retrieve specific item names for constructs like mathematics or science, or all items by setting the construct to NULL. It also shows how these items are used to build a light.edsurvey.data.frame for use with mml.sdf.

```R
t15 <- readTIMSS(path="~/TIMSS/2015", "usa", 4)
mathItems <- getAllItems(sdf=t15, construct="mmat")
sciItems <- getAllItems(sdf=t15, construct="ssci")
allItems <- getAllItems(sdf=t15, construct=NULL)

lsdf <- getData(data=t15, varnames=c("ROWID", "mmat", mathItems, psustr, wgtVar), omittedLevels=FALSE, addAttributes=TRUE)
mml.sdf(formula=mmat ~ 1, data=lsdf, weightVar="totwgt")
```

--------------------------------

### Read ELS:2002 Data into EdSurvey

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/readELS.html

Demonstrates how to use the readELS function to load student and school level data. The examples show both default usage and explicit parameter configuration for weight files.

```R
# read-in student file including weight file as default
els_df <- readELS("~/ELS/2002")
d <- getData(data=els_df, varnames=c("stu_id", "bysex", "bystlang"))
summary(d)

# read-in with parameters specified (student level with weights)
els_wgt_df <- readELS(path = "~/ELS/2002", 
                      filename = "els_02_12_byf3pststu_v1_0.sav", 
                      wgtFilename = "els_02_12_byf3stubrr_v1_0.sav",
                      verbose = TRUE, 
                      forceReread = FALSE)

# read-in with parameters specified (school level, no separate weight replicate file)
els_sch_df <- readELS(path = "~/ELS/2002", 
                      filename = "els_02_12_byf1sch_v1_0.sav", 
                      wgtFilename = NA,
                      verbose = TRUE, 
                      forceReread = FALSE)
```

--------------------------------

### Calculate Degrees of Freedom with DoFCorrection

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/DoFCorrection.html

This example demonstrates how to use the DoFCorrection function to calculate degrees of freedom for a regression coefficient and for a contrast between two coefficients using the Johnson-Rust method.

```R
sdf <- readNAEP(path=system.file("extdata/data", "M36NT2PM.dat", package="NAEPprimer"))
lm1 <- lm.sdf(formula=composite ~ dsex + b017451, data=sdf, returnVarEstInputs=TRUE)
# Calculate DoF for a single coefficient
dof1 <- DoFCorrection(lm1$varEstInputs, varA="dsexFemale", method="JR")
# Calculate DoF for a contrast between two coefficients
dofContrast <- DoFCorrection(lm1$varEstInputs, varA="dsexFemale", varB="b017451Every day", method="JR")
```

--------------------------------

### Example: Accessing TALIS 2018 School Data

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/readTALIS.html

This R code demonstrates how to read TALIS 2018 school-level data for all available countries using the readTALIS function. It then shows how to perform an unweighted summary analysis on the imported data.

```R
talis18 <- readTALIS(path = "~/TALIS/2018", 
                     isced = "b", 
                     dataLevel = "school", 
                     countries = "*")

#unweighted summary
result <- summary2(data=talis18, variable="tc3g01", weightVar = "")

#print usa results to console
result$usa
```

--------------------------------

### Fit Weighted Generalized Linear Models with EdSurvey

Source: https://context7.com/american-institutes-for-research/edsurvey/llms.txt

Demonstrates fitting weighted generalized linear models, including logistic regression, using `glm.sdf` and `logit.sdf`. It supports various link functions and handles survey weights and plausible values. Examples show different variance estimation methods and formula specifications.

```R
library(EdSurvey)
sdf <- readNAEP(path = system.file("extdata/data", "M36NT2PM.dat", package = "NAEPprimer"))

# Create a binary outcome variable
sdf$b013801_26more <- ifelse(sdf$b013801 %in% c("26-100", ">100"), yes = 1, no = 0)

# Logistic regression with jackknife variance
logit1 <- logit.sdf(formula = b013801_26more ~ dsex + b017451, data = sdf)
summary(logit1)

# Logistic regression with Taylor series variance
logit1t <- logit.sdf(formula = b013801_26more ~ dsex + b017451, data = sdf,
                     varMethod = "Taylor")
summary(logit1t)

# Use ifelse in formula for plausible values
logit2 <- logit.sdf(formula = ifelse(composite >= 300, yes = 1, no = 0) ~ dsex + b013801,
                    data = sdf)
summary(logit2)

# Use I() for indicator function with plausible values
logit3 <- glm.sdf(formula = I(composite >= 300) ~ dsex + b013801, data = sdf,
                  family = quasibinomial(link = "logit"))
summary(logit3)

# Wald test for joint hypothesis
waldTest(model = logit3, coefficients = "b013801")
```

--------------------------------

### Push Changes and Create Pull Request

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/CONTRIBUTING.html

This R code snippet pushes local Git commits to the remote repository and initiates the pull request process via the GitHub web interface using the `usethis` package. It guides the user through the final steps of submitting their contribution.

```R
usethis::pr_push()
```

--------------------------------

### Example: Accessing TALIS 2013 Teacher Data and Extracting Variables

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/readTALIS.html

This R code snippet illustrates reading TALIS 2013 teacher-level data for the USA. It then demonstrates how to extract specific variables into a data frame using the getData function and perform an analysis using edsurveyTable.

```R
usa2013 <- readTALIS(path = "~/TALIS/2013", isced = "b",
                     dataLevel = "teacher", countries = "usa")

# extract a data.frame with a few variables
gg <- getData(usa2013, c("tt2g05b", "tt2g01"))  
head(gg)

# conduct an analysis on the edsurvey.data.frame
edsurveyTable(formula=tt2g05b ~ tt2g01, data = usa2013)
```

--------------------------------

### Fork and Clone Repository with usethis

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/CONTRIBUTING.html

This R code snippet demonstrates how to fork the EdSurvey repository from GitHub and clone it to your local machine using the `usethis` package. This is the recommended first step for new contributors.

```R
usethis::create_from_github("American-Institutes-for-Research/EdSurvey", fork = TRUE)
```

--------------------------------

### Create and Append EdSurvey Data Frame Lists

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/edsurvey.data.frame.list.html

Demonstrates how to initialize an edsurvey.data.frame.list from a list of edsurvey.data.frame objects and how to append additional data frames to an existing list.

```R
# Create an edsurvey.data.frame.list from a list of edsurvey.data.frames
sdfl <- edsurvey.data.frame.list(datalist=list(sdfA, sdfB, sdfC, sdfD), labels=c("A locations", "B locations", "C locations", "D locations"))

# Append two edsurvey.data.frame objects or lists
combined_sdfl <- append.edsurvey.data.frame.list(sdfA, sdfB)
```

--------------------------------

### GET /getAttributes

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/edsurvey-class.html

Retrieves specific metadata attributes from an edsurvey.data.frame object.

```APIDOC
## GET /getAttributes

### Description
Acts as an accessor to retrieve metadata attributes from an edsurvey.data.frame object.

### Method
GET

### Endpoint
/getAttributes

### Parameters
#### Query Parameters
- **data** (object) - Required - The edsurvey.data.frame object.
- **attribute** (string) - Optional - The specific attribute to retrieve.

### Request Example
{
  "attribute": "weights"
}

### Response
#### Success Response (200)
- **value** (any) - The requested attribute value.

#### Response Example
{
  "attribute": "weights",
  "value": { "default": "wgt" }
}
```

--------------------------------

### GET /dim/edsurvey

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/dim.edsurvey.data.frame.html

Retrieves the dimensions (rows and columns) of an edsurvey.data.frame or edsurvey.data.frame.list object.

```APIDOC
## GET /dim/edsurvey

### Description
Returns the dimensions of an edsurvey.data.frame or an edsurvey.data.frame.list object to determine the number of rows and columns.

### Method
GET

### Endpoint
/dim/edsurvey

### Parameters
#### Request Body
- **x** (edsurvey.data.frame/list) - Required - The edsurvey data object to inspect.

### Request Example
{
  "x": "edsurvey_data_object"
}

### Response
#### Success Response (200)
- **nrow** (numeric/vector) - The number of rows.
- **ncol** (numeric) - The number of columns.

#### Response Example
{
  "nrow": 1000,
  "ncol": 50
}
```

--------------------------------

### GET /levelsSDF

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/levelsSDF.html

Retrieves the levels and labels of specified variables from an EdSurvey data object.

```APIDOC
## GET /levelsSDF

### Description
Retrieves the levels and labels of a variable from an edsurvey.data.frame, a light.edsurvey.data.frame, or an edsurvey.data.frame.list.

### Method
GET

### Endpoint
levelsSDF(varnames, data, showOmitted = TRUE, showN = TRUE)

### Parameters
#### Path Parameters
- **varnames** (vector of strings) - Required - A vector of character strings to search for in the database connection object.
- **data** (object) - Required - An edsurvey.data.frame, light.edsurvey.data.frame, or edsurvey.data.frame.list.

#### Query Parameters
- **showOmitted** (boolean) - Optional - A Boolean indicating if omitted levels should be shown. Defaults to TRUE.
- **showN** (boolean) - Optional - A Boolean indicating if (unweighted) n-sizes should be shown for each response level. Defaults to TRUE.

### Request Example
levelsSDF(varnames=c("pared", "ell3"), data=sdf)

### Response
#### Success Response (200)
- **result** (list) - A list containing the levels and labels for the requested variables.

#### Response Example
{
  "pared": {
    "levels": ["Did not finish high school", "Graduated high school", "Some education after high school"],
    "labels": ["1", "2", "3"]
  }
}
```

--------------------------------

### Calculate Achievement Level Statistics with EdSurvey

Source: https://context7.com/american-institutes-for-research/edsurvey/llms.txt

Provides examples for the `achievementLevels` function, which calculates the percentage of students at different achievement levels (e.g., Basic, Proficient, Advanced) with standard errors. The function supports custom cut points and aggregation by specified variables. Examples show discrete and cumulative levels, and aggregation by different demographic variables.

```R
library(EdSurvey)
sdf <- readNAEP(path = system.file("extdata/data", "M36NT2PM.dat", package = "NAEPprimer"))

# Discrete achievement levels for composite score
achievementLevels(achievementVars = c("composite"), aggregateBy = NULL, data = sdf)

# Achievement levels for a subscale
achievementLevels(achievementVars = c("num_oper"), aggregateBy = NULL, data = sdf)

# Cumulative achievement levels (at or above each level)
achievementLevels(achievementVars = c("composite"), aggregateBy = NULL, data = sdf,
                  returnCumulative = TRUE)

# Achievement levels by sex, aggregated by composite
achievementLevels(achievementVars = c("composite", "dsex"), aggregateBy = "composite",
                  data = sdf, returnCumulative = TRUE)

# Achievement levels by race, aggregated by race
achievementLevels(achievementVars = c("composite", "sdracem"),
                  aggregateBy = "sdracem", data = sdf, returnCumulative = TRUE)
```

--------------------------------

### GET /edsurvey/data

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/edsurvey-class.html

Retrieves data from an edsurvey.data.frame object with optional configuration for decimal conversion and variable naming.

```APIDOC
## GET /edsurvey/data

### Description
Extracts data from an edsurvey.data.frame object. Allows for automatic lowercasing of variables and decimal multiplier application.

### Method
GET

### Endpoint
/edsurvey/data

### Parameters
#### Query Parameters
- **x** (edsurvey.data.frame) - Required - The edsurvey data frame object.
- **lowercase** (boolean) - Optional - If TRUE, automatically lowercases variable names.
- **reqDecimalConversion** (boolean) - Optional - If TRUE, multiplies raw file values by a decimal multiplier.
- **cacheDataLevelName** (character) - Optional - Matches the named element in dataList for caching.

### Request Example
{
  "x": "survey_obj",
  "lowercase": true,
  "reqDecimalConversion": false
}

### Response
#### Success Response (200)
- **data** (object) - The extracted survey data frame.

#### Response Example
{
  "data": { "student_id": 101, "score": 550 }
}
```

--------------------------------

### GET /getAllItems

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/getAllItems.html

Retrieves IRT item variable names associated with specified constructs from an EdSurvey data object.

```APIDOC
## GET getAllItems

### Description
Retrieves the IRT item variable names associated with construct names for use with the mml.sdf function. This is essential for preparing light.edsurvey.data.frame objects.

### Method
GET

### Endpoint
getAllItems(sdf, construct = NULL)

### Parameters
#### Path Parameters
- **sdf** (edsurvey.data.frame) - Required - An edsurvey.data.frame or light.edsurvey.data.frame containing IRT information (Supports NAEP and TIMSS 2011, 2015, and 2019).

#### Query Parameters
- **construct** (character/vector) - Optional - A character value or vector for which to return associated item variable names. Defaults to NULL (returns all IRT item variable names).

### Request Example
getAllItems(sdf=t15, construct="mmat")

### Response
#### Success Response (200)
- **result** (character vector) - A vector of item names associated with the provided construct(s).

#### Response Example
["mmat01", "mmat02", "mmat03", "mmat04", "mmat05"]
```

--------------------------------

### Initialize Git Branch for Pull Request

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/CONTRIBUTING.html

This R code snippet initializes a new Git branch for a pull request using the `usethis` package. It takes a brief description of the intended changes as an argument, which helps in organizing the contribution.

```R
usethis::pr_init("brief-description-of-change")
```

--------------------------------

### Bootstrap Popover Component Implementation

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/README.html

Handles the initialization and content management for Bootstrap popovers. It allows for dynamic content injection and provides a noConflict method to avoid namespace collisions.

```javascript
c.prototype.setContent=function(){var a=this.tip(),b=this.getTitle(),c=this.getContent();a.find(".popover-title")[this.options.html?"html":"text"](b),a.find(".popover-content").children().detach().end()[this.options.html?"string"==typeof c?"html":"append":"text"](c),a.removeClass("fade top bottom left right in"),a.find(".popover-title").html()||a.find(".popover-title").hide()};
```

--------------------------------

### Importing BTLS Data with readBTLS

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/readBTLS.html

This snippet demonstrates how to initialize an edsurvey.data.frame by providing the paths to the BTLS fixed-width data file and the corresponding SPSS syntax file. The function processes the raw data and returns an object ready for analysis within the EdSurvey framework.

```R
fld <- "~/EdSurveyData/BTLS"
datPath <- file.path(fld, "ASCII Data File", "BTLS2011_12.dat")
spsPath <- file.path(fld, "Input Syntax for Stata and SPSS", "BTLS2011_12.sps")

# Read in the data to an edsurvey.data.frame
btls <- readBTLS(datPath, spsPath, verbose = TRUE)

# Check dimensions of the resulting object
dim(btls)
```

--------------------------------

### Initialize Bootstrap Transition Support

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/README.html

This snippet detects browser support for CSS transitions and provides a fallback mechanism to trigger transition-end events. It ensures that components requiring animation can reliably detect when a transition has completed.

```javascript
function b(){var a=document.createElement("bootstrap"),b={WebkitTransition:"webkitTransitionEnd",MozTransition:"transitionend",OTransition:"oTransitionEnd otransitionend",transition:"transitionend"};for(var c in b)if(void 0!==a.style[c])return{end:b[c]};return!1}a.fn.emulateTransitionEnd=function(b){var c=!1,d=this;a(this).one("bsTransitionEnd",function(){c=!0});var e=function(){c||a(d).trigger(a.support.transition.end)};return setTimeout(e,b),this};
```

--------------------------------

### Usage of mergev for Verbose Data Merging

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/mergev.html

This snippet demonstrates the function signature for mergev. It highlights the primary arguments used to control the merge process, such as specifying join keys and output ordering.

```R
mergev(x, y, by = NULL, by.x = NULL, by.y = NULL, all.x = NULL, all.y = NULL, all = FALSE, order = c("sort", "unsorted", "x", "y"), fast = FALSE, merge.type.colname = "merge.type", return.list = FALSE, verbose = TRUE, showWarnings = TRUE, ...)
```

--------------------------------

### Recode variable levels using recode.sdf

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/recode.sdf.html

This example demonstrates how to use the recode.sdf function to change the levels of the 'itsex' variable from 'MALE' and 'FEMALE' to 'BOY' and 'GIRL' respectively within a TIMSS dataset.

```R
usaG4.15 <- readTIMSS(path="~/TIMSS/2015", "usa", 4)
d <- getData(usaG4.15, "itsex")
summary(d)
usaG4.15 <- recode.sdf(usaG4.15,
                       recode = list(itsex=list(from=c("MALE"),
                                                to=c("BOY")),
                                     itsex=list(from=c("FEMALE"),
                                                to=c("GIRL"))))
d <- getData(usaG4.15, "itsex")
summary(d)
```

--------------------------------

### Perform Quantile Regression with rq.sdf

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/rq.sdf.html

This snippet demonstrates how to load survey data using readNAEP and perform a quantile regression analysis at a specific tau value using the rq.sdf function.

```R
sdf <- readNAEP(path=system.file("extdata/data", "M36NT2PM.dat", package = "NAEPprimer"))
rq1 <- rq.sdf(formula=composite ~ dsex + b017451, data=sdf, tau = 0.8)
summary(rq1)
```

--------------------------------

### Rename variables in an EdSurvey data frame

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/rename.sdf.html

This example demonstrates how to load a TIMSS dataset and rename specific variables ('itsex' to 'gender' and 'mmat' to 'math_overall') to facilitate subsequent analysis using linear models.

```R
usaG4.15 <- readTIMSS(path="~/TIMSS/2015", "usa", 4)
usaG4.15.renamed <- rename.sdf(x=usaG4.15,
                               oldnames=c("itsex", "mmat"),
                               newnames=c("gender", "math_overall"))
lm1 <- lm.sdf(formula=math_overall ~ gender, data = usaG4.15.renamed)
summary(lm1)
```

--------------------------------

### Import NHES Survey Data

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/readNHES.html

Demonstrates how to import NHES SPSS data files into an EdSurvey object. It includes examples for importing multiple files and explicitly setting survey codes when automatic detection is insufficient.

```R
rootPath <- "~/"
# Import all files to edsurvey.data.frame.list object
filesToImport <- list.files(path = file.path(rootPath, "NHES", c(2012, 2016)), pattern="\\.sav$", full.names = TRUE, recursive = TRUE)
esdfList <- readNHES(savFiles = filesToImport, surveyCode = "auto", forceReread = FALSE, verbose = TRUE)

# Explicitly setting the surveyCode parameter
path_ates2016 <- list.files(path = file.path(rootPath, "NHES", "2016"), pattern=".*ates.*[.]sav$", full.names = TRUE)
esdf <- readNHES(savFiles = path_ates2016, surveyCode = "ATES_2016", forceReread = FALSE, verbose = TRUE)

# Search for variables in the edsurvey.data.frame
searchSDF(string="sex", data=esdf)
```

--------------------------------

### Constructing an edsurvey.data.frame object

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/edsurvey-class.html

Initializes an edsurvey.data.frame object to store survey metadata and link to on-disk data. This constructor requires various parameters such as weights, plausible values, and survey-specific identifiers to ensure correct statistical calculations.

```R
edsurvey.data.frame(userConditions, defaultConditions, dataList = list(), weights, pvvars, subject, year, assessmentCode, dataType, gradeLevel, achievementLevels, omittedLevels, survey, country, psuVar, stratumVar, jkSumMultiplier, recodes = NULL, validateFactorLabels = FALSE, forceLower = TRUE, reqDecimalConversion = TRUE, fr2Path = NULL, dim0 = NULL, cacheDataLevelName = NULL)
```

--------------------------------

### Calculate Weighted Correlations using cor.sdf

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/cor.sdf.html

Demonstrates how to compute Pearson, Spearman, and Polychoric correlations using the cor.sdf function. It includes examples of handling categorical variables, applying weights, and filtering data subsets.

```R
sdf <- readNAEP(path=system.file("extdata/data", "M36NT2PM.dat", package = "NAEPprimer"))

# Calculate different correlation methods
c1_pears <- cor.sdf(x="b017451", y="b003501", data=sdf, method="Pearson", weightVar="origwt")
c1_spear <- cor.sdf(x="b017451", y="b003501", data=sdf, method="Spearman", weightVar="origwt")
c1_polyc <- cor.sdf(x="b017451", y="b003501", data=sdf, method="Polychoric", weightVar="origwt")

# Recoding variables before correlation
cor.sdf(x="c046501", y="c044006", data=sdf, method="Spearman", weightVar="origwt",
        recode=list(c046501=list(from="0%",to="None"),
                    c044006=list(from=c("1-5%", "6-10%", "11-25%", "26-50%", "51-75%", "76-90%", "Over 90%"),
                                 to="Between 0% and 100%")))
```

--------------------------------

### Download NHES Data Instructions

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/downloadNHES.html

Displays instructions for manually downloading NHES data files. This function is intended to guide users through the process of obtaining the correct SPSS format files required for further analysis in EdSurvey.

```R
# View instructions to manually download NHES data
downloadNHES()
```

--------------------------------

### Read ECLS-K:2011 Data and Suggest Weights

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/suggestWeights.html

This snippet demonstrates how to load an ECLS-K:2011 data file using the readECLS_K2011 function and subsequently identify appropriate survey weights for specific analysis variables using suggestWeights. It requires the data file path, layout file, and target variable names as inputs.

```R
eclsk11 <- readECLS_K2011(path=file.path("~/", "ECLS_K", "2011"), filename = "childK5p.dat", layoutFilename = "ECLSK2011_K5PUF.sps", verbose = FALSE)

# suggest weight for individual variable
suggestWeights(varnames="x8mscalk5", data=eclsk11)

# suggest weight for multiple variables
suggestWeights(varnames=c("x8mscalk5", "x_chsex_r", "x12sesl"), data=eclsk11)
```

--------------------------------

### R: Linear Model Fitting with EdSurvey

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/lm.sdf.html

Demonstrates fitting linear regression models using the `lm.sdf` function in R, which is designed for complex survey data. It shows how to specify different variance estimation methods (`varMethod`), handle factor levels (`relevels`), and recode variables. The function can also utilize plausible values as predictors.

```R
if (FALSE) { # \dontrun{
    # read in the example data (generated, not real student data)
    sdf <- readNAEP(path=system.file("extdata/data", "M36NT2PM.dat", package = "NAEPprimer"))
    
    # by default uses jackknife variance method using replicate weights
    lm1 <- lm.sdf(formula=composite ~ dsex + b017451, data=sdf)
    lm1
    
    # the summary function displays detailed results
    summary(lm1)
    
    # to show standardized regression coefficients
    summary(lm1, src=TRUE)
    
    # to specify a variance method, use varMethod
    lm2 <- lm.sdf(formula=composite ~ dsex + b017451, data=sdf, varMethod="Taylor")
    lm2
    summary(lm2)
    
    # use relevel to set a new omitted category
    lm3 <- lm.sdf(formula=composite ~ dsex + b017451, data=sdf, relevels=list(dsex="Female"))
    summary(lm3)
    # test of a simple joint hypothesis
    waldTest(lm3, "b017451")
    
    # use recode to change values for specified variables
    lm4 <- lm.sdf(formula=composite ~ dsex + b017451, data=sdf,
                  recode=list(b017451=list(from=c("Never or hardly ever",
                                                  "Once every few weeks",
                                                  "About once a week"),
                                           to=c("Infrequently")),
                              b017451=list(from=c("2 or 3 times a week","Every day"),
                                           to=c("Frequently"))))
    # Note: "Infrequently" is the dropped level for the recoded b017451
    summary(lm4)
    
    # use plausible values as predictors in a linear regression model
    lm5 <- lm.sdf(formula=algebra ~ dsex + geometry, data=sdf)
    lm5
    summary(lm5)
    } # } 
```

--------------------------------

### Calculate Covariance Between Regression Coefficients

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/varEstToCov.html

This example demonstrates how to use varEstToCov to calculate the covariance between two regression coefficients from an EdSurvey model. It also shows how to use this covariance to calculate the standard error of the difference between the two coefficients.

```R
sdf <- readNAEP(path=system.file("extdata/data", "M36NT2PM.dat", package = "NAEPprimer"))
lm1 <- lm.sdf(formula=composite ~ dsex + b017451, data=sdf, returnVarEstInputs=TRUE)
jkSumMultiplier <- EdSurvey:::getAttributes(data=sdf, attribute="jkSumMultiplier")
covFEveryDay <- varEstToCov(varEstA=lm1$varEstInputs,
                            varA="dsexFemale",
                            varB="b017451Every day",
                            jkSumMultiplier=jkSumMultiplier)
# Calculate standard error of the difference
sqrt(lm1$coefmat["dsexFemale", "se"]^2
     + lm1$coefmat["b017451Every day", "se"]^2
     - 2 * covFEveryDay)
```

--------------------------------

### Download ePIRLS Data

Source: https://github.com/american-institutes-for-research/edsurvey/blob/main/docs/reference/download_ePIRLS.html

Demonstrates how to use the download_ePIRLS function to retrieve assessment data. The function requires a root directory and supports parameters for caching processed files and controlling console output verbosity.

```R
# Basic download for 2016 data
download_ePIRLS(years=2016, root = "~/")

# Download with caching enabled for faster future access
download_ePIRLS(years=2016, root = "~/", cache = TRUE)

# Download with silent output
download_ePIRLS(root="~/", verbose = FALSE)
```