Skip to content

Data Linking Commands

Jump to bottom
Bell Eapen edited this page Jan 29, 2026 · 2 revisions

Data Linking Commands

Linking is the core powerful feature of CRISP-T. It connects your unstructured text documents (e.g., interviews, field notes) to structured numeric data (e.g., demographics, survey scores, timestamps). This enables "triangulation"—analyzing text in the context of numbers, and vice versa.

Linking commands are split between crisp (standard matching) and crispt (advanced time/embedding strategies).

1. Keyword & ID Linking (crisp)

These are the standard linking methods used during analysis commands with the --linkage flag.

ID Linking

Links a document to a DataFrame row if the document's ID matches a value in the DataFrame's id column. Best for surveys where each row has a corresponding text response.

crisp --inp ./corpus --linkage id --outcome score --regression

Keyword Linking

Links a document to a DataFrame row if the document contains a specific keyword. This is the default if --linkage is not specified but is often less precise than ID linking.

2. Temporal Linking (crispt)

Time-based analysis. Link documents to data points based on timestamps. Requires:

  1. Documents must have a valid timestamp in their metadata.
  2. Dataframe must have a time column.

Use crispt --temporal-link "method:column:param".

Method: Nearest

Links each document to the single DataFrame row with the closest timestamp.

# Link to nearest row based on 'created_at' column
crispt --inp ./corpus --temporal-link "nearest:created_at" --out ./linked

Method: Window

Links each document to all DataFrame rows within a specified time window (before and after the document timestamp).

# Link to all events within ±300 seconds (5 mins) of the document
crispt --inp ./corpus --temporal-link "window:timestamp_col:300" --out ./linked

Method: Sequence

Links documents to periods (e.g., weeks, months). Useful for longitudinal studies.

# Link weekly (W)
crispt --inp ./corpus --temporal-link "sequence:date_col:W" --out ./linked

3. Embedding Linking (crispt)

Semantic analysis. Link documents to DataFrame rows based on vector similarity. This assumes your DataFrame rows also have some text representation (or you are linking documents to other documents that underpin the rows).

Use crispt --embedding-link "metric:top_k:threshold".

  • Metric: cosine or euclidean.
  • Top_k: Number of links to create per document (e.g., link to the top 1 most similar row).
  • Threshold: Minimum similarity score (0.0 to 1.0).
# Link each document to its top 1 most similar data row, if similarity > 0.7
crispt --inp ./corpus --embedding-link "cosine:1:0.7" --out ./linked

4. Manual Relationships (crispt)

You can manually define relationships between any two data points (text or numeric) to build a knowledge graph.

crispt --inp ./corpus --add-rel "first|second|relation"

Example

# Define that the concept "anxiety" correlates with the variable "heart_rate"
crispt --inp ./corpus --add-rel "text:anxiety|numb:heart_rate|correlates"

Verifying Links

To check what links exist in your corpus:

  • --relationships: List all defined relationships.
  • --embedding-stats: Show statistics for embedding links.

Clone this wiki locally