liwca.Liwc22#

class liwca.Liwc22(*, encoding='utf-8', csv_delimiter=',', csv_escape=None, csv_quote='"', include_subfolders=True, skip_header=True, preprocess_cjk='none', url_regex=None, count_urls=True, precision=2, auto_open=True, use_gui=False, dry_run=False)[source]#

Bases: object

Wrapper around LIWC-22-cli.

Set cross-cutting options (encoding, CSV formatting, URL handling, precision, and execution-control flags) once at construction, then call the seven per-mode methods (wc, freq, mem, context, arc, ct, lsm) repeatedly. Each method takes only the kwargs specific to that mode - the hoisted options are injected automatically.

Can be used as a context manager to amortize the LIWC-22 app launch and shutdown across multiple calls when auto_open=True.

Parameters:

encoding (str, optional) – Input file encoding (default: "utf-8").
csv_delimiter (str, optional) – CSV delimiter (default: ","). Use "\t" for TSV inputs.
csv_escape (str, optional) – CSV escape character. None (default) means “no escape”; the flag is omitted from the CLI call.
csv_quote (str, optional) – CSV quote character (default: "). On Windows, the default value is silently omitted from the CLI call: LIWC-22-cli’s Java launcher re-escapes argv and mangles -quote " into swallowing subsequent flags. Since " is also the CLI’s default, omission matches the documented behaviour; any other value (e.g. "'") is emitted normally.
include_subfolders (bool, optional) – If True (default), include subfolders when analysing a directory input.
skip_header (bool, optional) – If True (default), skip the first row of an Excel/CSV file (i.e. treat it as a header). Setting False disables column-name resolution in the mode methods.
preprocess_cjk (str, optional) – Preprocess CJK text with Jieba (Chinese) or Kuromoji (Japanese) tokeniser - one of "chinese", "japanese", "none" (default).
url_regex (str, optional) – Regular expression used to capture URLs in text.
count_urls (bool, optional) – If True (default), count URLs as a single word. Only meaningful if url_regex is set.
precision (int, optional) – Number of decimal places in output (0-16, default: 2).
auto_open (bool, optional) – If LIWC-22 is not running, launch it before each analysis and close it afterwards (default True). Set to False to require that the app (or its license server) is already running.
use_gui (bool, optional) – When auto-opening, prefer the GUI app over the headless license server (default False).
dry_run (bool, optional) – Print each CLI command without executing it (default False).

Notes

The LIWC-22 desktop application (or its license server) must be running when you call the CLI.

See also

[LIWC CLI documentation](https://www.liwc.app/help/cli)
[LIWC CLI Python example](ryanboyd/liwc-22-cli-python)

Examples

>>> import liwca
>>> liwc = liwca.Liwc22(dry_run=True)
>>> liwc.wc("data.csv", "results.csv")

>>> with liwca.Liwc22() as liwc:
...     liwc.wc("data.csv", "wc.csv", text_columns="text")
...     liwc.freq("data.csv", "freq.csv", ngram=2)

Methods

`arc`(input, output, *[, text_columns, ...])	Analyse the narrative arc of texts.
`context`(input, output, *[, dictionary, ...])	Run LIWC-22 Contextualizer analysis.
`ct`(input, output, *, speakers[, ...])	Convert separate transcript files into a single spreadsheet.
`freq`(input, output, *[, text_columns, ...])	Compute word (and n-gram) frequencies across input texts.
`lsm`(input, output, *[, text_column, ...])	Run Language Style Matching (LSM) analysis.
`mem`(input, output, *[, text_columns, ...])	Run Meaning Extraction Method (MEM) analysis.
`wc`(input, output, *[, dictionary, ...])	Run a standard LIWC-22 word count analysis.

wc(input, output, *, dictionary='LIWC22', text_columns=None, id_columns=None, combine_columns=True, include_categories=None, exclude_categories=None, segmentation=None, output_format='csv', threads=None, text=None, env_var=None, clean_escaped_spaces=True)[source]#

Run a standard LIWC-22 word count analysis.

Scores each input text against a LIWC dictionary (default LIWC22) and reports per-category word counts or percentages.

Parameters:

input (str, Path, DataFrame, or Series) – Path to an input file/folder, a pandas.DataFrame, or a pandas.Series. DataFrame/Series input is written to a temp CSV, fed to LIWC-CLI, and the temp file is removed when the call returns. A DataFrame requires text_columns to identify the text column(s). A Series auto-wraps into a single-column frame using the Series name (or "text"). Use "console" with text or "envvar" with env_var to analyse literal text.
output (str or Path) – Output file/folder path, or "console".
dictionary (str, optional) – LIWC dictionary name (e.g. LIWC22, LIWC2015), path to a custom .dicx file, or one of the liwca.datasets.dictionaries friendly names (e.g. "sleep", "emfd", "bigtwo") - friendly names are auto-resolved to the cached local .dicx path (default: LIWC22).
text_columns (int, str, or iterable thereof, optional) – Columns containing analysable text. Each entry is either a 0-based integer index or a column-name string (requires the input to have a header row). A bare str or int is accepted for single-column selection. All columns processed by default (required for DataFrame input).
id_columns (int, str, or iterable thereof, optional) – Columns to use as row identifiers. Multiple columns are concatenated with ;. Defaults to row number.
combine_columns (bool, optional) – If True, combine spreadsheet columns into a single text per row (CLI default: True).
include_categories (str or iterable of str, optional) – Dictionary categories to include in output. Mutually exclusive with exclude_categories.
exclude_categories (str or iterable of str, optional) – Dictionary categories to exclude from output. Mutually exclusive with include_categories.
segmentation (str, optional) – Split text into segments. See the LIWC CLI documentation.
output_format (str, optional) – Output file format - one of csv, xlsx, ndjson (default: csv).
threads (int, optional) – Number of processing threads (default: available cores - 1).
text (str, optional) – Text string to analyse. Use with input="console".
env_var (str, optional) – Environment variable name containing text. Use with input="envvar".
clean_escaped_spaces (bool, optional) – With input="console": if True, escaped spaces like \n are converted to actual spaces (CLI default: True).

Returns:

The output path. On dry runs this is the path LIWC-22-cli would have written to - no file is created.

Return type:

str

Raises:

ValueError – If both include_categories and exclude_categories are set, or if input is a DataFrame without text_columns, or if input is an empty DataFrame, or if input is a DataFrame combined with text / env_var.
TypeError – If input / output are of the wrong type.
RuntimeError – If LIWC-22-cli exits with a non-zero status, or if LIWC-22 is not running and auto_open=False.

Notes

After LIWC-CLI writes the output CSV, the file is reshaped in place via wc_output_schema: row-id columns are renamed back to their source names, a constant "Segment" column is dropped, and the category columns sit under a column axis named "Category" when the file is loaded back into pandas.

Examples

>>> import pandas as pd
>>> df = pd.DataFrame({"doc_id": ["a", "b"], "text": ["hi", "bye"]})
>>> path = Liwc22().wc(
...     df,
...     "wc.csv",
...     text_columns="text",
...     id_columns="doc_id",
... )

freq(input, output, *, text_columns=None, combine_columns=True, conversion_list=None, stop_list='internal-EN', drop_words=5, ngram=1, trim_s=True, skip_wc=10, prune_interval=10000000, prune_threshold=5, output_format='csv')[source]#

Compute word (and n-gram) frequencies across input texts.

Parameters:

input (str, Path, DataFrame, or Series) – Path to input file/folder, a DataFrame (requires text_columns), or a Series (auto-wraps).
output (str or Path) – Output file/folder path, or "console".
text_columns (int, str, or iterable thereof, optional) – Columns containing analysable text. A bare str or int is accepted for single-column selection. All columns processed by default (required for DataFrame input).
combine_columns (bool, optional) – If True, combine spreadsheet columns into a single text per row (CLI default: True).
conversion_list (str, optional) – Path to a conversion list or an internal list name (e.g. internal-EN). Use "none" for no conversion.
stop_list (str, optional) – Path to a stop list, an internal list name (e.g. internal-EN), or "none" (default: internal-EN).
drop_words (int, optional) – Drop n-grams with frequency less than this value (default: 5).
ngram (int, optional) – N-gram size (1-5), inclusive of all lower n-grams (default: 1).
trim_s (bool, optional) – If True, trim trailing 's from words (CLI default: True).
skip_wc (int, optional) – Skip texts with word count less than this value (default: 10).
prune_interval (int, optional) – Prune frequency list every N words to optimise RAM (default: 10_000_000).
prune_threshold (int, optional) – Minimum n-gram frequency retained during pruning (default: 5).
output_format (str, optional) – Output file format - one of csv, xlsx, ndjson (default: csv).

Returns:

The output path.

Return type:

str

mem(input, output, *, text_columns=None, id_column=None, combine_columns=True, conversion_list=None, stop_list='internal-EN', ngram=1, trim_s=True, skip_wc=10, segmentation=None, threshold_type='min-obspct', threshold_value=10.0, enable_pca=False, save_theme_scores=False, column_delimiter=' ', prune_interval=10000000, prune_threshold=5, dtm_format='binary', output_format='csv')[source]#

Run Meaning Extraction Method (MEM) analysis.

Builds a document-term matrix over the input corpus and optionally runs Principal Component Analysis to surface latent themes.

Parameters:

input (str, Path, DataFrame, or Series) – Path to input file/folder, a DataFrame (requires text_columns), or a Series (auto-wraps).
output (str or Path) – Output file/folder path, or "console".
text_columns (int, str, or iterable thereof, optional) – Columns containing analysable text.
id_column (int or str, optional) – Column to use as row identifier.
combine_columns (bool, optional) – If True, combine spreadsheet columns into a single text per row.
conversion_list (str, optional) – Path to a conversion list or an internal list name.
stop_list (str, optional) – Path to a stop list, an internal list name, or "none" (default: "internal-EN").
ngram (int, optional) – N-gram size (1-5).
trim_s (bool, optional) – If True, trim trailing 's from words.
skip_wc (int, optional) – Skip texts with word count less than this value (default: 10).
segmentation (str, optional) – Split text into segments.
threshold_type (str, optional) – One of min-obspct (default), min-freq, top-obspct, top-freq.
threshold_value (float, optional) – Threshold cutoff value (default: 10.0).
enable_pca (bool, optional) – Enable Principal Component Analysis (default False).
save_theme_scores (bool, optional) – Save the theme-scores table for PCA (default False).
column_delimiter (str, optional) – Delimiter between grams in n-gram column names (default: space).
prune_interval (int, optional) – RAM-pruning controls (defaults: 10_000_000 and 5).
prune_threshold (int, optional) – RAM-pruning controls (defaults: 10_000_000 and 5).
dtm_format (str, optional) – Document-term matrix format - one of binary (default), relative-freq, or raw-counts.
output_format (str, optional) – One of csv, xlsx, ndjson (default: csv).

Return type:

str

context(input, output, *, dictionary='LIWC22', text_columns=None, id_column=None, combine_columns=True, category=None, word_list=None, words=None, word_window=3, keep_punctuation=True)[source]#

Run LIWC-22 Contextualizer analysis.

Extracts the surrounding context (configurable window of words to the left and right) for each occurrence of a target word or dictionary category.

Parameters:

input (str, Path, DataFrame, or Series) – Path to input file/folder, a DataFrame (requires text_columns), or a Series (auto-wraps).
output (str or Path) – Output file/folder path, or "console".
dictionary (str, optional) – LIWC dictionary name, path to a custom .dicx file, or a liwca.datasets.dictionaries friendly name (e.g. "sleep", "emfd", "bigtwo") - friendly names are auto-resolved to the cached local .dicx path.
text_columns (int, str, or iterable thereof, optional) – Columns containing analysable text.
id_column (int or str, optional) – Column to use as row identifier.
combine_columns (bool, optional) – If True, combine spreadsheet columns into a single text per row.
category (str, optional) – Dictionary category to contextualise (default: first category).
word_list (str, optional) – Path to a word list file for contextualisation.
words (str or iterable of str, optional) – Words to contextualise. Wildcards (*) allowed.
word_window (int or 2-tuple of int, optional) – Number of context words around the target word. An int sets the same window on both sides; a (left, right) tuple sets them independently (default: 3, i.e. 3 words on each side).
keep_punctuation (bool, optional) – If True, include punctuation in context items (CLI default: True).

Return type:

str

arc(input, output, *, text_columns=None, id_column=None, combine_columns=True, n_segments=5, scaling='percent', skip_wc=10, include_data_points=True, output_format='csv')[source]#

Analyse the narrative arc of texts.

Scores how a text’s narrative trajectory (staging, plot progression, cognitive tension) varies across segments.

Parameters:

input (str, Path, DataFrame, or Series) – Path to input file/folder, a DataFrame (requires text_columns), or a Series (auto-wraps).
output (str or Path) – Output file/folder path, or "console".
text_columns (int, str, or iterable thereof, optional) – Columns containing analysable text.
id_column (int or str, optional) – Column to use as row identifier.
combine_columns (bool, optional) – If True, combine spreadsheet columns into a single text per row.
n_segments (int, optional) – Number of segments to divide text into (default: 5).
scaling (str, optional) – Scaling method - "percent" (default, 0-100 scale) or "zscore" (Z-score).
skip_wc (int, optional) – Skip texts with word count less than this value (default: 10).
include_data_points (bool, optional) – If True, output individual data points (CLI default: True).
output_format (str, optional) – One of csv, xlsx, ndjson (default: csv).

Return type:

str

ct(input, output, *, speakers, remove_regex=None, min_turns=0, min_words=10, single_line=False)[source]#

Convert separate transcript files into a single spreadsheet.

Parameters:

input (str or Path) – Path to a transcript file or folder. DataFrame/Series input is not supported - ct operates on raw transcripts.
output (str or Path) – Output file/folder path, or "console".
speakers (str) – Path to a text/csv/xlsx file containing a list of speakers.
remove_regex (str, optional) – Regex pattern; first match is removed from each line.
min_turns (int, optional) – Omit speakers with fewer turns than this value (default: 0).
min_words (int, optional) – Omit speakers with word count less than this value (default: 10).
single_line (bool, optional) – Don’t combine untagged lines with the previous speaker (default False).

Return type:

str

lsm(input, output, *, text_column=None, person_column, group_column=None, level='both', segmentation=None, min_turns=0, min_words=10, single_line=False, pairwise=False, expanded=False, output_format='csv')[source]#

Run Language Style Matching (LSM) analysis.

Computes how closely speakers align in their use of function words, either person-to-person or within groups.

Parameters:

input (str, Path, DataFrame, or Series) – Path to input file/folder, a DataFrame (requires text_column), or a Series (auto-wraps; text_column auto-filled).
output (str or Path) – Output file/folder path, or "console".
text_column (int or str, optional) – Column containing the text. Required for non-Series input.
person_column (int or str) – Person ID column.
group_column (int or str, optional) – Group ID column. None (the default) means “no groups”.
level (str, optional) – Analysis level - "person", "group", or "both" (default).
segmentation (str, optional) – Split text into segments.
min_turns (int, optional) – Skip speakers with fewer turns / words than these thresholds (defaults: 0, 10).
min_words (int, optional) – Skip speakers with fewer turns / words than these thresholds (defaults: 0, 10).
single_line (bool, optional) – Don’t combine untagged lines with the previous speaker (default False).
pairwise (bool, optional) – If True, compute pairwise LSM between every pair of speakers; if False (default), compute one-to-many LSM.
expanded (bool, optional) – Include expanded LSM output (default False).
output_format (str, optional) – One of csv, xlsx, ndjson (default: csv).

Return type:

str

liwca.Liwc22

On this page

liwca.Liwc22#