API reference

WealthMCA

Fitted indicator MCA model returned by fit_wealth. Stores named indicators, observed category levels, category proportions, scoring coefficients, retained eigenvalues, total inertia, missing-value policy, and orientation anchor. Treat its arrays as read-only. No survey data or identifiers are stored.

Add building ID information for alter1 and alter2 in a network DataFrame.

This function:

1. Joins respondent building IDs to both alter1 and alter2 columns
2. Creates a same_building indicator variable

Parameters:

• df: DataFrame containing alter1 and alter2 columns
• respondentdf: DataFrame containing name and buildingid columns
• return_df: Bool, if true returns the modified DataFrame (default: false)

Returns:

• The modified DataFrame if return_df is true, otherwise nothing

addneighbors!(df, nds, r, sl)

Description

For an input DataFrame, df, find the set of matching neighbors stored in nds for specified relationship, given by relname.

Neighbor properties, specified in sl, are added from DataFrame r.

addneighbors(cr, ndf4, rhv4, sl)

sl variables to select in rhv4.

    addnetworkdata!(df, ndf)

Description

Add the network data.

    addsymmetric!(con)

Description

Add a column to the con edgelist that indicates whether the ties are recipricated. (In constrast to using non-unique, this marks both directions.)

Also adds column indicating whether the alter appears as an ego.

Description

Apply the data standardization for all columns present in transforms.

    binarize!(cr, v)

Values == yes -> true; other values -> false. Missing values are retained as missing.

clean_connections(conns::Vector{DataFrame}, waves;
                  alter_source=false, same_village=true, removemissing=true)

Combine and clean connection tables in the same order as waves. Mutates inputs. alter_source=true keeps raw source code 1; same_village=true drops missing same-village indicators and keeps code 1. Source codes are then converted to labels. removemissing=true rejects remaining missing values in ego, alter, question, alter source, and relationship using disallowmissing!; it does not drop those rows. Required delivery columns must be present.

    clean_household(hh, waves; nokeymiss = true)

Clean the household level data. hh must be a vector of dataframes. Data must be ordered by and match waves.

ARGS ≡≡≡≡≡≡≡≡≡≡

• hh: a vector of DataFrames, with entries for each wave of the data.
• waves: indicate the wave of each DataFrame in the same order as resp.
• nokeymiss = true : whether to filter to not missing on key variables: village code and building id

    clean_ihr(cop, ihr)

Clean the Intellectual Humility Project and the cooperation experiment data. Possibly subject to change when the data is updated.

NOT adjusted for datasets with a limited set of requested variables.

    clean_microbiome(mb1, mb2)

Clean the microbiome data, retaining the union of cohort columns and filling absent values with missing. Adds cohort (1 or 2); this is not an HMB wave ID. Donation amounts accept integers or integer strings; absent donation columns are allowed.

ARGS ≡≡≡≡≡≡≡≡≡≡

• mb1: cohort 1 raw data
• mb2: cohort 2 raw data

clean_microbiome(tables::Vector{DataFrame}, administrations::AbstractVector;
                 nokeymiss=true, namedict=nothing)

Clean HMB administrations: 1 = cohort 1 baseline, 2 = cohort 1 follow-up, 3 = cohort 2. Preserves one row per (name, cohort, administration) and rejects duplicate observations. Missing person/village IDs are dropped only when nokeymiss=true. The two-table method maps to administrations [1, 3].

clean_outcomes(dfs, waves; codebook = nothing, namedict = nothing, study = "rct")

Clean outcome/treatment DataFrames for the selected study (default "rct").

Strips wave suffixes, combines waves, and renames respondent_master_id → name. If a codebook is provided, also:

• Classifies outcome columns by codebook outcome_type
• Recodes outcome columns to Union{Missing, Bool} via recode_outcome
• Categorizes village_code
• Converts resp_target, friend_treatment, household_target → Union{Missing, Bool}

codebook can be a NamedTuple from load_codebook() (preferred) or a bare DataFrame with columns variable_id and outcome_type (legacy).

clean_perception!(resp; namedict=nothing)

Mutate a prepared respondent table to rename and recode community-behavior perceptions, perceived approval, and related personal attitudes and behaviors. This is an optional transformation, not called by clean_respondent or the template.

Requires the historical raw question columns (without wave suffixes), prepared child and gender, and compatible response labels/types. Missing columns are not skipped. Several recodes interpret missing selections as false; review wave-specific eligibility and question polarity before analysis.

Use a copy of the input and retain that DataFrame after the call. The current return value is a variable-name vector, not the DataFrame. The function is not idempotent. namedict records output-to-source renames, not derived-variable lineage. See the Perception and norms guide for the full crosswalk and assumptions.

    clean_respondent(
        resp::Vector{DataFrame},
        waves;
        nokeymiss = false,
        onlycomplete = false,
        namedict = nothing
    )

Clean the respondent level data. resp must be a vector of dataframes. Respondent data, resp, must be ordered by and match waves.

Combines and processes.

ARGS ≡≡≡≡≡≡≡≡≡≡

• resp: a vector of DataFrames, with entries for each wave of the data.
• waves: indicate the wave of each DataFrame in the same order as resp.
• nokeymiss: if true, do not allow entries with missing values for [:villagecode, :gender, :dateofbirth, :buildingid]
• onlycomplete: only include completed surveys

code_variables!(df; cb = nothing)

Apply categorical coding to cleaned columns in df. Hardcoded levels reflect post-cleaning string values, which often differ from raw survey option labels in the codebook (different case, simplified wording). Use make_ordered_categorical from cb for new variables not yet listed here.

    constraint(g, i)

Description

Network constraint as defined in Burt (1993). Here, larger constraint implies fewer structural holes (and, on the theory, less social capital).

Currently defined only for unweighted (binary) graphs.

    distance_df(
        dst, csspath, vdst, vgr;
        a1 = :building_id_a1, a2 = :building_id_a2
    )

Description

N.B., a1 and a1 are whatever two node columns you want to find distances for (between the nodes).

    dyadconstraint(g, i, j)

Description

Constraint for (i,j), defined in Burt (1993).

fit_wealth(df; indicators, anchor, ndims=2, missing_policy=:error)

Fit unweighted indicator MCA using only the explicitly named categorical indicators. Numeric values are treated as category labels, not continuous data. anchor=(column=:tv, low=false, high=true) fixes dimension one's sign so replacing the low category with the high category increases the score, all else equal. Both categories must occur and have a nonzero contrast on dimension one. This orientation does not establish that the dimension measures wealth: inspect asset patterns and external diagnostics. Remaining dimensions use a deterministic sign.

Missing data error by default; missing_policy=:category explicitly treats missing as a category. Constant columns are retained (and contribute no variation). An error is raised if fewer than ndims nonzero dimensions exist. No imputation, quintiling, household-size weighting, or supplementary-variable fitting is done.

    groupdescribe(df, grpvars)

Separately describe each group (by grpvars) of df, and concatenate.

    grouppartition!(ndf, rr, v)

Details

ndf is a networkinfo DataFrame, with names and village_code populated.

Create a partition vector from names in ndf over characteristic v, using input information cr.

For use with modularity calculation. N.B. further post processing likely required to coerce values into consecutive and distinct integers for groups.

    hh_distances(css, hc)

Calculate and add household distances to the css data.

Writes .bson file.

    hhwave(hd, noupd; ids = ids, wave = 4)

Household data for a wave, with imputation except for noupd variables.

    household_distances(bdf4)

Description

Calculate the household distances to be matched into an edgelist-style DataFrame (below).

bdf4 is the household data (e.g., "hondurashouseholdsWAVE4_v2.csv").

    interlen(x, y)

Return the length of the intersecting elements.

    invillage_adjust(x, wi)

Adjust invillage based on imputation.

    irrelreplace!(cr, v; extra = String[])

values equal to any of ["Don't know", "Don't Know", "Dont_Know", "Refused", "Removed"] become missing. Pass extra for dataset-specific additions (e.g., ["NA"]).

joinndfcr!( df, ndf; name = :perceiver, rels = ["freetime", "personalprivate"] )

Description

Join ndf network info DataFrame to cr CSS DataFrame.

joinndfdf!(df, ndf; name = :name)

Description

Join network info DataFrame ndf to respondent-level DataFrame df. This is not a simple join because ndf must be row-expanded as it is joined.

ndf should be filtered appropriately to the same number of waves, and no more than one relationship.

    jointnetwork(con, net_name1, net_name2, new_name; add_symmetric = false)

ARGS

• con : connections data for multiple waves, villages. The function will filter to the relevant relationships (R and Q).
• net_name1 : first relationship (R)
• net_name2 : second relationship (Q)
• new_name : name for new joint relationship (W)

Description

Take two paired networks; e.g., borrow and lend money, and construct an edgelist (network) based on a compound relationship, for relationships R, Q and new relationship W: such that if (aRb) & (bQa), then aWb. The function will also note whether each (new) edge is (i) symmetric, and (ii) whether the alter in the edge also exists as an ego (N.B., using only the data in the new set. If you want to use the larger node-set run addsymmetric() on the full, combined, data). Return a dataframe with columns identical to con that contains the edges.

load_codebook(; path = <bundled codebook dir>)

Load the three machine-readable codebook CSVs and return a NamedTuple containing:

• variables, options, derivations — raw DataFrames
• gvariables, goptions — GroupedDataFrames keyed on [:study, :variable_id] for O(1) per-variable lookups
• gvar_by_type, gvar_by_level — GroupedDataFrames for type/level queries
• outcome_type_map — pre-built Dict{String,String} mapping base variable name to outcome_type, for unambiguous RCT classifications (compatibility view)
• outcome_type_index — classifications keyed by (study, base variable, wave); nothing denotes a wave-independent derivation

The bundled codebooks (at HondurasTools/codebook/) are the default. Pass path to override with an external directory.

Schema

• variables — one row per variable-wave; fields: study, variableid, wave, level, variabletype, questiontype, survey, repeatedquestion, questiontexten, ...
• options — one row per variable-wave-option; fields: study, variableid, wave, optioncode, labelen, labelenmale, labeles, labelesmale
• derivations — one row per derived/outcome variable; fields: study, variableid, outcometype, denominator, derivation, source_questions, notes

make_ordered_categorical(cb, variable_id, data_col; wave = nothing, study = "rct")

Build an ordered CategoricalArray for data_col using option labels from cb.options, sorted by option_code. With wave=nothing, every wave must have identical labels and ordering; otherwise specify a wave explicitly.

Intended for new variables not yet in code_variables!. For existing cleaned variables, verify that option labels match the cleaned values (raw labels may differ in case or wording from post-cleaning values).

    neighbordata(ndfw; additionals = nothing, flat = true)

Description

• additionals: additional variables to include from ndfw

Extract neighbor names from ndfw network info DataFrame.

    neighborprops!(
        nb::Vector{Vector{S}}, g::AbstractGraph; property = :name
    )

Description

Get the property for each neighbor, for each node in the graph.

    neighborprops!(
        nb::Vector{Vector{Vector{S}}}, gs::Vector{T}; property = :name
    )

Description

Get the property for each neighbor, for each node in the graph, for a vector of graphs.

    neighborprops(g::AbstractGraph, v::AbstractString; property = :name)

Description

Get the specified property for each neighbor of v, where v is the property of that node.

    neighborprops(g::AbstractGraph, v::Int; property = :name)

Description

Get the specified property for each neighbor of v, where v is the vertex index in the graph object.

    network_info!(ndf, gcx, mods)

Populate ndf with network information.

• mods requires complex input that isn't really set up yet

networkinfo( cx, cr; waves = [1,3,4], relnames = ["freetime", "personalprivate", "kin", "union", "any"], alter_source = "Census" )

Description

• cx: connections data
• rr = nothing: reference DataFrame for modularity calculations
• mods = nothing: Vector of variables in rr to calculate modularity over. currently, only works for binary variables with missing values.

Construct a DataFrame that contains network statistics and graph objects from an input edgelist. N.B. that the edgelist should include all possible edges, which is filtered to the desired number of relationships. The larger set is needed to capture nodes that exist but do not have any ties in a particular network. Full sets are stored in names_all.

N.B. that combination networks (and therefore relnames) is basically only usable as-is.

prepare_for_bson(df)

Convert problematic column types to BSON-compatible formats. Handles all InlineStrings variants and other problematic types.

    process_nvariable!(
        df::DataFrame, v::Union{Symbol, String}, stat::Function
    )

Description

Calculate number missing and a scalar statistic (e.g., the mean) over each entry of Vector{Union{Missing, Real}}

    prp(x; a=3, b=2)

Description

sum(x .== a)/(sum(x .== b) + sum(x .== a))

recode_outcome(vector; na = "NA", dk = 0, refused = 999)

Recode a raw survey outcome vector to Union{Missing, Bool}.

Handles both string columns (with "NA" values that force CSV.jl to parse as strings) and integer columns. The codebook convention is:

• na string → missing (not applicable / not surveyed)
• dk (default 0) → missing (don't know)
• refused (default 999) → missing (refused)
• 1 → false (negative outcome)
• 2 → true (positive outcome)

Uses boolvec for the final [1,2] → Bool conversion.

Respondent data for a wave, with imputation except for noupd variables.

    reversestandard(df, v, transforms)

Description

Reverse standardization for a column and a set of transforms. Non-mutating.

    reversestandard(x, v, transforms)

Description

Reverse standardization for a column and a set of transforms. Non-mutating.

    reversestandards!(df, vbls, transforms; digits = nothing)

Description

Reverse the data standardization for columns present in transforms and in vbls.

    reversestandards!(df, transforms; digits = nothing)

Description

Reverse the data standardization for all columns present in transforms.

    sa(a)

Skip missing and NaN. via Skipper.jl.

    sai(a)

Skip Inf and NaN. via Skipper.jl.

score_wealth(model::WealthMCA, df; unknown=:error)

Project rows onto a fitted MCA model without refitting or rescaling. Returns a matrix (rows by retained dimensions), preserving input order. New categories error by default. unknown=:missing returns missing for every dimension of an affected row. Missing values follow the model's policy; a missing category absent from the fitting data is an unseen category. Extra columns are ignored.

    stround(x; digits = 2)

Description

Return String rounded to d digits for numeric/integer.

    sunique(x)

Return sorted unique object.

    tiestrength(g, i, j)

Bidirectional measure

Using the ZScore convenience fn. to do UnitRange transformation

for use with StandardizedPredictors.jl

    tryindex(g::T, a, prop; alt = NaN)

Description

Try to return index from property for MetaGraph, return NaN otherwise.

    tuple_addinv(c)

Description

Replace tuple (v, v) with tuple (1-v, 1-v).

    unilen(x)

Return the number of unique elements.

upck(x)

Return the last element of a vector or give missing if length < 1.

variable_info(cb, varname; wave = nothing, study = "rct")

Return all rows in cb.variables for varname, optionally filtered by wave and study.

variable_options(cb, varname; wave = nothing, study = "rct")

Return option codes and labels for varname from cb.options, sorted by option_code.

Note: option_code reflects survey display order, which may differ from the desired analytical ordering for ordered categoricals. Use the returned labels as a starting point and reorder manually if needed.

variables_by_level(cb, level; study = "rct")

Return unique variable_ids at a given data level for the given study.

Levels: "respondent", "household", "village", "connection", "outcome"

variables_by_type(cb, vtype; study = "rct")

Return unique variable_ids where variable_type == vtype for the given study.

Common types: "survey", "derived", "admin", "treatment", "identifier", "outcome", "intro", "flag"

Village data for a wave, with imputation except for noupd variables.

wealth_indices(df; indicators, anchor, reference_wave=1,
               id=:building_id, wave=:wave, ndims=2,
               missing_policy=:error, unknown=:error)

Fit each wave independently and also fit one shared model on reference_wave. Returns (scores, wave_models, reference_model, reference_wave). scores retains input row order and ID/wave columns, with wealth_within_d1, wealth_common_d1, etc. Only common scores can be differenced across waves. Dimension one is oriented by anchor in every model; other dimensions have no wealth direction.

Requires nonmissing, unique (id, wave) keys. Each row has equal fitting weight. No data are mutated. For future waves, reuse the returned reference model with score_wealth; do not refit or standardize separately by wave.

write_wealth_indices(input_path; indicators, anchor,
    imputed_path=nothing, output_dir=dirname(input_path), reference_wave=1,
    missing_policy=:category, unknown=:error)

Replace the legacy R CSV workflow with Julia. Read prepared household indicators from input_path (and optionally imputed_path), calculate two MCA dimensions, and write wealth_index.csv (within-wave scores), wealth_index_reference.csv (common scores), and wealth_indices.csv (both, with explicit column names). The first two preserve the legacy columns building_id, wave, wealth_d1, wealth_d2, imputed. IDs are read as strings; NA and empty fields are missing. All fits complete before any outputs are written. Output files are overwritten.

Regular and imputed inputs are fitted separately, matching the old R workflow; their common scores are comparable across waves within each input version, not across the two versions. Returns the fitted regular and optional imputed results for reuse. Does not perform raw-survey cleaning or imputation.