pathofetch 0.1.0

Download SNP matrices from NCBI Pathogen Detection

Pathofetch

Lightweight CLI and Python tool for downloading SNP cluster data from NCBI Pathogen Detection (PD).

Installation

From PyPI

pip install pathofetch

From source

git clone https://github.com/erinyoung/pathofetch.git
cd pathofetch
pip install -e .

Usage

Pathofetch requires two arguments: an organism group and a SNP cluster ID (as defined by NCBI Pathogen Detection).
It will download the corresponding tarball for the SNP tree and generate a pairwise SNP distance matrix.

By default:

• The SNP matrix is saved to {cluster_id}.snp_distance_matrix.csv.
• The raw tarball is saved to {cluster_id}.tar.gz.

Example

pathofetch -o Salmonella -c PDS000254123.2

Custom Output Filename

# specify CSV matrix
pathofetch -o Salmonella -c PDS000254123.2 -f results/matrix.csv
# generate qc file
pathofetch -o Salmonella -c PDS000254123.2 -q

Python API Usage

It is possible to import pathofetch into other Python scripts to build larger bioinformatics pipelines.

import pathofetch

# -----------------------------
# Download and process a single SNP cluster
# -----------------------------
# Returns True on success, False on failure
success = pathofetch.fetch_snp_matrix(
    organism="Listeria_monocytogenes",    # Organism group on NCBI PD
    cluster_id="PDS000000123.5",          # SNP cluster ID
    out_file="results/matrix.csv",        # Where to save the SNP distance matrix
    tar_file="archives/raw_data.tar.gz",  # Optional: save tarball to custom location
    qc_file_arg="AUTO"                     # Generate QC file alongside output
)

if success:
    print("Matrix generated successfully!")
    print("Matrix CSV: results/matrix.csv")
    print("Tarball: archives/raw_data.tar.gz")
    print("QC stats: PDS000000123.5.qc.csv (auto-named)")
else:
    print("Failed to generate SNP matrix. Check organism and cluster ID.")

Output Format

The output is a standard CSV symmetric matrix representing pairwise SNP distances.

-,PDT003080107.1,PDT002963418.1,PDT003087591.1
PDT003080107.1,0,12,5
PDT002963418.1,12,0,8
PDT003087591.1,5,8,0

QC Statistics File

If using the -q flag, a CSV file is generated with the following structure:

key,value
pathofetch_version,0.1.0
download_time,2.21s
organism_group,Aeromonas_salmonicida
cluster,PDS000097767.14
cluster_create_date,Feb 4 11:28
num_sample,87
snp_alignment_length,612
min_pairwise_distance,0
max_pairwise_distance,104
avg_pairwise_distance,50.46
tarball_file,PDS000097767.14.tar.gz
tarball_filesize,0.81 MB
snp_matrix_file,PDS000097767.14.snp_distance_matrix.csv
qc_file,PDS000097767.14.qc.csv

Arguments

usage: pathofetch [-h] [--version] [--organism ORGANISM] [--cluster CLUSTER] [--out-file OUT_FILE] [--tar-file TAR_FILE]
                  [--qc-file [QC_FILE]]

Download SNP Cluster Distance Matrices

options:
  -h, --help            show this help message and exit
  --version, -v         show program's version number and exit
  --organism ORGANISM, -o ORGANISM
                        Organism Group (e.g. Salmonella)
  --cluster CLUSTER, -c CLUSTER
                        Cluster ID (e.g. PDS000254123.2)
  --out-file OUT_FILE, -f OUT_FILE
                        Path to save output CSV
  --tar-file TAR_FILE, -t TAR_FILE
                        Path to save tar.gz
  --qc-file [QC_FILE], -q [QC_FILE]
                        Save QC metrics to file

License

GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007