Tag

Tag / Label #

A regular tag is a piece of fragment-derived metadata that one step in the pipeline produces, and other steps may consume, transform, or export.

A virtual tag is an on-the-fly create tag that exists just for this step and disappears right afterwards.

Overview - Regular tags #

Tags enable sophisticated workflows by decoupling data extraction from data usage. Instead of hardcoding logic like “trim adapters AND filter by adapter presence” into a single step, you extract adapter locations as a tag, then use that tag in multiple downstream operations.

Tags are identified by labels (arbitrary names following the pattern [a-zA-Z_][a-zA-Z0-9_]*) and carry typed values that describe properties of each fragment.

Virtual tags are identified by having a specif ‘xyz_’ prefix. See below. You can not declare a tag with that prefix as out_label of any step.

(The tag ‘ReadName’ is also reserved for usage in StoreTagsInTable’s index column)

Tag Types #

fastqrab supports four tag types:

(None of the subsequent step listings below are exhaustive).

Location+Sequence Tags #

Represent a region within a segment, storing:

  • A segment reference,
  • Start position (0-based, inclusive)
  • End position (0-based, exclusive)
  • The extracted sequence (which will never change).

If you modify the segment’s sequence, tag positions may become invalid (for steps that write back into the sequence). The extracted sequence however is always retained.

Created by:

Used for example by:

Sequence-Only Tags #

Store just a sequence string without positional information.

Created by:

Used by:

Numeric Tags #

Store floating-point or integer values representing computed metrics.

Some steps declare ranges on the tag (lower..=upper, left & right inclusive, e.g.

  • CalcGCContent declares 0..=1 if relative=true). The thresholds in FilterbyNumericTag are then checked against these limits.

Created by:

Used by:

Boolean Tags #

Store true/false flags indicating fragment properties.

Created by:

Used by:

Tag Lifecycle #

Tags follow a strict life-cycle enforced by the processor:

  1. Definition: A step with out_label creates a tag
  2. Consumption: Steps with in_label or in_labels read the tag
  3. Transformation: Convert steps modify tags into new tags
  4. Removal: Consuming steps may delete tags (e.g., ForgetTag)

Validation: At startup, the processor verifies:

  • Every tag is defined before use
  • Every defined tag is eventually consumed
  • The types of consumed tags match step expectations
  • Tag names follow the naming rules

This catches typos (e.g., in_label = "adaptor" when you created out_label = "adapter") before processing begins.

Tag Naming Rules #

Tag labels must:

  • Match the regex [a-zA-Z_][a-zA-Z0-9_]*
  • Be case-sensitive (mean_q ≠ Mean_Q)
  • Not be ReadName (reserved for table output)
  • Not start with len_ (reserved for virtual tags in EvalExpression)

Good names:

  • adapter_r1
  • barcode_fwd
  • mean_quality_passing
  • gc_content

Invalid names:

  • mean-quality (contains hyphen)
  • 2adapter (starts with number)
  • ReadName (reserved)
  • len_adapter (reserved prefix)

Virtual tags #

Any place you can use a tag, you can also use virtual tags.

The following virtual tags are supported:

  • read_no - the sequential number of the molecule in the input.
  • len_<segment|all> - the length of the read (or the molecule) at this step in the pipeline.
  • len_<tag_name> - the length of a tag’s string value (for location tags, that’s after regex replacement etc). (requires a string or location typed tag)
  • location_<tag_name> - the location of a (location) tag, as of this step, as string segment:start..end (left inclusive, right exclusive, 0 based)
  • initial_location_<tag_name> - the location as it was when this tag was captured

The difference between location_ and initial_location_ is that the former reflects all read modification steps, such as trimming, since the definition of the tag, until the step using the virtual tag. Note that that means that locations that have been ‘clipped off’ will appear lost. The initial one retains the location-as-captured on tag definition.

Example Len Tags in EvalExpression #

When using EvalExpression, you can reference tag lengths with len_<tagname>:

[[step]]
    action = "ExtractIUPAC"
    segment = "read1"
    search = "NNNN"
    anchor = "anywhere"
    max_mismatches = 0
    out_label = "umi"

[[step]]
    action = "EvalExpression"
    expression = "len_umi == 4"    # Virtual tag: length of UMI
    out_label = "correct_umi_length"
    result_type = 'bool'

Conditional Processing #

Modifying tags can be applied conditionally:

# Tag long reads
[[step]]
    action = "EvalExpression"
    expression = "len_read1 < 100" 
    out_label = "is_short"
    result_type = 'bool'

# Filter differently based on tag (via boolean conversion)
[[step]]
    action = "Postfix"
    seq = "AGGGG"
    qual = "#####"
    segment = 'read1'
    if_tag = "is_short"  # Append postfix only to short reads

See Also #