How to use a CSV with Pheno-Ranker

RoleUtility-assisted input

Accepted inputDelimited text table

ConfigurationGenerated by csv2pheno-ranker

Best forTabular categorical data

csv2pheno-ranker creates the JSON records and configuration required by Pheno-Ranker.

The companion csv2pheno-ranker command converts a CSV or TSV table into two files: a JSON array of records and a matching Pheno-Ranker configuration.

Categorical data

Pheno-Ranker compares categorical values. Convert continuous measurements into meaningful categories or ranges before using them in a comparison. The choice of ranges should be justified by the domain rather than selected only for the software.

Usage

Desktop

Open Tools > CSV/TSV, select your table, and check its delimiter and record identifier settings before running the conversion. When it finishes, select Use in analysis: Desktop carries both the converted JSON and its matching configuration into the cohort setup. Review the setup, then run the analysis.

Keep the generated JSON and configuration together if you export them for use outside Desktop.

CLI

Worked example

Convert a table

Suppose example.csv uses semicolons between columns and commas between values inside the Bar column:

Foo	Bar	Baz
foo1	bar1a,bar1b	baz1
foo2	bar2a,bar2b	baz2

The table has no unique row identifier. Convert it with:

csv2pheno-ranker -i example.csv --separator ';' --array-separator ',' --generate-primary-key --primary-key-name Id

Option	Meaning in this example
--separator ';'	Columns are separated by semicolons.
--array-separator ','	Values inside Bar are separated by commas.
--generate-primary-key	Create a unique identifier for every row.
--primary-key-name Id	Name the generated identifier field Id.

If the table already has a unique, single-value identifier column, omit --generate-primary-key and pass that column name with --primary-key-name.

Check the generated files

The command creates example.json:

[
  {
    "Bar": ["bar1a", "bar1b"],
    "Baz": "baz1",
    "Foo": "foo1",
    "Id": "PR_00000001"
  },
  {
    "Bar": ["bar2a", "bar2b"],
    "Baz": "baz2",
    "Foo": "foo2",
    "Id": "PR_00000002"
  }
]

It also creates example_config.yaml:

---
allowed_terms:
- Bar
- Baz
- Foo
- Id
indexed_terms:
- Bar
format: CSV
identity_paths:
  CSV:
    - Bar: Bar
primary_key: Id

The configuration records which field identifies each row and which columns can be compared. It also records that Bar contains multiple values.

Run Pheno-Ranker

Pass both generated files to the main CLI:

pheno-ranker -r example.json --config example_config.yaml

The default cohort output is matrix.txt. To omit columns from the comparison:

pheno-ranker -r example.json --config example_config.yaml --exclude-terms Id Foo

Always use the generated configuration when working with the converted JSON.

CSV data checks

• Use unique, non-empty column names.
• Use one consistent value for each category; for example, do not mix M and Male unless they intentionally represent different categories.
• .csv files use commas and .tsv files use tabs by default. Override that behavior with --separator when necessary.
• Use --array-separator only for columns containing multiple categorical values. Its default is |.
• When comparing tables from different cohorts, confirm that corresponding columns and category names use the same nomenclature.

CLI usage

Command reference

csv2pheno-ranker -i <input.csv> [options]

Option	Purpose
-i, --input <file>	Input CSV or TSV file.
--primary-key-name <name>	Existing identifier column, or name of a generated identifier.
--generate-primary-key	Generate an identifier when the table has none.
--separator, --sep <char>	Column delimiter; inferred from .csv or .tsv by default.
--array-separator <pattern>	Delimiter for multiple values inside a column; default is `
--output-dir <directory>	Directory for the generated JSON and YAML files.
--verbose	Report progress and output paths.
--debug <level>	Print debugging information from level 1 to 5.
--help	Print brief command help.
--man	Print the utility manual.
--version	Print the utility version.

By default, output files are written beside the input and use its basename. For example, cohort.tsv produces cohort.json and cohort_config.yaml.

Examples

Use default delimiters and an existing identifier column:

csv2pheno-ranker -i cohort.tsv --primary-key-name patient_id

Generate identifiers and write the results elsewhere:

mkdir output
csv2pheno-ranker -i example.csv --generate-primary-key --primary-key-name ID --output-dir output --separator ';' --array-separator ','

The converter loads the table into memory before writing JSON. Very large input files therefore require enough RAM for the complete converted dataset.

See the source utility README for standalone-script information, or Download & Installation for supported installation methods.