BP_GENB...TRACTOR(1p)

📦
version 1.77 · 4 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 BP_GENB...TRACTOR(1p) 💖

okay bestie, this is a User Contributed Perl Documentation page and it is so much. it's the manual for bp_genbank_ref_extractor, and yes the name is giving "the terminal ate half the title" but we move. sit down, grab a strawberry 🍓, and let's get into it.

✨ NAME ✨

bp_genbank_ref_extractor — the icon that retrieves all related sequences for a list of searches on Entrez gene. no cap. 🧬

🌈 VERSION 🌈

version 1.77. periodt.

🎀 SYNOPSIS 🎀

bp_genbank_ref_extractor [options] [Entrez Gene Queries]

🦋 DESCRIPTION 🦋

so this script goes to the Entrez Gene database and pulls up, like, everything: not just the gene sequence but the related transcript AND protein sequences too. it's the full package, she's a triple threat 💅.

and here's the lowkey genius part: the gene UIDs of multiple searches get collected first before anyone tries to retrieve anything. so each gene only gets analyzed once, even if it pops up as a result in more than one of your searches. no duplicate effort, main character efficiency ✨.

💀 heads up bestie: by default no sequences are saved. like, at all. check the options and examples, i'm begging you.

💅 OPTIONS 💅

there are several options to fine tune her behaviour — you can grab extra base pairs upstream and downstream of the gene, control how files get named, and pick which genome assembly to use. obsessed.

⚠️ also fr fr, go read the bugs section about problems when you use default option values. don't skip it, i know you want to skip it.
  • --assembly — when retrieving the sequence you can name a specific assembly. the value it expects is a regex, and it's case-insensitive. if it matches more than one assembly, it just uses the first match. defaults to "(primary|reference) assembly".
  • --debug — if set, you get EVEN MORE output that might help with debugging. unlike the messages from --verbose and --very-verbose, these will not show up in the log file unless this option is selected. this option also sets --very-verbose for you. two for one, slay.
  • --downstream, --down — says how many extra base pairs to retrieve downstream of the gene. this extra stuff only affects the gene sequence, not the transcript or the proteins. 🫶
  • --email — a valid email for connecting to the NCBI servers. NCBI may use it to contact users if there are problems, and to reach out before blocking access in case of heavy usage. so like, be a good citizen and give them a real one.
  • --api-key — NCBI requires an API key for requests over 10/sec as of December 2018. you may generate one in the "My NCBI" area. 🔑
  • --format — specifies the format the sequences get saved in. defaults to genbank format. valid formats are 'genbank' or 'fasta'.
  • --genes — specifies the name for the gene file. by default, they are not saved. if no value is given it defaults to its UID. possible values are 'uid', 'name', 'symbol' (the official symbol or nomenclature).
  • --help — display the documentation (this text). hi, that's me, i'm this text 💖.
  • --limit — when making a query, limit the result to these first specific results. this is to prevent the use of specially unspecific queries, and a warning gets given if a query returns more results than the limit. the default value is 200. note that this limit is for each search.
  • --non-coding, --nonon-coding — some protein coding genes have transcripts that are non-coding. by default, these sequences are saved as well. --nonon-coding can be used to ignore those transcripts.
  • --proteins — specifies the name for proteins file. by default, they are not saved. if no value is given it defaults to its accession. possible values are 'accession', 'description', 'gene' (the corresponding gene ID) and 'transcript' (the corresponding transcript accesion).
😭 note that if you're not using 'accession', it's possible for files to be overwritten. it's possible for the same gene to encode more than one protein, or for different proteins to have the same description. be careful bestie.
  • --pseudo, --nopseudo — by default, sequences of pseudo genes will be saved. --nopseudo can be used to ignore those genes.
  • --save — specifies the path for the directory where the sequence and log files will be saved. if the directory doesn't exist it will be created, although the path to it must exist. files in the directory may be rewritten if necessary. if unspecified, a directory named extracted sequences in the current directory gets used.
  • --save-data — this option saves the data (gene UIDs, description, product accessions, etc) to a file. as an optional value, you can specify the file format. defaults to CSV.

currently only CSV is supported.

saving the data structure as a CSV file requires the installation of the Text::CSV module.

  • --transcripts, --mrna — specifies the name for transcripts file. by default, they are not saved. if no value is given it defaults to its accession. possible values are 'accession', 'description', 'gene' (the corresponding gene ID) and 'protein' (the protein the transcript encodes).
😭 note that if you're not using 'accession', it's possible for files to be overwritten. it's possible for the same gene to have more than one transcript, or for different transcripts to have the same description. also, non-coding transcripts will create problems if using 'protein'.
  • --upstream, --up — specifies the number of extra base pairs to be extracted upstream of the gene. this extra base pairs will only affect the gene sequence, not the transcript or proteins.
  • --verbose, --v — if set, the program becomes verbose. for an extremely verbose program, use --very-verbose instead.
  • --very-verbose, --vv — if set, the program becomes extremely verbose. setting this option automatically sets --verbose as well. for help in debugging, consider using --debug. 🔥

🌸 EXAMPLES 🌸

bestie these examples are everything, let's go one by one:

 bp_genbank_ref_extractor \
   --transcripts=accession \
   '"homo sapiens"[organism] AND H2B'

search Entrez Gene with the query '"homo sapiens"[organism] AND H2B' and save their transcripts sequences only. note that the default value of --limit may only extract some of the hits. 🙈

 bp_genbank_ref_extractor \
   --transcripts=accession --proteins=accession \
    --format=fasta \
    '"homo sapiens"[organism] AND H2B' \
    '"homo sapiens"[organism] AND MCPH1'

save both transcript and protein sequences in the fasta format, for two queries: '"homo sapiens"[organism] AND H2B' and '"homo sapiens"[organism] AND MCPH1'. two queries, one icon.

 bp_genbank_ref_extractor \
   --genes --down=500 --up=100 \
   '"homo sapiens"[organism] AND H2B'

download genomic sequences, including 500 bp downstream and 100 bp upstream of each gene. ✨

 bp_genbank_ref_extractor \
   --genes --asembly='Alternate HuRef' \
   '"homo sapiens"[organism] AND H2B'

download genomic sequences from the Alternate HuRef genome assembly.

 bp_genbank_ref_extractor --save-data=CSV \
   '"homo sapiens"[organism] AND H2B'

do not save any sequence, only save the results in a CSV file. minimalism, she's chic.

 bp_genbank_ref_extractor --save='search-results' \
   --genes=name  downstream=500 --upstream=200 \
   --nopseudo --nonnon-coding --transcripts --proteins \
   --format=fasta --save-data=CSV \
   '"homo sapiens"[organism] AND H2B' \
   '"homo sapiens"[organism] AND MCPH1'

ignoring non-coding and pseudo genes, downloads: genomic sequences with 500 and 200 bp downstream and upstream respectively, using the gene name as filename; transcript and proteins sequences using their accession number as filename; everything in fasta format plus a CSV file with search results; saved in a directory named search-results. this one ate and left no crumbs 👑

💀 NON-BUGS 💀

okay these are NOT bugs, they're just how it works, don't come for her.

  • when supplying options, it's possible to not supply a value and just use the default. however, when the expected value is a string, the next argument may get confused as a value for the option. for example, when using the following command:
 bp_genbank_ref_extractor --transcripts \
   'H2A AND homo sapiens'

we mean to search for 'H2A AND homo sapiens' saving only the transcripts and using the default as base for the filename. but the search terms will be interpreted as the base for the filenames (and since it's not a valid identifier, it will return an error). 😭 to prevent this, you can either specify the values:

 bp_genbank_ref_extractor --transcripts='accession' \
   'H2A AND homo sapiens'

or you can use the double hash to stop processing options. note that this should only be used after the last option. all arguments supplied after the double dash will be interpreted as search terms:

 bp_genbank_ref_extractor --transcripts \
   -- 'H2A AND homo sapiens'

🧚 NOTES ON USAGE 🧚

  • genes that are marked as 'live' and 'protein-coding' should have at least one transcript. however, this is not always true due to mistakes on annotation. such cases will throw a warning. when faced with this, be nice and write to the entrez RefSeq maintainers <http://www.ncbi.nlm.nih.gov/RefSeq/update.cgi>. 🫶
  • when creating the directories to save the files, if the directory already exists it will be used and no error or warning will be issued unless --debug has been set. if a non-directory file already exists with that name, bp_genbank_ref_extractor exits with an error.
  • on the subject of verbosity: all messages are saved on the log file. the options --verbose and --very-verbose only affect their printing to standard output. debug messages are different — they will only show up (and be logged) if requested with --debug.
  • when saving a file, to avoid problems with limited filesystems such as NTFS or FAT, only some characters are allowed. all other characters will be replaced by an underscore. allowed characters are:
a-z 0-9 - + . , () {} []'
  • bp_genbank_ref_extractor tries to use the same file extensions that bioperl would expect when saving the file. if unable, it will use the '.seq' extension.

📬 FEEDBACK 📬

💌 Mailing lists

user feedback is an integral part of the evolution of this and other Bioperl modules. send your comments and suggestions preferably to the Bioperl mailing list. your participation is much appreciated. 💖

  bioperl-l@bioperl.org               - General discussion
  https://bioperl.org/Support.html    - About the mailing lists

🛟 Support

please direct usage questions or support issues to the mailing list: bioperl-l@bioperl.org rather than to the module maintainer directly. many experienced and reponsive experts will be able look at the problem and quickly address it. please include a thorough description of the problem with code and data examples if at all possible. ngl, that last part is important — help them help you.

🐛 Reporting bugs

report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their resolution. bug reports can be submitted via the web:

  https://github.com/bioperl/bio-eutilities/issues

👑 AUTHOR 👑

Carnë Draug <carandraug+dev@gmail.com>

this software is copyright (c) 2011-2015 by Carnë Draug.

this software is available under the GNU General Public License, Version 3, June 2007.

okay that's the whole page bestie, you're officially a bp_genbank_ref_extractor expert now, no cap. this was built with perl v5.40.0 and dated 2025-01-27, mwah 💋✨🦋

📦 where this page comes from