v0.30.8 - opentargets and g2p fixes

Version ≥ 0.30.8 (Jun 28, 2026):

• gget g2p: Either gene or --uniprot_id is now sufficient — whichever is missing is resolved via UniProt and cached. Gene→UniProt picks the canonical reviewed human Swiss-Prot entry; the resolution and its limitations are logged. The canonical pair is always prepended to the result as gene_name / uniprot_id columns (and stored on df.attrs), so the output schema is invariant regardless of input mode. Existing call sites continue to work.
  • New residues= filter (Python: int / list / range / set; CLI --residues 100,200,300 or 100-200) restricts features / alignment to specific positions client-side.
  • map results gain a parsed PDB Ids List column (list[str]) alongside the comma-joined PDB Ids string, for direct chaining into gget pdb.
  • Fixed silent failure when the gene/UniProt pair was unknown: G2P returns HTTP 200 with a JSON {"status":"failure",...} body that was being parsed as a single TSV column. Now logged as an error and returns None.
  • All failure modes now return None (was a mix of None and empty DataFrame).
  • Added retries with exponential backoff on transient failures (5xx, connection errors, timeouts).
  • URL-encoded path segments.
  • New out= Python argument writes the result to an explicit CSV path (takes precedence over save).
• gget alphafold: Added a new jackhmmer_savedir argument (-jhd/--jackhmmer_savedir on the command line) that lets you choose where the temporary jackhmmer files are stored. By default, gget alphafold still creates a ~/tmp/jackhmmer/ folder in your home directory (which can take up to ~2 GB of disk space); the new argument lets you redirect these files elsewhere, e.g. to a disk with more free space. Resolves issue 49.
• gget pdb: Added support for the PDBx/mmCIF structure format (fixes issue 178 and issue 177).
  • New resource="mmcif" option downloads the structure in PDBx/mmCIF format (.cif).
  • The default resource="pdb" now automatically falls back to PDBx/mmCIF when the legacy PDB file is unavailable (e.g. for large structures), since the legacy PDB format is being phased out by RCSB. A warning is logged and saved files use the correct extension (.cif).
• gget opentargets: Adapted to several upstream Open Targets GraphQL API changes:
  • Fixed: gget opentargets resource="drugs" was failing with HTTP 400 — Field 'synonyms' of type '[DrugLabelAndSource!]!' must have a sub selection. Open Targets changed Drug.synonyms and Drug.tradeNames from scalar lists to lists of structured DrugLabelAndSource objects. The internal GraphQL query was updated to request the label sub-field; the drug.synonyms / drug.tradeNames columns in the returned DataFrame remain list[str], so existing user code is unaffected.
  • Fixed: gget opentargets resource="expression" had started returning an empty DataFrame because Open Targets retired the Target.expressions field. The query now uses the current Target.baselineExpression field. The returned columns have changed because the upstream data model changed: results are now per-biosample (tissue/cell type) baseline expression summary statistics (median, min, q1, q3, max, unit) with tissueBiosample/celltypeBiosample identifiers and datasourceId/datatypeId, instead of the old per-tissue RNA zscore/value/level fields. A gene can have thousands of biosamples; the page size follows --limit (capped at the API's 3000-per-request maximum), and a warning is logged if results are truncated — narrow with --filters (e.g. datasourceId, datatypeId). Resolves issue 247.
  • Docs: Clarified the meaning of the diseases resource score column (OpenTargets' single overall target–disease association score, 0–1, aggregated across all data types/sources — not a per-data-source score) and that disease.id values are EFO-mapped traits that include not only MONDO diseases but also phenotypes (HP_*) and measurements (EFO_*), with an example of how to filter to MONDO disease terms only. Addresses issue 168.
• gget archs4 (tissue mode): No longer crashes with KeyError: ['color'] not found in axis when ARCHS4 intermittently omits the optional color column from its CSV response. The column is now dropped only if present. Output also has a deterministic row order (sorted by median descending, with id as tiebreaker) so equal-median tissues no longer flip order between requests.
• gget bgee: Outbound Bgee API requests now send a User-Agent: gget/<version> header so the Bgee service can attribute (and, if needed, allow-list) gget traffic, improving resilience against intermittent request blocking.

v0.30.7 - Modernize gget

• gget cellxgene: Added support for the three non-human primate species available in the CZ CELLxGENE Census LTS 2025-11-08: rhesus macaque (macaca_mulatta), common marmoset (callithrix_jacchus), and chimpanzee (pan_troglodytes).
  • The species argument (both Python and command line) now accepts all five supported organisms; the CLI choices, help text, and docstrings list them.
  • Added early validation of the species argument that raises a clear ValueError listing the supported species, instead of failing later inside the Census API call.
  • Note: the new primate species require census_version="2025-11-08" (LTS) or newer.
• Docs/README: updated gget repository and manual URLs from pachterlab to scverse (github.com/scverse/gget, scverse.org/gget) to reflect the project's move under the scverse organization. Links to separate resources (pachterlab/gget_examples, pachterlab/kvar, pachterlab/varseek, and the Pachter Lab homepage) were left unchanged. Resolves issue 217.
• gget g2p: New module to query the Genomics 2 Proteins (G2P) portal for residue-level protein structure/function annotations — per-residue features (AlphaFold pLDDT, UniProt sites, predicted pockets, PTMs), the gene–transcript–protein–isoform–structure map, and isoform alignments. Resolves issue 138.
• Deprecations:
  • gget alphafold and gget gpt are no longer actively maintained. Both now emit a warning when invoked, and a deprecation notice was added to the top of each module's docs.
• Bug fixes:
  • gget search: Missing values are now consistently returned as None instead of NaN, both in scalar cells and inside synonym lists ([None] rather than [nan] for genes with no synonyms). The previous output was an artifact of SQL LEFT JOINs surfacing as pandas NaNs; the JSON output was already null either way, so this only affects the DataFrame return path.
  • gget mutate: Fixed pyarrow.lib.ArrowNotImplementedError: Function 'binary_join_element_wise' has no kernel matching input types (large_string, null, large_string) when the input contained no substitutions (only deletions/insertions/delins/duplications/inversions). The substitution-only sequence-build branches now short-circuit on an empty selection instead of triggering an arrow-string kernel that older pyarrow versions don't implement.
  • gget muscle and gget diamond: When the bundled MUSCLE / DIAMOND binary fails because a system library is missing (most commonly libgomp / libomp on macOS without Homebrew gcc/libomp installed), gget now raises a clear RuntimeError naming the missing library and the exact brew install / apt install command to fix it — instead of the raw dyld / ld.so error spilling onto stderr.
  • gget muscle: When the MUSCLE binary fails, gget now exits with a non-zero status code instead of silently exiting 0. Pipelines and CI scripts can finally detect MUSCLE failures programmatically.
• Developer tooling / packaging:
  • Migrated packaging to a single pyproject.toml (the hatchling build backend); removed setup.py, setup.cfg, requirements.txt, dev-requirements.txt, and MANIFEST.in. Runtime dependencies and the test dependency group are now declared in pyproject.toml.
  • The minimum supported Python version is now 3.12; CI tests on 3.12, 3.13, and 3.14.
  • cellxgene-census is now declared as an optional extra (pip install gget[cellxgene]) because it has no wheels for Python 3.14 yet. Users who install it via gget setup cellxgene are unaffected.
  • Added a pre-commit configuration (lint + format via ruff, plus standard hygiene hooks). Run prek run --all-files (or pre-commit run --all-files) before opening a PR.
  • Added type annotations across the entire gget/ source tree (175 functions across all 28 source files) and wired mypy into the pre-commit config with a permissive baseline. IDE intellisense and downstream typed-code consumers benefit immediately; the type-error baseline can be tightened module-by-module over time.
  • Modernized the test CI to use uv and run on pull requests, and added package-build-check and PyPI trusted-publishing workflows.

v0.30.6 - bugs and fallbacks

• gget blat: Improved resilience against UCSC BLAT endpoint failures (fixes intermittently failing tests).
  • Added retry-with-exponential-backoff for transient failures (HTTP 429/5xx, network errors, and non-JSON 200 responses caused by UCSC rate-limiting or HTML error pages). Up to 4 attempts with 1.5s → 3s → 6s backoff.
  • Replaced the misleading "sequence too short or assembly invalid" message with the actual server response (status code, response preview) so failures are diagnosable.
  • HTTPError and URLError are now caught explicitly instead of bubbling up as unhandled exceptions.
• Bug fixes:
  • gget cosmic: Fixed misleading error message when the download step fails — was reporting the previous command's return code/stderr instead of the failing command's.
  • gget cosmic: Narrowed the JSON parse exception handler to json.JSONDecodeError so unrelated ValueErrors are no longer masked by the "Failed to download file" message.
  • gget --version, gget --help, gget invoked with no arguments, and gget <module> with no further arguments now all exit with status 0 instead of 1, so CI scripts and shell pipelines no longer treat these informational outputs as failures.
  • Added request timeouts to previously-unguarded requests calls in gget ref, gget info, gget 8cube, gget enrichr, and gget opentargets. Default is 10s connect / 60s read; configurable via the new DEFAULT_REQUESTS_TIMEOUT constant.
  • Narrowed a bare except: in utils.get_uniprot_seqs to (KeyError, IndexError, TypeError) so unrelated errors (including KeyboardInterrupt) are no longer swallowed.
  • Added utils.http_json() and utils.dig() helpers that issue a request and parse JSON / walk a nested response path with consistent error reporting. Migrated gget bgee, gget opentargets, and one .json() callsite in gget virus to use them; remaining modules will migrate opportunistically. Upstream HTML error pages, malformed JSON, and missing response keys now surface as clear RuntimeErrors naming the failing service instead of cryptic JSONDecodeError / KeyError tracebacks.
  • utils.http_json() now retries transient failures (connection errors, read timeouts, HTTP 5xx) up to 3 times with exponential backoff. Smooths over short upstream blips (e.g. bgee.org read timeouts) without affecting 4xx errors, which still raise immediately.
  • gget virus: Replaced 11 bare except: pass blocks around file.close() / os.remove() cleanup calls with narrowed except OSError handlers that log the failure at DEBUG. Previously, real I/O issues during cleanup (disk full, permissions) were silently dropped and the cleanup path also swallowed KeyboardInterrupt.
  • gget cbio: Fixed a code path in cbio_plot that called the removed-in-pandas-2.0 DataFrame.append() inside a loop when filling missing CNA genes — the entire branch crashed on modern pandas. It now builds a single DataFrame of missing rows and concatenates once.
• Performance:
  • utils.get_uniprot_seqs: Collect per-ID DataFrames in a list and pd.concat(..., ignore_index=True) once at the end, avoiding the O(n²) cost of growing a DataFrame inside the request loop.
  • Cached utils.find_latest_ens_rel, utils.search_species_options, utils.ref_species_options, and utils.find_nv_kingdom with functools.lru_cache. These hit Ensembl FTP listings that are stable for a release; repeated calls within one Python process are now free.
  • Added utils.parallel_map, a thin ThreadPoolExecutor wrapper for I/O-bound work. Used to fan out utils.get_uniprot_seqs across the input ID list — looking up N IDs is now bounded by ~N / pool_size UniProt round-trips instead of N. Pool size defaults to 8 and can be overridden via the GGET_MAX_WORKERS environment variable.

v0.30.5 - gget virus updates

• gget opentargets: Rewrote this module to reflect the new Open Targets API structure
  • some output column/key names may differ to reflect the new API structure
  • Removed the --filter_mode argument
• gget blast: Fixed compatibility with newer pandas versions (≥ 2.0) where pd.read_html() no longer accepts raw HTML strings directly, causing a FileNotFoundError / OSError: Filename too long error when parsing BLAST results
• gget cosmic: Added overwrite and gzip arguments to internals.
• gget virus updates

v0.30.3 - gget virus updates

Version ≥ 0.30.3 (Feb 26, 2026):

• gget virus: New filtering options, quiet mode, and improved download reliability
  • Added --segment filter for segmented viruses (e.g., Influenza A segments like 'HA', 'NA', 'PB1')
  • Added --vaccine_strain filter to include or exclude vaccine strain sequences
  • Added --source_database filter to select sequences from 'genbank' or 'refseq' (replaces refseqOnly)
  • Added -q / --quiet flag to suppress progress information
  • Extended fallback strategies for improved download reliability on large datasets
  • Command summary file now includes software version

v0.30.2 - gget virus updates

• gget virus updates: Metadata streaming optimization, improved protein filtering, and enhanced error handling and retry logic
  • Metadata now streams to disk during fetch to prevent memory exhaustion on large datasets (100,000+ records)
  • Fixed metadata CSV mapping (camelCase → snake_case) for organism name, host, and collection date
  • Enhanced protein filtering for segmented viruses with improved FASTA header parsing
  • Added annotated=False option for filtering unannotated sequences
  • Added progress bars to batched sequence downloads
  • Fixed collection date naming bug
  • Improved error messages for invalid filter dates
  • Added enhanced retry attempts for virus name resolution
  • Added verbosity to influenza A and COVID-19 checking steps

v0.30.0 - gget virus & gget 8cube

• NEW MODULES:

  • gget 8cube
  • gget virus

• SECURITY IMPROVEMENTS:

  • Replaced os.system() with f-strings containing URLs from external APIs in gget/main.py
  • Replaced exec() with importlib.import_module() in gget setup for safer dynamic imports
  • Replaced shell=True subprocess calls with list-based arguments in gget muscle, gget diamond, and gget setup to prevent command injection

v0.29.3 - BLAT access

Version ≥ 0.29.3 (Sep 11, 2025):

• gget blat: Updated API request to new permissions.
• gget pdb: Added wwpdb mirror; falls back to rcsb if wwpdb fails.
• gget cellxgene: Improved argument handling; frontend unchanged. Fixes issue 181.
• gget setup/gget alphafold: Fixed pip_cmd bug in gget.setup("alphafold")

v0.29.2 - uv pip install gget

Version ≥ 0.29.2 (Jul 03, 2025):

• gget can now be installed using uv pip install gget
  • All package metadata (version, author, description, etc.) is now managed in setup.cfg for full compatibility with modern tools like uv, pip, and PyPI
  • gget now uses a minimal setup.py and is fully PEP 517/518 compatible
• gget setup will now try to use uv pip install first for speed and modern dependency resolution, and fall back onto pip install if uv fails or is not available
  • Users are informed at each step which installer is being used and if a retry is happening
  • Note: Some scientific dependencies (e.g., cellxgene-census) may not yet support Python 3.12. If you encounter installation errors, try using Python 3.9 or 3.10. (The pip installation might also still succeed in these cases.)
• All required dependencies are now listed in setup.cfg under install_requires -> Installing gget with pip install . or uv pip install . will automatically install all dependencies

v0.29.1 - mutate and cosmic overhaul

• gget mutate:
  • gget mutate has been simplified to focus on taking as input a list of mutations and associated reference genome with corresponding annotation information, and produce as output the sequences with the mutation incorporated and a short region of surrounding context. For the full functionality of the previous version and how it integrates in the context of a novel variant screening pipeline, visit the varseek repository being developed by members of the gget team at https://github.com/pachterlab/varseek.git.
  • Added additional information to returned data frames as described here: #169
• gget cosmic:
  • Major restructuring of the gget cosmic module to adhere to new login requirements set by COSMIC
  • New arguments email and password were added to allow the user to manually enter their login credentials without required input for data download
  • Default changed: gget_mutate=False
  • Deprecated argument: entity
  • Argument mutation_class is now cosmic_project
• gget bgee:
  • type="orthologs" is now the default, removing the need to specify the type argument when calling orthologs
  • Allow querying multiple genes at once.
• gget diamond:
  • Now supports translated alignment of nucleotide sequences to amino acid reference sequences using the --translated flag.
• gget elm:
  • Improved server error handling.