Package: gpas
GPAS clientThe command line interface for the GPAS mycobacterial platform. The client enables privacy-preserving sequence data submission and retrieval of analytical output files. Prior to upload, sample identifiers are anonymised and human host sequences are removed. For the best experience, a multicore machine with 16GB of RAM running Linux or MacOS is recommended.InstallInstalling MinicondaIf a conda package manager is already installed, skip toInstalling the client, otherwise:LinuxIn a terminal console, install Miniconda, following instructions and accepting default options:curl-Ohttps://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bashMiniconda3-latest-Linux-x86_64.shMacOSThe client requires anx86_64conda installation. If your Mac has an Apple processor, disable or delete existingarm64conda installations before continuing.If your Mac has an Apple processor, using Terminal, firstly run:arch-x86_64zshInstall Miniconda using Terminal, following instructions and accepting default options:curl-Ohttps://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
bashMiniconda3-latest-MacOSX-x86_64.shInstalling or updating the clientIf using a Mac with an Apple processor, using Terminal, firstly run:arch-x86_64zshPerform the installation/upgrade:condacreate--yes-ngpas-cconda-forge-cbiocondahostile
condaactivategpas
pipinstallgpasTest:gpas --versionUsageEnsure that the conda environment is active:condaactivategpasHelpRungpas --helpfor an overview of CLI subcommands. For help with a specific subcommand, use e.g.gpas auth --helpAuthentication (gpas auth)You will need to authenticate the first time you use the client. Do this by runninggpas authand entering your username and password. A token will be saved automatically inside your home directory.gpas auth
Enter your username: bede.constantinides@ndm.ox.ac.uk
Enter your password: ***************Uploading samples (gpas upload)The upload subcommand performs metadata validation and client-side removal of human reads for each of your samples, before uploading sequences to the GPAS platform for analysis.gpasuploadtests/data/illumina.csvDuring upload, a mapping CSV is created (e.g.a5w2e8.mapping.csv) linking your local sample names with their randomly generated remote names. Keep this file safe, as it is useful for downloading and relinking results later.A 4GB human genome index is downloaded the first time you rungpas upload. If for any reason this is interrupted, simply run the upload command again. Upload will not proceed until the index has been downloaded and passed an integrity check.To retain the decontaminated FASTQ files uploaded to GPAS, include the optional--saveflag. To perform decontamination without uploading anything, use the optional--dry-runflag.Downloading files (gpas download)The download subcommand retrieves the output (and/or input) files associated with a batch of samples given a mapping CSV generated during upload, or one or more sample GUIDs. When a mapping CSV is used, by default downloaded file names are prefixed with the sample names provided at upload. Otherwise downloaded files are prefixed with the sample GUID.# Download the main reports for all samples in a5w2e8.mapping.csvgpasdownloada5w2e8.mapping.csv# Download the main and speciation reports for samples in a5w2e8.mapping.csvgpasdownloada5w2e8.mapping.csv--filenamesmain_report.json,speciation_report.json# Download the main report for one samplegpasdownload3bf7d6f9-c883-4273-adc0-93bb96a499f6# Download the main report for two samplesgpasdownload3bf7d6f9-c883-4273-adc0-93bb96a499f6,6f004868-096b-4587-9d50-b13e09d01882# Save downloaded files to a specific directorygpasdownloada5w2e8.mapping.csv--out-dirresults# Download input filesgpasdownloada5w2e8.mapping.csv--inputs--filenames""The complete list of--filenamesavailable for download varies by sample, and can be found in the Downloads section of sample view pages in the GPAS web portal.Querying sample metadata (gpas query)The query subcommand fetches either the processing status (gpas query status) or raw metadata (gpas query raw) of one more samples given a mapping CSV generated during upload, or one or more sample GUIDs.# Query the processing status of all samples in a5w2e8.mapping.csvgpasquerystatusa5w2e8.mapping.csv# Query the processing status of a single samplegpasquerystatus3bf7d6f9-c883-4273-adc0-93bb96a499f6# Query all available metadata in JSON formatgpasqueryrawa5w2e8.mapping.csvDownloading decontamination indexes (gpas download-index)The human genome index used for host decontamination is downloaded automatically when runninggpas uploadfor the first time. You may however trigger this manually by runninggpas download-index.SupportFor technical support, please open an issue or contactsupport@gpas.globalDevelopmentDevelopment installgitclonehttps://github.com/GlobalPathogenAnalysisService/cli.gitcdcli
condaenvcreate-y-fenvironment.yml
pipinstall--editable'.[dev]'pre-commitinstallUpdatinggitpulloriginmain
gpas--versionUsing an alternate hostThe stateless way (use--hostwith every command):gpasauth--hostdev.portal.gpas.world
gpasuploadsamples.csv--hostdev.portal.gpas.worldThe stateful way (no need to use--hostwith each command):export GPAS_HOST="dev.portal.gpas.world"Then, as usual:gpasauth
gpasuploadsamples.csvTo reset:unsetGPAS_HOSTInstalling a pre-release versioncondacreate--yes-ngpas-cconda-forge-cbiocondahostile
condaactivategpas
pipinstall--pregpasUsing a local development serverexportGPAS_HOST="localhost:8000"exportGPAS_PROTOCOL="http"To unset:unsetGPAS_HOSTunsetGPAS_PROTOCOLReleasing a new versionHaving installed an editabledevelopment environment(with pre-commit, pytest and flit):pytest# Bump version strings inside src/gpas/__init__.py AND Dockerfile# Use format e.g. 1.0.0a1 for pre-releases (following example of Pydantic)gittag0.0.0.# e.g.gitpushoriginmain--tags
flitbuild# Build packageflitpublish# Authenticate and upload package to PyPI# Announce in Slack CLI channel# PR gpas/gpas/settings.py with new version