Skip to content

koza

Usage:

$ koza [OPTIONS] COMMAND [ARGS]...

Options:

  • --version
  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • transform: Transform a source file.
  • join: Join multiple KGX files into a unified...
  • load: Load KGX node/edge files into a DuckDB as-is.
  • split: Split a KGX file by specified fields with...
  • schema-export: Export the koza graph schema from a DuckDB...
  • closurize: Apply closure expansion to a merged graph:...
  • information-content: Compute information-content and...
  • annotation-information-content: Compute annotation-based information...
  • pairwise-similarity: All-by-all term similarity (Jaccard,...
  • profile: Profile the shape of a graph: schema-smart...
  • prune: Prune graph by removing dangling edges and...
  • append: Append new KGX files to an existing graph...
  • normalize: Apply SSSOM mappings to normalize edge...
  • canonicalize: Repair CURIE prefixes with alternate...
  • merge: Complete merge pipeline: join → normalize...
  • report: Generate comprehensive reports for KGX...
  • node-report: Generate tabular node report with GROUP BY...
  • edge-report: Generate tabular edge report with...
  • node-examples: Generate sample rows per node type.
  • edge-examples: Generate sample rows per edge type.
  • export: Write a koza DuckDB graph's nodes/edges...
  • convert: One-shot KGX file format conversion (=...
  • biolink-check: Check a graph against Biolink type...

koza transform

Transform a source file.

Accepts either a config YAML file or a Python transform file directly.

Examples: # With config file (existing behavior) koza transform config.yaml

# Config-free mode with transform file (shell expands the glob)
koza transform transform.py -o ./output -f jsonl data/*.yaml

# With output options
koza transform transform.py -f jsonl -o ./output data/*.yaml

# Explicit input format
koza transform transform.py --input-format yaml data/*.dat

# CSV with comma delimiter (default for .csv files)
koza transform transform.py data/*.csv

# TSV with explicit delimiter
koza transform transform.py -d '\t' data/*.txt

Usage:

$ koza transform [OPTIONS] {config_or_transform} [input_files]...

Arguments:

  • config_or_transform: Configuration YAML file OR Python transform file [required]
  • input_files...: Input files (required for .py transforms, supports shell glob expansion)

Options:

  • --input-format <csv|jsonl|json|yaml>: Input format (auto-detected if not specified)
  • -o, --output-dir <str>: Path to output directory [default: ./output]
  • -f, --output-format <tsv|jsonl|kgx|passthrough>: Output format [default: tsv]
  • -n, --limit <int>: Number of rows to process (if skipped, processes entire source file) [default: 0]
  • -p, --progress: Display progress of transform
  • -q, --quiet: Disable log output
  • -v, --verbose: Enable debug-level logging (e.g. per-row 'filtered out' messages)
  • -d, --delimiter <str>: Field delimiter for CSV/TSV files (default: tab for .tsv, comma for .csv)
  • --help: Show this message and exit.

koza join

Join multiple KGX files into a unified DuckDB database

Examples: # Auto-discover files in directory koza join --input-dir tmp/ -o graph.duckdb

# Use glob patterns
koza join -n &quot;tmp/*_nodes.tsv&quot; -e &quot;tmp/*_edges.tsv&quot; -o graph.duckdb

# Mix directory discovery with additional files
koza join --input-dir tmp/ -n extra_nodes.tsv -o graph.duckdb

# Multiple individual files
koza join -n file1.tsv -n file2.tsv -e edges.tsv -o graph.duckdb

Usage:

$ koza join [OPTIONS]

Options:

  • -n, --nodes <str>: Node files or glob patterns (can specify multiple)
  • -e, --edges <str>: Edge files or glob patterns (can specify multiple)
  • -d, --input-dir <str>: Directory to auto-discover KGX files
  • -o, --output <str>: Path to output database file (default: in-memory)
  • -f, --format <tsv|jsonl|parquet>: Output format for any exported files [default: tsv]
  • --schema-report: Generate schema compliance report
  • --required-node-field <str>: Node fields that must be present and non-empty (can specify multiple)
  • --required-edge-field <str>: Edge fields that must be present and non-empty (can specify multiple)
  • --slots-file <str>: YAML file with {nodes: [...], edges: [...]} — sets explicit JSONL schema, skipping inference. JSON keys NOT in the slot list are silently dropped at read time.
  • --force-single-valued <str>: Collapse this Biolink-multivalued slot to a scalar, keeping only the first array element (repeatable). Default: none — Biolink multivalued slots are preserved as arrays. Pass e.g. --force-single-valued category for the historical Monarch convention.
  • -q, --quiet: Suppress output
  • -p, --progress: Show progress bars [default: True]
  • --help: Show this message and exit.

koza load

Load KGX node/edge files into a DuckDB as-is.

The first step of a build, on its own: bring a knowledge graph that is already represented as node and edge files into nodes / edges tables, ready for analysis or downstream operations (closurize, report) — without the deduplicate / normalize / prune stages that merge runs.

Unlike join (cat-merge style), load preserves an existing provided_by instead of overwriting it with the source filename. Pass --generate-provided-by to opt into the filename-stamping behavior.

Examples: # Load a KG represented as one nodes file and one edges file koza load -n graph_nodes.jsonl -e graph_edges.jsonl -o graph.duckdb

# Auto-discover from a directory
koza load --input-dir kg/ -o graph.duckdb

Usage:

$ koza load [OPTIONS]

Options:

  • -n, --nodes <str>: Node files or glob patterns (can specify multiple)
  • -e, --edges <str>: Edge files or glob patterns (can specify multiple)
  • -d, --input-dir <str>: Directory to auto-discover KGX files
  • -o, --output <str>: Path to output database file (default: in-memory)
  • -f, --format <tsv|jsonl|parquet>: Output format for any exported files [default: tsv]
  • --slots-file <str>: YAML file with {nodes: [...], edges: [...]} — sets explicit JSONL schema, skipping inference. JSON keys NOT in the slot list are silently dropped at read time.
  • --required-node-field <str>: Node fields that must be present and non-empty (can specify multiple)
  • --required-edge-field <str>: Edge fields that must be present and non-empty (can specify multiple)
  • --generate-provided-by: Overwrite provided_by with the source filename (cat-merge style). Off by default: load preserves any existing provided_by.
  • --schema-report: Generate schema compliance report
  • -q, --quiet: Suppress output
  • -p, --progress: Show progress bars [default: True]
  • --help: Show this message and exit.

koza split

Split a KGX file by specified fields with format conversion support

Usage:

$ koza split [OPTIONS] {file} {fields}

Arguments:

  • file: Path to the KGX file to split [required]
  • fields: Comma-separated list of fields to split on [required]

Options:

  • -o, --output-dir <str>: Output directory for split files [default: ./output]
  • -f, --format <tsv|jsonl|parquet>: Output format (default: preserve input format)
  • --remove-prefixes: Remove prefixes from values in filenames
  • -q, --quiet: Suppress output
  • -p, --progress: Show progress bars [default: True]
  • --help: Show this message and exit.

koza schema-export

Export the koza graph schema from a DuckDB as a YAML release artifact.

By default, the wide post-closurize classes are renamed to Entity / Association (matching monarch-app's convention) and the narrow post-merge classes are dropped. Use --raw to preserve the full internal naming — note that downstream consumers (monarch-app's import target, lsolr create-schema invocations) expect the projected names, so --raw output isn't drop-in compatible with the default downstream toolchain.

Usage:

$ koza schema-export [OPTIONS] {database}

Arguments:

  • database: Path to a koza-built DuckDB containing _koza_schema [required]

Options:

  • -o, --output <str>: Path to write the exported schema YAML [required]
  • --raw: Export the schema as-is (DenormalizedEntity/DenormalizedAssociation preserved). Default is to project denormalized classes to consumer-facing Entity/Association names.
  • --help: Show this message and exit.

koza closurize

Apply closure expansion to a merged graph: produce denormalized_nodes and denormalized_edges, evolve the stored schema to include DenormalizedEntity and DenormalizedAssociation classes.

Examples: # Monarch-style: expand subject/object/disease-context with full closure, # label-only expansion for the qualifier fields, has_phenotype per-node # aggregation. koza closurize graph.duckdb -c phenio-relation-filtered.tsv \ --edge-field subject --edge-field object \ --edge-field disease_context_qualifier \ --edge-field-to-label species_context_qualifier \ --edge-field-to-label stage_qualifier \ --edge-field-to-label sex_qualifier \ --edge-field-to-label onset_qualifier \ --edge-field-to-label frequency_qualifier \ --node-field has_phenotype \ --additional-node-constraints "e.negated IS NULL OR e.negated = false OR e.negated = 'False'"

Usage:

$ koza closurize [OPTIONS] {database}

Arguments:

  • database: Path to the DuckDB database file to closurize [required]

Options:

  • -c, --closure-file <str>: Path to the relation-graph TSV file (subject_id, predicate_id, object_id). Omit to build denormalized views without closure: no *_closure / _closure_label slots and no node-level has_descendant slots.
  • --node-field <str>: Predicate to expand into per-node aggregations (repeatable)
  • --edge-field <str>: Edge field to fully expand (label + category + namespace + closure) (repeatable)
  • --edge-field-to-label <str>: Edge field to expand with label/category/namespace only — no closure (repeatable)
  • --additional-node-constraints <str>: SQL WHERE-clause fragment applied to per-predicate node aggregation joins. Reference edges columns via the alias e (e.g. e.negated IS NULL).
  • -q, --quiet: Suppress output
  • --help: Show this message and exit.

koza information-content

Compute information-content and closure-size tables for a closurized graph.

Reads the closure table produced by closurize plus the edges table, and writes two tables a downstream similarity engine can read instead of rebuilding per process:

information_content (term, ic) -- information content per closure term closure_size (entity, size) -- distinct closure subsumers per entity

closure_size covers every entity with an association-predicate edge, so genotypes, variants and cases get sizes alongside genes and diseases.

Run after closurize.

Examples: # Defaults: rdfs:subClassOf closure, every has_phenotype entity koza information-content monarch-kg.duckdb

# Custom closure predicate, narrowed to one association category
koza information-content graph.duckdb \
    --closure-predicate rdfs:subClassOf --closure-predicate BFO:0000050 \
    --association-category biolink:GeneToPhenotypicFeatureAssociation \
    --association-predicate biolink:has_phenotype

Usage:

$ koza information-content [OPTIONS] {database}

Arguments:

  • database: Path to an already-closurized DuckDB database file [required]

Options:

  • --closure-predicate <str>: Closure predicate(s) that define ancestry for IC / closure-size (repeatable). Default: rdfs:subClassOf
  • --association-category <str>: Narrow the closure-size table to these edge categories (repeatable). Default: no category filter — every entity with an association-predicate edge gets a size, whatever its category
  • --association-predicate <str>: Edge predicate for entity->term associations. Default: biolink:has_phenotype
  • --include-negated: Include negated associations in the closure-size table (default: excluded)
  • -q, --quiet: Suppress output
  • --help: Show this message and exit.

koza annotation-information-content

Compute annotation-based information content into a named table.

IC(t) = -log2(n(t) / N): n(t) = distinct entities annotated to t or a closure descendant of t, N = distinct annotated entities (oaklib's information-content --use-associations). Run once per annotation corpus.

Run after closurize.

Examples: # mouse gene -> MP corpus koza annotation-information-content monarch-kg.duckdb \ --output-table information_content_mgi_mp \ --association-category biolink:GeneToPhenotypicFeatureAssociation \ --subject-prefix MGI --object-prefix MP

Usage:

$ koza annotation-information-content [OPTIONS] {database}

Arguments:

  • database: Path to an already-closurized DuckDB database file [required]

Options:

  • --output-table <str>: Table to write (term, ic), e.g. information_content_mgi_mp [required]
  • --association-category <str>: Edge category making up the annotation corpus (repeatable, required), e.g. biolink:GeneToPhenotypicFeatureAssociation [required]
  • --subject-prefix <str>: Keep associations whose subject has this CURIE prefix (repeatable), e.g. MGI
  • --object-prefix <str>: Keep associations whose object has this CURIE prefix (repeatable), e.g. MP
  • --association-predicate <str>: Edge predicate for entity->term associations. Default: biolink:has_phenotype
  • --closure-predicate <str>: Closure predicate(s) that define ancestry (repeatable). Default: rdfs:subClassOf
  • --include-negated: Include negated associations in the corpus (default: excluded)
  • -q, --quiet: Suppress output
  • --help: Show this message and exit.

koza pairwise-similarity

All-by-all term similarity (Jaccard, Resnik, Phenodigm) between two term sets.

Semsimian's all_by_all_pairwise_similarity, computed in DuckDB over the closure. Pairs are kept when Resnik (max IC of a shared ancestor, from --ic-table) is strictly above the threshold.

Run after closurize and an IC operation (e.g. annotation-information-content).

Examples: koza pairwise-similarity monarch-kg.duckdb -o HP_vs_MP.parquet \ --ic-table information_content_mgi_mp \ --subject-root HP:0000118 --subject-prefix HP \ --object-root MP:0000001 --object-prefix MP

Usage:

$ koza pairwise-similarity [OPTIONS] {database}

Arguments:

  • database: Closurized DuckDB database (opened read-only) [required]

Options:

  • -o, --output <str>: Output file: .parquet, .tsv or .tsv.gz [required]
  • --ic-table <str>: Table of (term, ic) to score shared ancestors, e.g. information_content_mgi_mp [required]
  • --subject-root <str>: Subject terms: descendants of this term [required]
  • --object-root <str>: Object terms: descendants of this term [required]
  • --subject-prefix <str>: Keep subject terms with this CURIE prefix (repeatable)
  • --object-prefix <str>: Keep object terms with this CURIE prefix (repeatable)
  • --min-ancestor-information-content <float>: Keep pairs whose Resnik score is strictly greater [default: 1.5]
  • --closure-predicate <str>: Closure predicate(s) defining ancestry (repeatable). Default: rdfs:subClassOf
  • --no-labels: Skip the label columns
  • --batch-size <int>: Subject terms per SQL batch; peak memory grows with it, so lower it for large term sets [default: 500]
  • --memory-limit <str>: DuckDB memory limit, e.g. 64GB (set it under SLURM / CI)
  • --threads <int>: DuckDB threads
  • -q, --quiet: Suppress output
  • --help: Show this message and exit.

koza profile

Profile the shape of a graph: schema-smart categorical breakdowns.

Renders per-column marginal distributions (counts by predicate, category, namespace, knowledge source, ...) for each table. Which columns are "categorical" is auto-detected from the Biolink schema (enums, the category designator, knowledge-source/type slot families) plus a DuckDB cardinality probe — so it adapts to whatever graph you point it at, not a fixed list.

Examples: koza profile graph.duckdb koza profile graph.duckdb -t denormalized_edges --top 15 koza profile graph.duckdb -o shape.parquet -f parquet

Usage:

$ koza profile [OPTIONS] {database}

Arguments:

  • database: Path to the DuckDB database file to profile [required]

Options:

  • -t, --table <str>: Table(s) to profile (repeatable). Default: auto-detect nodes / edges / denormalized_* that are present.
  • -c, --column <str>: Override auto-detection — profile exactly these columns (repeatable).
  • -n, --top <int>: Top values to show per column [default: 10]
  • --max-distinct <int>: Cardinality cap for treating a column as categorical [default: 50]
  • --max-ratio <float>: Or distinct/row-count ratio cap for categorical [default: 0.01]
  • -o, --output <str>: Also write long-form (table, column, value, count) to a file
  • -f, --format <tsv|parquet|jsonl>: Format for --output [default: tsv]
  • -q, --quiet: Suppress the rendered summary
  • --help: Show this message and exit.

koza prune

Prune graph by removing dangling edges and handling singleton nodes

Examples: # Keep singleton nodes, move dangling edges koza prune graph.duckdb

# Remove singleton nodes to separate table
koza prune graph.duckdb --remove-singletons

# Experimental: filter small components
koza prune graph.duckdb --min-component-size 10

Usage:

$ koza prune [OPTIONS] {database}

Arguments:

  • database: Path to the DuckDB database file to prune [required]

Options:

  • --keep-singletons: Keep singleton nodes in main table
  • --remove-singletons: Move singleton nodes to separate table
  • --min-component-size <int>: Minimum connected component size (experimental)
  • -q, --quiet: Suppress output
  • -p, --progress: Show progress bars [default: True]
  • --help: Show this message and exit.

koza append

Append new KGX files to an existing graph database

Examples: # Append specific files to existing database koza append graph.duckdb -n new_nodes.tsv -e new_edges.tsv

# Auto-discover files in directory and append
koza append graph.duckdb --input-dir new_data/

# Append with deduplication and schema reporting
koza append graph.duckdb -n &quot;*.tsv&quot; --deduplicate --schema-report

Usage:

$ koza append [OPTIONS] {database}

Arguments:

  • database: Path to existing DuckDB database file [required]

Options:

  • -n, --nodes <str>: Node files or glob patterns (can specify multiple)
  • -e, --edges <str>: Edge files or glob patterns (can specify multiple)
  • -d, --input-dir <str>: Directory to auto-discover KGX files
  • --deduplicate: Remove duplicates during append
  • --schema-report: Generate schema compliance report
  • -q, --quiet: Suppress output
  • -p, --progress: Show progress bars [default: True]
  • --help: Show this message and exit.

koza normalize

Apply SSSOM mappings to normalize edge subject/object references

This operation loads SSSOM mapping files and applies them to rewrite edge subject and object identifiers to their canonical/equivalent forms. Node identifiers themselves are not changed - only edge references are normalized.

Examples: # Apply specific mapping files koza normalize graph.duckdb -m gene_mappings.sssom.tsv -m mondo.sssom.tsv

# Auto-discover SSSOM files in directory
koza normalize graph.duckdb --mappings-dir ./sssom/

# Apply mappings with glob pattern
koza normalize graph.duckdb -m &quot;*.sssom.tsv&quot;

# Only apply exact matches, ignoring close/broad/narrow mappings
koza normalize graph.duckdb -m &quot;*.sssom.tsv&quot; --use-match skos:exactMatch

Usage:

$ koza normalize [OPTIONS] {database}

Arguments:

  • database: Path to existing DuckDB database file [required]

Options:

  • -m, --mappings <str>: SSSOM mapping files or glob patterns (can specify multiple)
  • -d, --mappings-dir <str>: Directory containing SSSOM mapping files
  • --use-match <str>: SSSOM predicate CURIE to apply, e.g. skos:exactMatch (can specify multiple). Default: apply every mapping regardless of predicate_id.
  • -q, --quiet: Suppress output
  • -p, --progress: Show progress bars [default: True]
  • --help: Show this message and exit.

koza canonicalize

Repair CURIE prefixes with alternate casing against a prefixmaps context

Rewrites node ids and edge subject/object references whose prefix matches a canonical prefix case-insensitively but not exactly (e.g. hgnc:746 -> HGNC:746). Each change is recorded in the prefix_canonicalization_log table. Prefixes unknown to the context are reported by koza report prefixes and never touched.

Only the nodes and edges tables are rewritten. Derived tables (closure, denormalized_*, mappings, ...) keep the old ids, so run this before closurize / denormalize, or rebuild them afterwards.

Examples: # Preview the repairs koza canonicalize graph.duckdb --dry-run

# Apply against the default merged context
koza canonicalize graph.duckdb

# Repair only one prefix
koza canonicalize graph.duckdb --only hgnc

# Preview, then repair and remove the duplicate node rows the repair creates
koza canonicalize graph.duckdb --dry-run --deduplicate
koza canonicalize graph.duckdb --deduplicate

# Use a different prefixmaps context
koza canonicalize graph.duckdb --context bioregistry.upper

Usage:

$ koza canonicalize [OPTIONS] {database}

Arguments:

  • database: Path to existing DuckDB database file [required]

Options:

  • -c, --context <str>: prefixmaps context to canonicalize against [default: merged]
  • --only <str>: Repair only this prefix (case-insensitive, e.g. --only hgnc); repeatable. Default: every prefix with alternate casing.
  • --deduplicate: Nodes only: remove rewritten node rows whose id duplicates an existing node, keeping the pre-existing row. Only acts on rows rewritten in this run, so pass it on the repair run itself. Edges are never deduplicated
  • --dry-run: Run everything and roll it back, reporting exact counts
  • -q, --quiet: Suppress output
  • --help: Show this message and exit.

koza merge

Complete merge pipeline: join → normalize → prune

This composite operation orchestrates the full graph processing pipeline: 1. Join: Load and combine multiple KGX files into a unified database 2. Normalize: Apply SSSOM mappings to edge subject/object references 3. Prune: Remove dangling edges and handle singleton nodes

The pipeline can be customized by skipping steps or configuring options.

Examples: # Full pipeline with auto-discovery koza merge --input-dir ./data/ --mappings-dir ./sssom/ -o clean_graph.duckdb

# Specific files with export
koza merge -n nodes.tsv -e edges.tsv -m mappings.sssom.tsv --export --export-dir ./output/

# Skip normalization, only join and prune
koza merge -n &quot;*.tsv&quot; -e &quot;*.tsv&quot; --skip-normalize -o graph.duckdb

# Custom singleton handling
koza merge --input-dir ./data/ -m &quot;*.sssom.tsv&quot; --remove-singletons

Usage:

$ koza merge [OPTIONS]

Options:

  • -n, --nodes <str>: Node files or glob patterns (can specify multiple)
  • -e, --edges <str>: Edge files or glob patterns (can specify multiple)
  • -m, --mappings <str>: SSSOM mapping files or glob patterns (can specify multiple)
  • -d, --input-dir <str>: Directory to auto-discover KGX files
  • --mappings-dir <str>: Directory containing SSSOM mapping files
  • -o, --output <str>: Path to output database file (default: temporary)
  • --export: Export final clean data to files
  • --export-dir <str>: Directory for exported files (required if --export)
  • -f, --format <tsv|jsonl|parquet>: Output format for exported files [default: tsv]
  • --archive: Export as archive (tar) instead of loose files
  • --compress: Compress archive as tar.gz (requires --archive)
  • --graph-name <str>: Name for graph files in archive (default: merged_graph)
  • --skip-normalize: Skip normalization step
  • --use-match <str>: SSSOM predicate CURIE to apply during normalization, e.g. skos:exactMatch (can specify multiple). Default: apply every mapping regardless of predicate_id.
  • --skip-prune: Skip pruning step
  • --keep-singletons: Keep singleton nodes (default) [default: True]
  • --remove-singletons: Move singleton nodes to separate table
  • --required-node-field <str>: Node fields that must be present and non-empty (can specify multiple)
  • --required-edge-field <str>: Edge fields that must be present and non-empty (can specify multiple)
  • --force-single-valued <str>: Collapse this Biolink-multivalued slot to a scalar during the join step, keeping only the first array element (repeatable). Default: none — Biolink multivalued slots are preserved as arrays.
  • -q, --quiet: Suppress output
  • -p, --progress: Show progress bars [default: True]
  • --help: Show this message and exit.

koza report

Generate comprehensive reports for KGX graph databases.

Available report types:

• qc: Quality control analysis by data source

• graph-stats: Comprehensive graph statistics (similar to merged_graph_stats.yaml)

• schema: Database schema analysis and biolink compliance

• connectivity: Connected component analysis (requires koza)

• prefixes: CURIE prefix census against a prefixmaps context

Examples:

# Generate QC report
koza report qc -d merged.duckdb -o qc_report.yaml

# Generate graph statistics
koza report graph-stats -d merged.duckdb -o graph_stats.yaml

# Generate schema report
koza report schema -d merged.duckdb -o schema_report.yaml

# Generate connectivity report with parquet sidecars
koza report connectivity -d merged.duckdb --output-dir cc_output/ -o cc_summary.yaml

# Census CURIE prefixes against the merged prefixmaps context
koza report prefixes -d merged.duckdb -o prefixes.yaml

# Quick QC analysis (console output only)
koza report qc -d merged.duckdb

Usage:

$ koza report [OPTIONS] {report_type}

Arguments:

  • report_type: Type of report: qc, graph-stats, schema, connectivity, or prefixes [required]

Options:

  • -d, --database <str>: Path to DuckDB database file [required]
  • -o, --output <str>: Path to output report file (YAML format)
  • --output-dir <str>: Directory for sidecar output files (used by connectivity report)
  • -q, --quiet: Suppress progress output
  • --context <str>: prefixmaps context (prefixes report only) [default: merged]
  • --help: Show this message and exit.

koza node-report

Generate tabular node report with GROUP BY ALL categorical columns.

Outputs count of nodes grouped by categorical columns (namespace, category, etc.).

Examples:

# From database
koza node-report -d merged.duckdb -o node_report.tsv

# From file
koza node-report -f nodes.tsv -o node_report.parquet --format parquet

# Custom columns
koza node-report -d merged.duckdb -o report.tsv -c namespace -c category -c provided_by

Usage:

$ koza node-report [OPTIONS]

Options:

  • -d, --database <str>: Path to DuckDB database file
  • -f, --file <str>: Path to node file (TSV, JSONL, or Parquet)
  • -o, --output <str>: Path to output report file
  • --format <tsv|parquet|jsonl>: Output format (default: infer from -o extension, else tsv)
  • -c, --column <str>: Categorical columns to group by (can specify multiple)
  • -q, --quiet: Suppress progress output
  • --help: Show this message and exit.

koza edge-report

Generate tabular edge report with denormalized node info.

Joins edges to nodes to get subject_category, object_category, etc., then outputs count of edges grouped by categorical columns.

With --set-column, switches to a kgxval-style "edge type shape" summary: one row per (subject_category, predicate, object_category, ...) group, with each set column reported as the distinct set of values that group spans.

Examples:

# From database
koza edge-report -d merged.duckdb -o edge_report.tsv

# From files
koza edge-report -n nodes.tsv -e edges.tsv -o edge_report.parquet --format parquet

# Custom columns
koza edge-report -d merged.duckdb -o report.tsv \
    -c subject_category -c predicate -c object_category -c primary_knowledge_source

# SPQO edge-type-shape summary with proportion + term sets
koza edge-report -d merged.duckdb -o summary.parquet --format parquet --proportion \
    -c subject_category -c predicate -c object_category \
    -s knowledge_level -s agent_type -s primary_knowledge_source

Usage:

$ koza edge-report [OPTIONS]

Options:

  • -d, --database <str>: Path to DuckDB database file
  • -n, --nodes <str>: Path to node file (for denormalization)
  • -e, --edges <str>: Path to edge file (TSV, JSONL, or Parquet)
  • -o, --output <str>: Path to output report file
  • --format <tsv|parquet|jsonl>: Output format (default: infer from -o extension, else tsv)
  • -c, --column <str>: Categorical columns to group by (can specify multiple)
  • -s, --set-column <str>: Slots to summarize as the distinct set of values per group instead of grouping on them (e.g. knowledge_level, agent_type, primary_knowledge_source). Switches to the SPQO 'edge type shape' summary.
  • -P, --percentile-column <str>: Numeric slots to summarize per group as &lt;slot&gt;_avg + &lt;slot&gt;_quantiles (list slots summarize element count, e.g. publications; numeric slots the value).
  • --proportion: Add a proportion column (group count / total edges).
  • -q, --quiet: Suppress progress output
  • --help: Show this message and exit.

koza node-examples

Generate sample rows per node type.

Samples N example rows for each distinct value in the type column (default: category).

Examples:

# From database (5 examples per category)
koza node-examples -d merged.duckdb -o node_examples.tsv

# From file with 10 examples per type
koza node-examples -f nodes.tsv -o examples.tsv -n 10

# Group by different column
koza node-examples -d merged.duckdb -o examples.tsv -t provided_by

Usage:

$ koza node-examples [OPTIONS]

Options:

  • -d, --database <str>: Path to DuckDB database file
  • -f, --file <str>: Path to node file (TSV, JSONL, or Parquet)
  • -o, --output <str>: Path to output examples file
  • --format <tsv|parquet|jsonl>: Output format (default: infer from -o extension, else tsv)
  • -n, --sample-size <int>: Number of examples per type [default: 5]
  • -t, --type-column <str>: Column to partition examples by [default: category]
  • -q, --quiet: Suppress progress output
  • --help: Show this message and exit.

koza edge-examples

Generate sample rows per edge type.

Samples N example rows for each distinct combination of type columns (default: subject_category, predicate, object_category).

Examples:

# From database (5 examples per edge type)
koza edge-examples -d merged.duckdb -o edge_examples.tsv

# From files with 10 examples
koza edge-examples -n nodes.tsv -e edges.tsv -o examples.tsv -s 10

# Custom type columns
koza edge-examples -d merged.duckdb -o examples.tsv -t predicate -t primary_knowledge_source

Usage:

$ koza edge-examples [OPTIONS]

Options:

  • -d, --database <str>: Path to DuckDB database file
  • -n, --nodes <str>: Path to node file (for denormalization)
  • -e, --edges <str>: Path to edge file (TSV, JSONL, or Parquet)
  • -o, --output <str>: Path to output examples file
  • --format <tsv|parquet|jsonl>: Output format (default: infer from -o extension, else tsv)
  • -s, --sample-size <int>: Number of examples per type [default: 5]
  • -t, --type-column <str>: Columns to partition examples by (can specify multiple)
  • -q, --quiet: Suppress progress output
  • --help: Show this message and exit.

koza export

Write a koza DuckDB graph's nodes/edges out as single KGX files.

The inverse of load/join: one file per table, no fragmentation (unlike split). For TSV, scalar multivalued columns are |-delimited and nested object columns (sources, ...) are written as JSON-in-cell; JSONL/Parquet keep nested data natively.

Examples: koza export graph.duckdb -o output/ -f tsv koza export graph.duckdb -o output/ -f jsonl

Usage:

$ koza export [OPTIONS] {database}

Arguments:

  • database: Path to the DuckDB graph to export [required]

Options:

  • -o, --output-dir <str>: Output directory [default: ./output]
  • -f, --format <tsv|jsonl|parquet>: Output format [default: tsv]
  • -q, --quiet: Suppress output
  • --help: Show this message and exit.

koza convert

One-shot KGX file format conversion (= load + export).

Loads the input file(s) into a temporary DuckDB and writes them back out in the requested format, applying the same serialization policy as export.

Examples: koza convert -e edges.jsonl -o output/ -f tsv koza convert -n nodes.jsonl -e edges.jsonl -o output/ -f parquet

Usage:

$ koza convert [OPTIONS]

Options:

  • -n, --nodes <str>: Node file(s) or glob(s)
  • -e, --edges <str>: Edge file(s) or glob(s)
  • -o, --output-dir <str>: Output directory [default: ./output]
  • -f, --format <tsv|jsonl|parquet>: Output format [default: tsv]
  • --slots-file <str>: YAML {nodes:[...], edges:[...]} explicit JSONL schema (skips inference)
  • -q, --quiet: Suppress output
  • --help: Show this message and exit.

Check a graph against Biolink type constraints (edge domain/range + node prefixes).

Two Biolink-driven checks, run as set-operations over the graph's own nodes/edges (no row iteration):

  • subobj_errors: where each edge type MISMATCHES the current Biolink model's domain/range — which may be a model gap as readily as a data error (Biolink is stricter than widely realized; the report is triage input, the edge count the signal). Edges that ASSERT their association class (the edge category slot) are checked against THAT class (BAD_SUBJECT / BAD_PREDICATE / BAD_OBJECT); others fall back to "is this triple legal at all" (NOT_IN_LEGAL_TYPES — advisory). At edge-type grain, so each mismatch carries its edge count.
  • prefix_errors: node CURIE prefix valid for its category.

Example: koza biolink-check graph.duckdb -o checks/

Usage:

$ koza biolink-check [OPTIONS] {database}

Arguments:

  • database: Path to the DuckDB database file to check [required]

Options:

  • -o, --output-dir <str>: Directory to write subobj_errors / prefix_errors tables
  • -f, --format <tsv|parquet|jsonl>: Output format [default: parquet]
  • -q, --quiet: Suppress summary output
  • --help: Show this message and exit.