Package: tmerge
tmergeBuild highly accurate full-length transcripts from third generation sequencing alignments.tmerge compares transcript structures (or read-to-genome alignments) present in the input and attempts to reduce transcript redundancy, i.e., merge compatible input transcripts into non-redundant transcript models.tmerge is fast and can typically process several millions of aligned long reads in a few minutes.Installationpip install tmergeIt is recommended to install tmerge within avirtual environmentUsagetmerge offers both a CLI and a Python module. The CLI is built upon the Python module and includes several built in "plugins" (see below for description of plugins).CLIOnce you have installed tmerge via pip, the CLI will be available on your PATH. If you have installed tmerge into a virtual environment, you will need to activate that virtual environment to run the CLI.Runtmerge --helpfor a description of the options.Python moduleYou may import tmerge as a Python module and call themergefunction to run it.mergetakes 2 mandatory kwargs (input_pathandoutput_path) and two optional kwargs (toleranceandprocesses). Any additional keyword arguments will be sent to any registered plugins (see below).fromtmergeimportmergeinput_path="my.gff"output_path="output.gff"merge(input_path=input_path,output_path=output_path)# Will block until completion# Can now do more things with the output filewithopen(output_path,"a")asf:f.write("# A comment\n")f.flush()PluginsPlugins allow you to "hook" into tmerge's lifecycle events and allow you to view, edit or remove the transcripts passing through tmerge and adapt it to your lab's specific needs. For example, adding Hi-Seq support.This section explains how to write plugins and register them to tmerge.Transcript Models and ContigsBefore writing a plugin, it is important to understand the concept of Transcript Models and Contigs. Transcripts are represented in tmerge asTranscriptModelobjects, at first these are the transcripts defined in the input file but are altered throughout the lifecycle of tmerge, either having other transcript models merged into them or removed entirely. Contigs are lists of overlapping transcript models. Merging of transcript models is only performed within a contig and not between contigs.Plugin classA plugin is a simple class that registers itself to one or more "hooks" in it's init method. It receives thehooksdict as it's first argument followed by all of the kwargs that are passed totmerge.merge.classCounter:def__init__(self,hooks,**kwargs):self.count=0hooks["transcript_added"].tap(self.add_one)defadd_one(self,*args):self.count+=1defprint(self,*args);print(f"There are{self.count}transcripts")Editing transcriptsSome of the hooks send transcripts to the hooked-in function (see table below). You can edit or remove any of these transcripts and changes will be reflected in the output merged file. Further, any key/value pairs added to themetadict will be appended to the "attributes" column of the output merged GFF.classMyPointlessPlugin:def__init__(self,hooks,extra_attribute,bad_id,**kwargs):self.extra_attribute=extra_attributeself.bad_id=bad_idhooks["transcript_added"].tap(self.add_meta)hooks["contig_merged"].tap(self.remove_if_matches)defadd_meta(self,transcript,*args):# When tmerge.merge(input_path=output, output_path=output, extra_attribute="Pointless") is ran 'extra: "Pointless"' will be added to the attributes column for every transcriptself.transcript.meta["extra"]=self.extra_attributedefremove_if_matches(self,contig,*args):# Running tmerge.merge(input_path=output, output_path=output, bad_id="bad") will remove any transcript with the id of "bad" from the resultfortranscriptincontig:iftranscript.id=self.bad_id:transcript.remove()# Flags a transcript for removalRegistering pluginsSimple listThe easiest way to provide tmerge with plugins is to pass thepluginskwarg totmerge.merge.frommypluginsimportMySimplePlugin,MyAdvancedPluginfromtmergeimportmergemerge(input_path="input.gff",output_path="output.gff",plugins=[MySimplePlugin,MyAdvancedPlugin])Dynamic Plugin DiscoveryIf you're already using setup_tools in your project, then you can usedynamic plugin discoveryto easily drop in plugins to tmerge.In your project'ssetup.pyadd your plugin to thetmerge.pluginsgroup:# setup.pysetup(...entry_points={"tmerge.plugins":"plugin_name = my.plugin.module.MyPlugin"})This will automatically register your plugin with tmerge and the plugin will be executed withtmerge.merge.Lifecycle eventsHook NameWhen?Arguments sent to hooked-in functionschromosome_parsedWhen one chromosome is parsed from the inputchromosome(list ofTranscriptModels)transcript_addedWhen a transcript is added to a contigtranscript(TranscriptModel)contig_builtWhen one contig (group of overlapping transcripts) is builtcontig(list ofTranscriptModels)transcripts_mergedWhen one transcript is merged into anotherhost_transcript(TranscriptModel),merged_transcript(TranscriptModel)host_transcriptis the transcript that has hadmerged_transcriptmerged into itcontig_mergedWhen one contig is fully mergedcontig(list ofTranscriptModels)contig_completeContig has been fully merged, transcript flagged for removal removed, and queued for writingcontig(list ofTranscriptModels)merging_completeAll transcripts have been mergedNonepre_sortJust before the merged output is sortedNonepost_sortJust after the merged output is sortedNonecompleteEverything completeNoneExamplesSee theplugins/folder for examples of various plugins.AuthorsJulien Lagarde, CRG, Barcelona, contactjulienlag@gmail.comJacob Windsor, CRG, Barcelona, contactme@jcbwndsr.com