gget

# gget ## Overview gget is a command-line bioinformatics tool and Python package providing unified access to 20+ genomic databases and analysis methods. Query gene information, sequence analysis, protein structures, expression data, and disease associations through a consistent interface. All gget modules work both as command-line tools and as Python functions. **Important**: The databases queried by gget are continuously updated, which sometimes changes their structure. gget modules are tested automatically on a biweekly basis and updated to match new database structures when necessary. ## Installation Install gget in a clean virtual environment to avoid conflicts: ```bash # Using uv (recommended) uv uv pip install gget # Or using pip uv pip install --upgrade gget # In Python/Jupyter import gget ``` ## Quick Start Basic usage pattern for all modules: ```bash # Command-line gget <module> [arguments] [options] # Python gget.module(arguments, options) ``` Most modules return: - **Command-line**: JSON (default) or CSV with `-csv` flag - **Python**: DataFrame or dictionary Common flags across modules: - `-o/--out`: Save results to file - `-q/--quiet`: Suppress progress information - `-csv`: Return CSV format (command-line only) ## Module Categories ### 1. Reference & Gene Information #### gget ref - Reference Genome Downloads Retrieve download links and metadata for Ensembl reference genomes. **Parameters**: - `species`: Genus_species format (e.g., 'homo_sapiens', 'mus_musculus'). Shortcuts: 'human', 'mouse' - `-w/--which`: Specify return types (gtf, cdna, dna, cds, cdrna, pep). Default: all - `-r/--release`: Ensembl release number (default: latest) - `-l/--list_species`: List available vertebrate species - `-liv/--list_iv_species`: List available invertebrate species - `-ftp`: Return only FTP links - `-d/--download`: Download files (requires curl) **Examples**: ```bash # List available species gget ref --list_species # Get all reference files for human gget ref homo_sapiens # Download only GTF annotation for mouse gget ref -w gtf -d mouse ``` ```python # Python gget.ref("homo_sapiens") gget.ref("mus_musculus", which="gtf", download=True) ``` #### gget search - Gene Search Locate genes by name or description across species. **Parameters**: - `searchwords`: One or more search terms (case-insensitive) - `-s/--species`: Target species (e.g., 'homo_sapiens', 'mouse') - `-r/--release`: Ensembl release number - `-t/--id_type`: Return 'gene' (default) or 'transcript' - `-ao/--andor`: 'or' (default) finds ANY searchword; 'and' requires ALL - `-l/--limit`: Maximum results to return **Returns**: ensembl_id, gene_name, ensembl_description, ext_ref_description, biotype, URL **Examples**: ```bash # Search for GABA-related genes in human gget search -s human gaba gamma-aminobutyric # Find specific gene, require all terms gget search -s mouse -ao and pax7 transcription ``` ```python # Python gget.search(["gaba", "gamma-aminobutyric"], species="homo_sapiens") ``` #### gget info - Gene/Transcript Information Retrieve comprehensive gene and transcript metadata from Ensembl, UniProt, and NCBI. **Parameters**: - `ens_ids`: One or more Ensembl IDs (also supports WormBase, Flybase IDs). Limit: ~1000 IDs - `-n/--ncbi`: Disable NCBI data retrieval - `-u/--uniprot`: Disable UniProt data retrieval - `-pdb`: Include PDB identifiers (increases runtime) **Returns**: UniProt ID, NCBI gene ID, primary gene name, synonyms, protein names, descriptions, biotype, canonical transcript **Examples**: ```bash # Get info for multiple genes gget info ENSG00000034713 ENSG00000104853 ENSG00000170296 # Include PDB IDs gget info ENSG00000034713 -pdb ``` ```python # Python gget.info(["ENSG00000034713", "ENSG00000104853"], pdb=True) ``` #### gget seq - Sequence Retrieval Fetch nucleotide or amino acid sequences for genes and transcripts. **Parameters**: - `ens_ids`: One or more Ensembl identifiers - `-t/--translate`: Fetch amino acid sequences instead of nucleotide - `-iso/--isoforms`: Return all transcript variants (gene IDs only) **Returns**: FASTA format sequences **Examples**: ```bash # Get nucleotide sequences gget seq ENSG00000034713 ENSG00000104853 # Get all protein isoforms gget seq -t -iso ENSG00000034713 ``` ```python # Python gget.seq(["ENSG00000034713"], translate=True, isoforms=True) ``` ### 2. Sequence Analysis & Alignment #### gget blast - BLAST Searches BLAST nucleotide or amino acid sequences against standard databases. **Parameters**: - `sequence`: Sequence string or path to FASTA/.txt file - `-p/--program`: blastn, blastp, blastx, tblastn, tblastx (auto-detected) - `-db/--database`: - Nucleotide: nt, refseq_rna, pdbnt - Protein: nr, swissprot, pdbaa, refseq_protein - `-l/--limit`: Max hits (default: 50) - `-e/--expect`: E-value cutoff (default: 10.0) - `-lcf/--low_comp_filt`: Enable low complexity filtering - `-mbo/--megablast_off`: Disable MegaBLAST (blastn only) **Examples**: ```bash # BLAST protein sequence gget blast MKWMFKEDHSLEHRCVESAKIRAKYPDRVPVIVEKVSGSQIVDIDKRKYLVPSDITVAQFMWIIRKRIQLPSEKAIFLFVDKTVPQSR # BLAST from file with specific database gget blast sequence.fasta -db swissprot -l 10 ``` ```python # Python gget.blast("MKWMFK...", database="swissprot", limit=10) ``` #### gget blat - BLAT Searches Locate genomic positions of sequences using UCSC BLAT. **Parameters**: - `sequence`: Sequence string or path to FASTA/.txt file - `-st/--seqtype`: 'DNA', 'protein', 'translated%20RNA', 'translated%20DNA' (auto-detected) - `-a/--assembly`: Target assembly (default: 'human'/hg38; options: 'mouse'/mm39, 'zebrafinch'/taeGut2, etc.) **Returns**: genome, query size, alignment positions, matches, mismatches, alignment percentage **Examples**: ```bash # Find genomic location in human gget blat ATCGATCGATCGATCG # Search in different assembly gget blat -a mm39 ATCGATCGATCGATCG ``` ```python # Python gget.blat("ATCGATCGATCGATCG", assembly="mouse") ``` #### gget muscle - Multiple Sequence Alignment Align multiple nucleotide or amino acid sequences using Muscle5. **Parameters**: - `fasta`: Sequences or path to FASTA/.txt file - `-s5/--super5`: Use Super5 algorithm for faster processing (large datasets) **Returns**: Aligned sequences in ClustalW format or aligned FASTA (.afa) **Examples**: ```bash # Align sequences from file gget muscle sequences.fasta -o aligned.afa # Use Super5 for large dataset gget muscle large_dataset.fasta -s5 ``` ```python # Python gget.muscle("sequences.fasta", save=True) ``` #### gget diamond - Local Sequence Alignment Perform fast local protein or translated DNA alignment using DIAMOND. **Parameters**: - Query: Sequences (string/list) or FASTA file path - `--reference`: Reference sequences (string/list) or FASTA file path (required) - `--sensitivity`: fast, mid-sensitive, sensitive, more-sensitive, very-sensitive (default), ultra-sensitive - `--threads`: CPU threads (default: 1) - `--diamond_db`: Save database for reuse - `--translated`: Enable nucleotide-to-amino acid alignment **Returns**: Identity percentage, sequence lengths, match positions, gap openings, E-values, bit scores **Examples**: ```bash # Align against reference gget diamond GGETISAWESQME -ref reference.fasta --threads 4 # Save database for reuse gget diamond query.fasta -ref ref.fasta --diamond_db my_db.dmnd ``` ```python # Python gget.diamond("GGETISAWESQME", reference="reference.fasta", threads=4) ``` ### 3. Structural & Protein Analysis #### gget pdb - Protein Structures Query RCSB Protein Data Bank for structure and metadata. **Parameters**: - `pdb_id`: PDB identifier (e.g., '7S7U') - `-r/--resource`: Data type (pdb, entry, pubmed, assembly, entity types) - `-i/--identifier`: Assembly, entity, or chain ID **Returns**: PDB format (structures) or JSON (metadata) **Examples**: ```bash # Download PDB structure gget pdb 7S7U -o 7S7U.pdb # Get metadata gget pdb 7S7U -r entry ``` ```python # Python gget.pdb("7S7U", save=True) ``` #### gget alphafold - Protein Structure Prediction Predict 3D protein structures using simplified AlphaFold2. **Setup Required**: ```bash # Install OpenMM first uv pip install openmm # Then setup AlphaFold gget setup alphafold ``` **Parameters**: - `sequence`: Amino acid sequence (string), multiple sequences (list), or FASTA file. Multiple sequences trigger multimer modeling - `-mr/--multimer_recycles`: Recycling iterations (default: 3; recommend 20 for accuracy) - `-mfm/--multimer_for_monomer`: Apply multimer model to single proteins - `-r/--relax`: AMBER relaxation for top-ranked model - `plot`: Python-only; generate interactive 3D visualization (default: True) - `show_sidechains`: Python-only; include side chains (default: True) **Returns**: PDB structure file, JSON alignment error data, optional 3D visualization **Examples**: ```bash # Predict single protein structure gget alphafold MKWMFKEDHSLEHRCVESAKIRAKYPDRVPVIVEKVSGSQIVDIDKRKYLVPSDITVAQFMWIIRKRIQLPSEKAIFLFVDKTVPQSR # Predict multimer with higher accuracy gget alphafold sequence1.fasta -mr 20 -r ``` ```python # Python with visualization gget.alphafold("MKWMFK...", plot=True, show_sidechains=True) # Multimer prediction gget.alphafold(["sequence1", "sequence2"], multimer_recycles=20) ``` #### gget elm - Eukaryotic Linear Motifs Predict Eukaryotic Linear Motifs in protein sequences. **Setup Required**: ```bash gget setup elm ``` **Parameters**: - `sequence`: Amino acid sequence or UniProt Acc - `-u/--uniprot`: Indicates sequence is UniProt Acc - `-e/--expand`: Include protein names, organisms, references - `-s/--sensitivity`: DIAMOND alignment sensitivity (default: "very-sensitive") - `-t/--threads`: Number of threads (default: 1) **Returns**: Two outputs: 1. **ortholog_df**: Linear motifs from orthologous proteins 2. **regex_df**: Motifs directly matched in input sequence **Examples**: ```bash # Predict motifs from sequence gget elm LIAQSIGQASFV -o results # Use UniProt accession with expanded info gget elm --uniprot Q02410 -e ``` ```python # Python ortholog_df, regex_df = gget.elm("LIAQSIGQASFV") ``` ### 4. Expression & Disease Data #### gget archs4 - Gene Correlation & Tissue Expression Query ARCHS4 database for correlated genes or tissue expression data. **Parameters**: - `gene`: Gene symbol or Ensembl ID (with `--ensembl` flag) - `-w/--which`: 'correlation' (default, returns 100 most correlated genes) or 'tissue' (expression atlas) - `-s/--species`: 'human' (default) or 'mouse' (tissue data only) - `-e/--ensembl`: Input is Ensembl ID **Returns**: - **Correlation mode**: Gene symbols, Pearson correlation coefficients - **Tissue mode**: Tissue identifiers, min/Q1/median/Q3/max expression values **Examples**: ```bash # Get correlated genes gget archs4 ACE2 # Get tissue expression gget archs4 -w tissue ACE2 ``` ```python # Python gget.archs4("ACE2", which="tissue") ``` #### gget cellxgene - Single-Cell RNA-seq Data Query CZ CELLxGENE Discover Census for single-cell data. **Setup Required**: ```bash gget setup cellxgene ``` **Parameters**: - `--gene` (-g): Gene names or Ensembl IDs (case-sensitive! 'PAX7' for human, 'Pax7' for mouse) - `--tissue`: Tissue type(s) - `--cell_type`: Specific cell type(s) - `--species` (-s): 'homo_sapiens' (default) or 'mus_musculus' - `--census_version` (-cv): Version ("stable", "latest", or dated) - `--ensembl` (-e): Use Ensembl IDs - `--meta_only` (-mo): Return metadata only