Getting Started

Installation

Watch this video

• CRISP-T is a Python package that can be installed using pip and used from the command line. Your system should have Python 3.11 or higher and pip installed. You can download and install Python for your operating system here. Optionally, CRISP-T can be imported into Python scripts or Jupyter notebooks.

• uv is recommended, but not necessary.

• Installing packages in a virtual environment using pip and venv is recommended if you are not using uv.

Quickstart (uv or pip)

# Using uv (recommended for speed)
uv venv
uv pip install crisp-t[ml]

# Using pip directly
python -m venv .venv && source .venv/bin/activate
pip install crisp-t[ml]

Advanced (Optional - Skip to data preparation below)

Include machine learning features for numeric data analysis (Recommended):

pip install crisp-t[ml]

If you are doing only textual analysis, a minimal install is possible as below:

pip install crisp-t

In rare cases, you may need XGBoost for gradient boosting features (Optional):

pip install crisp-t[xg]

• Mac users need to install libomp: brew install libomp for XGBoost to work. (Needed only if you want to use XGBoost)

Data preparation

• Create a subdirectory (e.g. crisp_source) in your work directory.
• Copy all the textual data as .txt or .pdf files into this newly created directory. For example, each interview transcript is copied as a TXT or PDF file.
• Copy the numeric data as a single .csv file into this newly created directory. Please note that only one CSV file with numeric data is currently supported.
• Import data from crisp_source folder to crisp_input folder with: crisp --source crisp_source --out crisp_input. You may use any folder name.
• Some data sources (e.g. survey data) may only have a single CSV file with free-text columns. In that case, use: crisp --source crisp_source --unstructured <free_text_column_name>. This creates CRISP documents from the text column.
• Ignore warnings related to PDF files.
• Data is now imported to crisp_input.
• Use --inp crisp_input in all subsequent commands to use the imported dataset.
• You may save intermediary results into a different folder using --out option if required.

How to Run (Common Patterns)

# 1. Import
crisp --source crisp_source --out crisp_input

# 2. Textual exploration (topics + sentiment)
crisp --inp crisp_input --topics --assign --out crisp_input

# 3. Numeric + predictive (requires [ml] extras)
crisp --include relaxed,self_time,sleep_bal,time_dp,travel_time,home_env --kmeans

# 4. Visualization
crispviz --inp crisp_input --wordcloud --ldavis --out viz_out/

# 5. Semantic filtering (example keyword)
crisp --inp crisp_input --filters keywords=mask --topics

# 6. Triangulation inspection (metadata print)
crisp --inp crisp_input --print metadata --print decision_tree_accuracy
crisp --inp crisp_input --print metadata --print regression_coefficients