PLINKLiftOver

PLINKLiftOver is a utility enabling liftOver to work on genomics files from PLINK, allowing one to update the coordinates from one genome reference version to another.

Installation

PLINKLiftOver requires

Python 3.10
The command line version of liftOver, installed and on the system path
An appropriate chain file
The MAP file from a PLINK dataset

Install from pypi

pip install -U plinkliftover

or install the development version with

pip install -U git+https://github.com/milescsmith/plinkliftover.git

Usage

plinkliftover has three subcommands:

liftover: Fully convert the genomic coordinates from one version to another in a PLINK file
map2bed: Convert a PLINK MAP file to a BED file
bed2map: Convert a BED file to a MAP file

The latter two subcommands are most useful in situations where it is not possible to run the liftOver executable locally (i.e. you are on Windows) but can use UCSC's online version or you otherwise need/want a BED file.

liftover:

Usage: plinkliftover liftover [OPTIONS] MAPFILE CHAINFILE

  Converts genotype data stored in the PLINK PED+MAP format from one genome
  build to another, using liftOver.

Arguments:
  MAPFILE    The plink MAP file to `liftOver`.  [required]
  CHAINFILE  The location of the chain files to provide to `liftOver`.
             [required]

Options:
  --pedfile TEXT             Optionally remove "unlifted SNPs" from the plink
                             PED file after running `liftOver`.
  --datfile TEXT             Optionally remove 'unlifted SNPs' from a data
                             file containing a list of SNPs (e.g. for
                             --exclude or --include in `plink`)
  --prefix TEXT              The prefix to give to the output files.
  --liftoverexecutable TEXT  The location of the `liftOver` executable.
  -v, --version              Prints the version of the plinkliftover package.
  --help                     Show this message and exit.

For example

plinkliftover liftover updating.map hg19ToHg38.over.chain.gz --prefix updated

map2bed:

Usage: plinkliftover map2bed [OPTIONS] MAPFILE

  Convert genotype data stored in a PLINK MAP file into a BED file, allowing
  one to use the online version of liftOver should the local executable is
  unavailable

Arguments:
  MAPFILE  A PLINK MAP file.  [required]

Options:
  -o, --output PATH  Location to save BED file to.  If one is not provided,
                     then it will be saved to where the MAP file is.
  -v, --version      Prints the version of the plinkliftover package.
  --help             Show this message and exit.

bed2map:

Usage: plinkliftover bed2map [OPTIONS] BEDFILE

  Convert genotype data stored in a PLINK MAP file into a BED file, allowing
  one to use the online version of liftOver should the local executable is
  unavailable

Arguments:
  BEDFILE  A BED file.  [required]

Options:
  -o, --output PATH  Location to save MAP file to.  If one is not provided,
                     then it will be saved to where the BED file is.
  -v, --version      Prints the version of the plinkliftover package.
  --help             Show this message and exit.

Note!

By default, PLINK 2.0 does not use/create the required MAP file. It can be generated using PLINK 1.9 by

plink --bfile original --recode --out to_update

where original is the prefix for the bed/bim/fam files and to_update is the prefix to give the new files.

🛡 License

This project is licensed under the terms of the GNU GPL v3.0 license. See LICENSE for more details.

📃 Citation

@misc{plinkliftover,
  author = {Miles Smith <miles-smith@omrf.org>},
  title = {Awesome `plinkliftover` is a Python cli/package created with https://github.com/TezRomacH/python-package-template},
  year = {2021},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/milescsmith/plinkliftover}}
}

Credits

This project was generated with python-package-template.

milescsmith/PLINKLiftOver