childeswordfreq: Usage & Best Practices

2.1 Word lists for word_counts()

word_counts() accepts either:

• A .csv file with a column named word, or
• A character vector via the words argument.

If word_list_file = NULL and words = NULL, word_counts() enters “all-words” mode and counts every type in the selected slice.

# Prepare a temporary CSV with a `word` column
tmp_csv <- tempfile(fileext = ".csv")
write.csv(
  data.frame(word = c("go", "want", "think")),
  tmp_csv,
  row.names = FALSE
)

# Output path for the Excel workbook
out <- tempfile(fileext = ".xlsx")

# Run word_counts on a specific CHILDES slice
word_counts(
  word_list_file = tmp_csv,
  output_file = out,
  language = "eng",
  corpus = "Brown",
  age = c(24, 36),
  role = c("CHI", "MOT")
)

Requirements for .csv inputs:

• A single column .csv file.
• The column header must be exactly word.
• Each row must include one target item or pattern.
• Case matching is case-insensitive at the type level; token mode makes use of CHILDES gloss and MOR information.

2.2 CHILDES filters

All CHILDES filters (language, corpus, collection, age, sex, role, role_exclude) are passed directly to childesr. In practice:

• corpus and language names must match CHILDES conventions exactly.
• age is in months and can be a single value or c(min, max).
• role and role_exclude are speaker code(s), for example "CHI", "MOT", "FAT", "ADU".
• Any parameter left as NULL is interpreted as “no restriction” on that dimension.

Example: all English-language corpora, no restriction on age or role:

word_counts(
  word_list_file = tmp_csv,
  output_file = out,
  language = "eng",
  age = NULL,
  role = NULL
)

3.1 Morphology and Stems

In token mode, collapse = "stem" attempts to aggregate inflected variants under a single stem where MOR analysis supports it (for example “go”, “goes”, “going”, “went” under one stem).

Limitations:

• Stem assignment depends on the MOR tier and may vary across corpora.
• Some forms may remain distinct if they are not consistently tagged.

For analyses where inflection is theoretically important, users should inspect the resulting stems and, if necessary, operate on separate forms explicitly.

3.2 Part-of-Speech Filtering

The part_of_speech argument restricts counts to specific POS values in MOR (for example c("n","v")). This is only available in token mode and is useful for:

• Disambiguating homographs across categories.
• Excluding non-content items for certain analyses.

Users should verify POS behavior on a subset of items before relying on it in a large-scale analysis.

8.1 Practical Recommendations:

• Prototype queries with a very small word list before scaling up
• Restrict language, corpus, age, and role as tightly as your research question allows
• Enable caching for interactive exploration.

8.2 Caching

childeswordfreq includes optional disk caching to accelerate repeated queries during interactive work. Caching stores the results of remote CHILDES queries so that subsequent calls with the same arguments return immediately rather than re-downloading data.

What counts as “the same query”? Caching speeds up calls that hit the same CHILDES slice, meaning all of the following match exactly:

• language, corpus, collection
• age, sex, role, role_exclude
• Mode (type vs token) and token-mode settings (wildcard, collapse, part_of_speech, tier)

If any of these change, a new remote query is required and caching does not apply.

When this is useful: During development, analyses are regularly re-run when:

• Re‐running the same code chunks while debugging
• Knitting R Markdown files
• Restarting an R session and re-executing the script
• Testing changes to downstream processing
• Running examples or unit tests that call the same slice repeatedly

In practice, you may run the same CHILDES query dozens of times. Without caching, each run contacts the API and can take seconds to minutes. With caching, repeated runs are effectively instantaneous.

Typical speedup - First run: full CHILDES download (seconds to minutes) - Subsequent identical runs: near 0 seconds

This is a substantial benefit for workflows that involve frequent re-execution.

Usage

cwf_cache_enable()   # turn caching on for interactive exploration
# ...run exploratory word_counts() or phrase_counts() calls...
cwf_cache_disable()  # disable before final or published analyses

Final analyses should always be derived directly from the current CHILDES database, not from previously cached local data. Disabling caching ensures that the published output reflects up-to-date datasets.

To make analyses replicable:

• Archive the entire Excel workbook alongside analysis scripts
• Report at least:
  • Language, corpus (and/or collection)
  • Age range in months
  • Speaker roles included/excluded
  • Whether token mode was used (for example wildcards, stems, POS, MOR tier)
  • Whether counts are raw, normalized, or Zipf-scaled
  • Behavior for non-attested items (rows with 0 counts)

Template for Methods Section:

Lexical/phrasal frequencies were computed using the childeswordfreq R package (version X.Y.Z) through childesr (version A.B.C), querying the CHILDES database (version V). We analyzed language(s) L and corpus/corpora C, with an age range of [Amin, Amax] months. Target speaker roles included R, with excluded roles R_excl. Counts were obtained in [type/token] mode. [If token mode used:] We specified: [wildcards, stem collapsing, POS filters, MOR tier]. We applied normalization [per N tokens/Zipf scaling]. 

Adjust the placeholders to match the values recorded in your own outputs.