CLI Guide

Complete guide to using the wosecopy command-line interface.

Overview

wosecopy provides a comprehensive CLI for all operations. All commands follow this pattern:

wosecopy COMMAND [ARGUMENTS] [OPTIONS]

Getting Help

# General help
wosecopy --help

# Command-specific help
wosecopy extract --help
wosecopy metrics --help

Common Workflows

Basic Analysis Pipeline

# 1. Extract concepts
wosecopy extract stories.csv -o results.csv

# 2. Calculate metrics
wosecopy metrics results.csv -o metrics.json

# 3. Visualize
wosecopy visualize results.csv -o graph.png --index 0

Research Workflow

# Extract concepts
wosecopy extract study_data.csv -o results.csv --language en

# Analyze by ratings
wosecopy analyze-ratings results.csv --rating-column creativity -o grouped.json

# Compare raters
wosecopy compare results.csv -r rating_h -r rating_j -r rating_k -o plots/

# Calculate unexpectedness
wosecopy unexpectedness results.csv --prompt-column prompt -o creativity.csv

# Export graphs for network analysis
wosecopy export results.csv -o graphs/ --format graphml

Command Reference

See CLI Module for detailed command reference.

Examples

Extract with Custom Settings

wosecopy extract german_stories.csv \
    -o results_de.csv \
    --language de \
    --text-column Text \
    --similarity-threshold 0.6

Export Multiple Formats

# GraphML for Gephi
wosecopy export results.csv -o graphs/graphml/ --format graphml

# GEXF for Gephi
wosecopy export results.csv -o graphs/gexf/ --format gexf

# GML for other tools
wosecopy export results.csv -o graphs/gml/ --format gml

Batch Processing

# Process multiple files
for file in data/*.csv; do
    wosecopy extract "$file" -o "results/$(basename $file)"
done

Tips and Tricks

Progress Bars

Most commands show progress bars by default. The extraction command uses tqdm for progress tracking.

Output Organization

Organize outputs by creating a clear directory structure:

mkdir -p outputs/{graphs,metrics,plots,results}

wosecopy extract data.csv -o outputs/results/concepts.csv
wosecopy metrics outputs/results/concepts.csv -o outputs/metrics/stats.json
wosecopy export outputs/results/concepts.csv -o outputs/graphs/
wosecopy compare ... -o outputs/plots/

Chaining Commands

Use command chaining for automated workflows:

wosecopy extract data.csv -o results.csv && \
wosecopy metrics results.csv -o metrics.json && \
wosecopy visualize results.csv -o graph.png

Troubleshooting

Model Not Found

If you see “Model not found” errors:

wosecopy download-model --language en --size lg

Column Not Found

Check your column names:

# Use head to inspect CSV
head -n 1 data.csv

# Then specify correct column
wosecopy extract data.csv --text-column YourColumnName

Empty Results

If extraction produces empty results:

Check that sentences are separated by periods
Verify the text column has actual content
Try lowering similarity threshold
Check the language setting matches your data