strprofiler 0.2.0

STRprofiler is a simple python utility to compare short tandem repeat (STR) profiles. In particular, it is designed to aid research labs in comparing models (e.g. cell lines & xenografts) generated from primary tissue samples to ensure contamination has not occurred. It includes basic checks for sample mixing and contamination.

STRprofiler is intended only for research purposes.

For each STR profile provided, STRprofiler will generate a sample-specific report that includes the following similarity scores as compared to every other profile:

Tanabe, AKA the Sørenson-Dice coefficient:

$$ score = \frac{2 * no.shared.alleles}{no.query.alleles + no.reference.alleles} $$

Masters (vs. query):

$$ score = \frac{no.shared.alleles}{no.query.alleles} $$

Masters (vs. reference):

$$ score = \frac{no.shared.alleles}{no.reference.alleles} $$

Amelogenin is not included in the score computation by default but can be included by passing the --score_amel flag.

Installation

STRprofiler is available on PyPI and can be installed with pip:

pip install strprofiler

Usage

STRprofiler can be run directly from the command line.

strprofiler -sm "SampleMap_exp.csv" -scol "Sample Name" -o ./strprofiler_output STR1.xlsx STR2.csv STR3.txt

Full usage information can be found by running strprofiler --help.

 Usage: strprofiler [OPTIONS] INPUT_FILES...   

 STRprofiler compares STR profiles to each other.  

╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --tan_threshold    -tanth   FLOAT        Minimum Tanabe score to report as potential matches in summary table. [default: 80]                          │
│ --mas_q_threshold  -masqth  FLOAT        Minimum Masters (vs. query) score to report as potential matches in summary table. [default: 80]             │
│ --mas_r_threshold  -masrth  FLOAT        Minimum Masters (vs. reference) score to report as potential matches in summary table. [default: 80]         │
│ --mix_threshold    -mix     INTEGER      Number of markers with >= 2 alleles allowed before a sample is flagged for potential mixing.                 |
|                                            [default: 3]                                                                                               │
│ --sample_map       -sm      PATH         Path to sample map in csv format for renaming. First column should be sample names as given                  |
|                                            in STR file(s),  second should be new names to assign. No header.                                          │
│ --database         -db      PATH         Path to an STR database file in csv, xlsx, tsv, or txt format.                                               │
│ --amel_col         -acol    TEXT         Name of Amelogenin column in STR file(s). [default: AMEL]                                                    │
│ --sample_col       -scol    TEXT         Name of sample column in STR file(s). [default: Sample]                                                      │
│ --marker_col       -mcol    TEXT         Name of marker column in STR file(s). Only used if format is 'wide'. [default: Marker]                       │
│ --penta_fix        -pfix                 Whether to try to harmonize PentaE/D allele spelling. [default: True]                                        │
│ --score_amel       -amel                 Use Amelogenin for similarity scoring. [default: False]                                                      │
│ --output_dir       -o       PATH         Path to the output directory. [default: ./STRprofiler]                                                       │
│ --version                                Show the version and exit.                                                                                   │
│ --help                                   Show this message and exit.                                                                                  │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Input Files(s)

STRprofiler can take either a single STR file or multiple STR files as input. These files can be csv, tsv, tab-separated text, or xlsx (first sheet used) files. The STR file(s) should be in either 'wide' or 'long' format. The long format expects all columns to map to the markers except for the designated sample name column with each row reflecting a different profile, e.g.:

The wide format expects a line for each marker for each sample, e.g.:

In this format, the marker_col must be specified. Only columns beginning with "Allele" will be used to parse the alleles for each sample/marker. Any other size or height columns will be ignored.

Output Files

STRprofiler generates two types of output files. The first is a summary file, which contains the top hits for each sample above the specified scoring thresholds. This file provides a useful overview in addition to a flag to identify samples with potential mixing for closer inspection. In the output directory, this file will be named full_summary.strprofiler.YYYYMMDD.HH_MM_SS.csv where the date and time are the time the program was run.

In addition to the marker columns, the summary file contains the following columns:

The second is a sample-specific comparison file, which contains the results of the comparison between the query sample and all other provided samples. These files are generated for each STR profile provided in the input file(s) and named after the query sample in question. For example, if the input file contains a sample named Sample1, the output file will be named Sample1.strprofiler.YYYYMMDD.HH_MM_SS.csv.

In addition to the marker columns, this output contains the following columns:

Database Comparison

STRprofiler can be also used to compare batches of samples against a larger database of samples.

strprofiler -db ExampleSTR_database.csv -o ./strprofiler_output STR1.xlsx

In this mode, inputs are compared against the database samples only, and not among themselves. Outputs will be as described above for sample input(s).

The STRprofiler App

New in v0.2.0 is strprofiler-app, a command that launches a Shiny application that allows for user queries against an uploaded or pre-defined database (provided with the -db parameter) of STR profiles.

This application can provide a convenient portal to a group's STR database and can be hosted on standard Shiny servers, Posit Connect instances, or ShinyApps.io.

An example of the application can be seen here.

Deploying an strprofiler App

Building an app for deployment to any of the above options is simple.

First, make your app.py file:

from strprofiler.shiny_app.shiny_app import create_app

database = "./tester_db.csv"
app = create_app(db=database)

If no database is provided, an example database included with the package will be used. This app can then be deployed to any of the above endpoints as one would with any other Shiny app.

Alternatively, one could export it as a shinylive app and host it on Github pages or similar.

Database Format

The database should be formatted as a samples by markers matrix and saved as a csv, tsv, tab-delimited txt, or xlsx file, the same format as for the standard strprofiler command, e.g:

Optionally, one may provide two metadata columns - "Center" and "Passage", which will be recognized as non-marker columns.

Contributing

You can contribute by creating issues to highlight bugs and make suggestions for additional features. Pull requests are also very welcome.

License

STRprofiler is released on the MIT license. You are free to use, modify, or redistribute it in almost any way, provided you state changes to the code, disclose the source, and use the same license. It is released with zero warranty for any purpose and the authors retain no liability for its use. Read the full license for additional details.

Reference

If you use strprofiler in your research, please cite the DOI:

Jared Andrews, Mike Lloyd, & Sam Culley. (2024). j-andrews7/strprofiler: v0.2.0 (v0.2.0). Zenodo. https://doi.org/10.5281/zenodo.7348386