Tag Usage on fastqrab documentation

Mon, 01 Jan 0001 00:00:00 +0000

ConcatTags #

Concatenate multiple tags into a single tag.

# ignore_in_test
[[step]]
 action = "ConcatTags"
 in_labels = ["mytag", "mytag2"] # list of tags to concatenate (minimum 2)
 out_label = "combined" # output tag name
 on_missing = "merge_present" # required: "merge_present" or "set_missing"
 separator = "_" # (optional) separator for string concatenation

This transformation combines multiple tags into a single output tag. The behavior depends on the types of input tags and how missing tags are handled.

Behavior by Tag Type #

Location Tags Only #

When all input tags are location tags (e.g., from ExtractIUPAC, ExtractAnchor), the transformation:

Mon, 01 Jan 0001 00:00:00 +0000

ForgetAllTags #

Remove every tag currently stored for the read batch.

[[step]]
 action = "ForgetAllTags"

Use this when you want to clear all tag labels before continuing. It is handy after persisting tags to an external table, or before running steps that must not see previously extracted metadata.

Mon, 01 Jan 0001 00:00:00 +0000

ForgetTag #

Forget about a tag. Useful if you want to store tags in a table, but not this one.

[[step]]
 action = "ForgetTag"
 in_label = "mytag"

This transformation removes a specified tag from the molecule’s tag collection.

Mon, 01 Jan 0001 00:00:00 +0000

StoreTagBackInSequence #

Store the tag’s replacement in the sequence, replacing the original sequence at that location.

[[step]]
 action = "StoreTagBackInSequence"
 in_label = "mytag"
 ignore_missing = true # if false, an error is raised if the tag is missing

This transformation stores the tag’s value back into the sequence, replacing the original sequence at that location.

Note that if this changes the length of the sequence, existing location tags will loose their location data (retaining their sequence though).

Mon, 01 Jan 0001 00:00:00 +0000

StoreTagInComment #

Store currently present tags as comments on read names.

[[step]]
 action = "StoreTagInComment"
 in_labels = ["mytag"] # Store these tags. Not optional. May be a single string as well. Alias 'in_label'
 segment = "read1" # Any of your input segments, or 'All'
 comment_insert_char = " " # (optional) char at which to insert comments
 comment_separator = "|" # (optional) char to separate comments
 region_separator = "_" # (optional) char to separate regions in a tag, if it has multiple

Comments are key=value pairs, separated by comment_separator which defaults to ‘|’. They get inserted before the first comment_insert_char, which defaults to input.options.read_comment_char.

Mon, 01 Jan 0001 00:00:00 +0000

StoreTagsInTable #

Store the tags in a TSV table.

[[step]]
 action = "StoreTagsInTable"
 infix = "tags"
 compression = "Raw" # Raw, Gzip, Zstd
 region_separator = "_" # (optional) char to separate regions in a tag, if it has multiple
 in_labels = ["mytag", ] # Store just these tags. Optional, all tags store if not set
 include_read_name = true # (optional) include the ReadName column. Default: true

This transformation writes all current tags to a tab-separated values (TSV) table file for further analysis.

Store Tag In FASTQ

Mon, 01 Jan 0001 00:00:00 +0000

StoreTagInFastQ #

# Store the content of a tag in a fastq file.
# Needs a 'location 'tag'.
# Can store other tags in the read name.
# quality scores are set to '~'.
# With demultiplexing: creates separate files per barcode
 [[step]]
 action = "StoreTagInFastQ"
 in_label = "mytag" # tag to store. File name is derived with this as infix
 format = "Fastq" # FASTQ / FASTA / BAm
 compression = "gz" # or "zstd" | "none" # (optional) compression format, not if format == BAM
 compression_level = 6 # (optional) compression level for gzip (0-9) or zstd (1-22)
 					 # defaults: gzip=6, zstd=5
 comment_tags = []# e.g. ["other_tag"] # see StoreTagInComment
 comment_insert_char = ' ' # (optional) char at which to insert comments
 comment_separator = '|' # (optional) char to separate comments
 region_separator = "_" # (optional) char to separate regions in a tag, if it has multiple

Store the sequence of a tag in a fastq file, with other tags (and virtual tags) optionally stored in the read name as comments.

Mon, 01 Jan 0001 00:00:00 +0000

StoreTagInSequence #

Insert a tag’s string value into a read sequence at the position defined by another location tag.

[[step]]
 action = "StoreTagInSequence"
 in_value_label = "mytag" # location or string tag to insert
 in_position_label = "mytag2" # location tag defining where to insert
 anchor = "Start" # "Start"/"left" or "End"/"right"

Parameters #

Parameter	Type	Required	Description
`in_value_label`	location or string tag	yes	Tag whose sequence is inserted into the read
`in_position_label`	location tag	yes	Tag that defines the insertion position
`anchor`	`"Start"` / `"left"` / `"End"` / `"right"`	yes	Whether to insert before the leftmost position (`Start`) or after the rightmost end (`End`) of the position tag

How it works #

in_position_label is a location tag pointing to a region (or multiple regions) in a read. The insertion point is derived from the anchor:

Mon, 01 Jan 0001 00:00:00 +0000

AssignToReference #

Assign each query sequence to the closest entry in barcodes section, using Hamming distance.

( As opposed to HammingCorrect which will correct to the closest barcode sequence).

At start-up the step builds an efficient Hamming-distance index over the database. For every read, the tag supplied in in_label is looked up in the index and the name of the closest matching reference entry is written to out_label as a string tag.

Mon, 01 Jan 0001 00:00:00 +0000

HammingCorrect #

Correct a tag to one of a predefined set of ‘barcodes’ using closest hamming distance.

[[step]]
 action = "HammingCorrect"
 in_label = "mytag"
 out_label = "my_corrected_tag"
 barcodes = "mybarcodelist"
 max_hamming_distance = 1
 on_no_match = 'remove' # 'remove', 'empty', 'keep'
 name_split_character = '|' # optional

[barcodes.mybarcodelist]
 "AAAA" = "label_ignored" # only read when demultiplexing

on_no_match controls what happens if the tag cannot be corrected within the max_hamming_distance:

remove: Remove the hit (location and sequence), useful for FilterByTag later.
keep: Keep the original tag (and location)
empty: Keep the original location, but set the tag to empty.

Note that hamming_correction removes the location information on tags if they spanned more than one region. (This is an implementation limitation, not a conceptual one).