FEATURE_DRAW(1p)

📦
version 2.40 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 FEATURE_DRAW 💖

okay bestie, gather round, because this one is from the User Contributed Perl Documentation shelf of the 1p man pages and it's genuinely so useful. it's a whole script. it renders your feature files. it's giving ✨pipeline glamour✨.

✨ NAME ✨

feature_draw.pl — render a Bio::Graphics Feature File 🎀

🦋 SYNOPSIS 🦋

feature_draw.pl [options] file.txt [file2.txt...] > rendering.png
feature_draw.pl [options] file.txt [file2.txt...] | display -

like, yes, that's it, that's the whole vibe. 💅

🌸 DESCRIPTION 🌸

so feature_draw.pl is a thin front end wrapped around the Bio::Graphics module. she does not do the heavy lifting herself, she just delegates and looks cute doing it. 👑

what she actually does: she takes a list of files that hold sequence feature coordinates — protein, nucleotide, whatever — either from the files you list on the command line or from standard input, renders them, and spits out a PNG file on standard output. periodt.

🎀 Options 🎀

this script uses GNU-style long options. which means you can hand her the image width option in literally any of these forms, your choice, no judgement:

 --width=800
 --width 800
 -width 800
 -w 800
  • --width — sets the width of the image, in pixels. the default is 800 pixels.
  • --range — sets the range of the region displayed, in base pairs from start to stop. any of these formats are accepted:
  --range 1..1000
  --range 1,1000
  --range 1-1000
and yes bestie, negative ranges are allowed. go off. 🙈

🌈 Feature Files Format 🌈

this script accepts and processes sequence annotations in a simple tab-delimited format or in GFF format. both. she's flexible. 💅

the feature file format has two parts: a configuration section and a data section. the configuration section sets up the size and overall properties of the image, and the data section gives you the feature data itself.

🧚 Configuration Section 🧚

if you don't provide one, this script generates a reasonable default configuration section for you, so you genuinely do not need to provide a configuration section to get a reasonable image. no cap. 🫶

however — and this is the important bit — if you want to actually tune the appearance of the image, you will probably want to tweak the configuration. here's an excerpt from the configuration section:

# example file
[general]
bases = -1000..21000
height = 12

[EST]
glyph = segments
bgcolor= yellow
connector = dashed
height = 5

[FGENES]
glyph = transcript2
bgcolor = green
description = 1

so the configuration section is divided into a set of sections, each one labeled with a [section title]. the [general] section specifies global options for the entire image. the other sections apply to particular feature types. in the example up there, the config in the [EST] section applies to features labeled as ESTs, and the config in the [FGENES] section applies to features labeled as predictions from the FGENES gene prediction program. 🧬

inside each section is a series of name=value pairs, where the name is the name of an option to set. you can put whitespace around the = sign to make it more readable, or even use a colon (:) if you prefer. the following option names are recognized:

  • bases — Min & max of the sequence range (bp). example: 1200..60000
  • width — width of the image (pixels). example: 600
  • height — Height of each graphical element (pixels). example: 10
  • glyph — Style of each graphical element (see below). example: transcript
  • fgcolor — Foreground color of each element. example: yellow
  • bgcolor — Background color of each element. example: blue
  • linewidth — Width of lines. example: 3
  • label — Print the feature's name. example: 1
  • description — Whether to print the feature's description. example: 0
  • bump — Elements are not allowed to collide. example: 1
  • ticks — Print tick marks on arrows. example: 1
  • connector — Type of group connector (dashed, hat or solid). example: dashed

the bases and width options are only relevant in the [general] section. they get overridden by the like-named command-line options. 💀

the remainder of the options can be located in any section, but if present in the [general] section they will set defaults for all the others. main character energy fr fr.

colors are English-language color names or Web-style #RRGGBB colors (go read a book on HTML if you want the explanation, iykyk). true/false values are 1 for true and 0 for false. numeric ranges can be expressed in start..end fashion with two dots, or as start-end with a hyphen.

the glyph option controls how the features are rendered. the following glyphs are implemented:

  • box — a filled rectangle, nondirectional.
  • ellipse — an oval.
  • arrow — an arrow; can be unidirectional or bidirectional. it is also capable of displaying a scale with major and minor tickmarks, and can be oriented horizontally or vertically.
  • segments — a set of filled rectangles connected by solid lines. used for interrupted features, such as gapped alignments and exon groups.
  • transcript — similar to segments, but the connecting line is a "hat" shape, and the direction of transcription is indicated by a small arrow.
  • transcript2 — similar to transcript, but the direction of transcription is indicated by a terminal segment in the shape of an arrow.
  • primers — two inward pointing arrows connected by a line. used for STSs.

okay so the bump option is the most important option for controlling the look of the image. listen:

  • if set to false (the number 0), the features are allowed to overlap.
  • if set to true (the number 1), the features will move vertically to avoid colliding.
  • if not specified, bump is turned on if the number of any given type of sequence feature is greater than 50.

🍓 Data Section 🍓

the data section can follow or proceed the configuration section. the two sections can also be intermixed. the data section is a tab or whitespace-delimited file which you can export from a spreadsheet application or word processor file — be sure to save as text only! 😭

here is an example data section:

Cosmid     B0511        .       516-619 Cosmid     B0511        .
3185-3294 Cosmid     B0511        .       10946-11208 Cosmid     B0511
.       13126-13511 Cosmid     B0511        .       66-208 Cosmid
B0511        .       6354-6499 Cosmid     B0511        .
13955-14115 EST        yk595e6.5    +       3187-3294 EST
yk846e07.3   -       11015-11208 EST        yk53c10
           yk53c10.5    +       18892-19154
           yk53c10.3    -       15000-15500,15700-15800 EST
yk53c10.5    +       16032-16105 SwissProt  PECANEX      +
13153-13656     Swedish fish FGENESH    "Gene 1"     -
1-205,518-616,661-735,3187-3365,3436-3846       Transmembrane domain
FGENESH    "Gene 2"     -       16626-17396,17451-17597 Kinase and sushi
domains

each line of the file contains five columns. the columns are:

  1. feature type
  2. feature name
  3. strand
  4. coordinates
  5. description

💜 Feature type 💜

the feature type should correspond to one of the [feature type] headings in the configuration section. if it doesn't, the [general] options will be applied to the feature when rendering it. the feature name is a name for the feature. use a . or - if this is not relevant. if the name contains whitespace, put single or double quotes ("") around the name.

💜 Strand 💜

the strand indicates which strand the feature is on. it is one of:

  • + for the forward strand
  • - for the reverse strand
  • . for features that are not stranded

💜 Coordinates 💜

the coordinates column is a set of one or more ranges that the feature occupies. ranges are written using .. as in start..stop, or with hyphens, as in start-stop. for features that are composed of multiple ranges — for example transcripts that have multiple exons — you can either put the ranges on the same line separated by commas or spaces, or put the ranges on individual lines and just use the same feature name and type to group them. in the example above, the Cosmid B0511 features use the individual line style, while the FGENESH features use the all-ranges-on-one-line style. slay. ✨

💜 Description 💜

the last column contains some descriptive text. if the description option is set to true, this text will be printed underneath the feature in the rendering.

finally, it is possible to group related features together. an example is the ESTs yk53c10.5 and yk53c10.3, which are related by being reads from the two ends of the clone yk53c10. to indicate this relationship, generate a section that looks like this:

EST        yk53c10
           yk53c10.5    +       18892-19154
           yk53c10.3    -       15000-15500,15700-15800

the group is indicated by a line that contains just two columns containing the feature type and a unique name for the group. follow this line with all the features that form the group, but leave the first column (the feature type) blank. the group will be rendered by drawing a dashed line between all the members of the group. you can change this by specifying a different connector option in the configuration section for this feature type. 🫶

💀 BUGS 💀

please report them to the author. that's it. that's the whole bug section. go tell Lincoln. 🙈

👑 SEE ALSO 👑

  • Bio::Graphics

🌟 AUTHOR 🌟

Lincoln Stein, lstein@cshl.org 🎀

okay bestie that's the whole page!! 💖 this was perl v5.30.0, dated 2019-11-25, and it's one of the FEATURE_DRAW(1p) pages from the User Contributed Perl Documentation. go render something gorgeous, you ate. 💅✨🦋🌸

📦 where this page comes from