LIWC-22 CLI

The LIWC-22 Command Line Interface

NOTE: The Command Line Interface for LIWC-22 is only available to academic users.

What is the LIWC-22 CLI?

Academic licenses for LIWC-22 come with a brand new command line interface (CLI): that is, a "companion" application that allows you to run most LIWC-22 analyses (including LIWC, MEM, Contextualizer, and more) from the command line or terminal of your operating system. The CLI makes it easy for users to integrate their LIWC analyses into their typical workflow and analytic pipelines. For example, it is now possible to run LIWC analyses directly from Python or R, ensuring that you get LIWC output that aligns perfectly with what you would receive from the GUI version of the application.

Getting Started

In order to call the LIWC-22 CLI, you must first run one of the two following applications:

  • The LIWC-22 desktop application (the GUI-based desktop application that you all know and love)
  • The LIWC-22 license validation application (a command line tool released with v1.10.0 and later)

Once you have opened either of the above, the CLI can be called to access its analytic functions. In either case, you simply need to run the application of your choice, then the CLI will connect to your preferred application. Notably, the LIWC-22 license validation application is designed to make life much, much easier for folks who need to use LIWC in a "headless" type of environment (e.g., a remote server, HPC environments, etc.).

By default, the LIWC-22 CLI and the LIWC-22 License Validatin Application are added to your OS environment when you install LIWC-22. This means that you should not need to add either to your "PATH" environment variable manually, and you should be able to call LIWC-22-license-server and/or LIWC-22-cli directly from your command line/terminal immediately following installation without any additional steps. Otherwise, the LIWC-22 CLI can be called like a typical executable program by navigating to its installation folder or, alternatively, calling it using its absolute path.

Performance Recommendations

For the best performance, we recommend calling upon the CLI to analyze text in as large of batches as possible. For example, if you have a corpus of 100,000 unique texts, you might pass those texts to the CLI in a one-by-one fashion — such as iterating over the collection of texts and issuing a unique CLI call for each text. However, such an approach will incur considerable overhead and, additionally, will not take advantage of LIWC-22's optimized word counting engine. If possible, we recommend grouping texts into a single file for analysis (e.g., a CSV file) or, if more feasible for your use case, as large of batches as reasonably possible. For example, batches of 1,000 texts will ultimately process exponentially faster (on a per-text basis) than batches of 100 texts, which will in turn process faster than batches of 10 texts, and so on.

Examples and Samples

The foundation of all LIWC-22 CLI calls is the --mode or -m argument. Once you have specificed a --mode, the CLI provides standard --help documentation for the various arguments for each function, including both required and optional arguments.

As a quick example: to get up and running with a basic LIWC Analysis (i.e., a "word count" or "wc" analysis in the CLI), you might pass the following call to the CLI to see a list of the ways in which you can use the word count function to analyze texts:

LIWC-22-cli --mode wc --help

If you want to analyze a folder full of texts files (e.g., .txt, .pdf) using the default LIWC-22 dictionary, you might use the following command:

LIWC-22-cli --mode wc --input "C:/Users/Ryan/Ryan's Embarrassingly Bad Poetry/texts" --output "C:/Users/Ryan/Ryan's Embarrassingly Bad Poetry/results/LIWC-22 Results.csv"

Calling the LIWC-22 CLI from Python

In general, we recommend running the LIWC-22-cli from python as a subprocess. Depending on your analytic pipeline, you may have preferred ways of accomplishing this task. However, we have provided a couple of examples of how this can be accomplished in the following script:
LIWC-22-cli_Example.py

Calling the LIWC-22 CLI from R

In R, there are a number of ways in which we can think about analyzing text with the LIWC-22 CLI. As with Python or any other approach, the most computationally efficient way of analyzing your text data with LIWC is to analyze all of your data with a single CLI call. That is to say: if you have all of your text data in a dataset, you will probably want to process the entire dataset in a single LIWC-22 CLI call, then read the resulting output into R as a dataframe (or your preferred object type).

However, this approach might feel a but unfamiliar to a lot of researchers that do not work with other programming languages, as this recommended approach deviates from how most people learn the R programming language (social scientists in particular). It is entirely possible to analyze texts using something like the apply() function — it just isn't as effective.

Lastly, an important note about building your own functions to interface with the LIWC-22 CLI. For many (perhaps most) R users: there's a good chance that you are used to accomplishing all tasks in R with single calls that apply() some function to each row of your dataset. As mentioned above, this is totally viable (albeit inefficient). However, note that most command lines/terminals have a limit on the number of characters that can be used in a single line. This means, for example, that you can not pass a 10,000-word text to your command line because it simply results in a command that is too long for the console to handle. This is another reason why, in general, we recommend using the LIWC-22 CLI to analyze text prior to reading your data into R.

We have provided a couple of examples of how you can issue calls to the LIWC-22 CLI from within R in the following script:
LIWC-22-cli_Example.R