[{"_1":2,"_219":-5,"_220":-5},"loaderData",{"_3":4,"_13":14,"_16":17,"_215":216},"root",{"_5":-5,"_6":-7,"_7":8,"_9":-7,"_10":11,"_12":-7},"currentUser","primaryEmail","siteVerification","6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","toast","enableDev",false,"incidentStatus","routes/_layout",{"_15":-5},"username","routes/_layout.r.$namespace.$reponame",{"_18":19,"_20":-5,"_21":11,"_22":11,"_23":24,"_25":26,"_27":-5,"_28":11,"_29":30,"_81":-5,"_82":83,"_214":11},"canonicalUrl","https://hub.docker.com/r/szsctt/isling/tags","mcpServer","canSeeDockerfile","canSeeAutobuilds","namespace","szsctt","reponame","isling","cloudBuildSource","isAutobuildsAvailable","repo",{"_31":32,"_33":34,"_36":37,"_38":39,"_40":11,"_41":42,"_43":44,"_45":46,"_49":26,"_23":24,"_50":51,"_52":35,"_53":54,"_55":56,"_57":58,"_59":-5,"_60":54,"_61":62,"_63":11,"_64":24,"_65":66,"_71":11,"_72":73,"_78":24,"_79":80},"categories",[],"content_types",[35],"image","date_registered","2020-12-19T00:18:10.279654Z","description","","is_private","last_updated","2024-02-12T04:16:26.644417Z","last_modified","2024-10-16T13:48:34.145251Z","media_types",[47,48],"application/vnd.docker.container.image.v1+json","application/vnd.oci.image.index.v1+json","name","pull_count",980,"repository_type","star_count",0,"status",1,"status_description","active","source","collaborator_count","full_description","# Isling\n\nIsling is a tool for detecting viral integration in paired-end reads.\n\n# Overview\n\nThe pipeline performs several steps in order to identify integration sites. It takes as input datasets consisting of either fastq files or bam files. It does some pre-processing of the reads (merging overlapping reads, optional) and then aligns them to both a host and a viral sequence. Reads are first aligned to the viral sequence(s), and then aligned reads are extracted and aligned to the host. These alignments are used to identify viral integrations.\n\n

\n\n\n# Dependencies\nIsling requires `snakemake` and either `singularity` (recommended) or `conda` to supply dependencies. Additionaly, `python` version 3.5 or above and `pandas` are required (these should be automatically installed if installing `snakemake` with `conda`.\n\nAlternativley, use the Docker version which contains isling and all dependencies.\n\n# Running\n\nTo run with the (included) test data locally, run:\n\n```\nsnakemake --configfile test/config/test.yml --cores \n```\n\n## Inputs\n\nA config file, as well as the host and viral references, and reads are required inputs. Specify all inputs in a config file.\n\n### Config file\n\nA yaml config file is used to specify the data to be processed and parameters for processing. The config file is organised into datasets, and specifies the parameters to be used for that dataset. If multiple datasets are present in the config file, they will be processed simultaneously. Each dataset contains a number of key-value pairs which indicate how the dataset is to be processed.\n\nThe first entry in the config file should be the key 'snakefile', with the value being the path to the directory containing the snakefile, for example:\n\n```\nsnakedir: \"/scratch1/sco305/intvi_pipeline\"\n```\n\nIf snakemake is run from the intvi_pipeline directory (which contains the `Snakefile`), this key may be omitted, otherwise it is required.\n\nThis should be followed by one block for each dataset to be processed. All paths should be either absolute or relative to the directory containing the `Snakefile`. An example dataset block from a config file:\n\n```\ndataset_name:\n read_folder: \"/path/to/read/folder\"\n out_dir: \"/path/to/output/\"\n samples:\n \t- \"sample1\"\n \t- \"sample2\"\n R1_suffix: \"_L001_R1.fastq.gz\"\n R2_suffix: \"_L001_R2.fastq.gz\"\n split: 2\n read1-adapt: \"AGATCGGAAGAGCACACGTCTGAACTCCAGTCA\"\n read2-adapt: \"AGATCGGAAGAGCGTCGTGTAGGGAAAGAGTGT\"\n mean-frag-len: \"estimate\"\n dedup: True\n dedup-subs: 2\n merge: True\n trim: True\n host_name: \"macFas5\"\n host_fasta: \"/path/to/refs/macFas5.fa\"\n virus_name: \"pAAV2-OTC_flop\"\n virus_fasta: \"/path/to/refs/pAAV2-OTC.fa\"\n clip-cutoff: 20\n min-mapq: 20\n cigar-tol: 3\n filter: \n - \"HostEditDist <= 5\"\n - \"ViralEditDist <= 5\"\n - \"NoAmbiguousBases < 20 or Type == discordant\"\n bed-include:\n - \"path/to/bed\"\n bed-exclude:\n - \"path/to/bed\"\n min-n-merge: 1\n merge-method: 'common'\n```\n\n#### Dataset name\n\nThe block should start with a name for the dataset. This can be anything, but each dataset name in the config file must be unique. This will be used to name output files.\n\n#### Read folder, samples, R1\\_suffix, R2\\_suffix, bam\\_suffix\n\nSpecify the path to the folder containing reads for this datset with the `read_folder` key. Reads must be paired-end. Reads can be in either fastq or sam/bam format.\n\nFor fastq reads, each R1 and R2 file must have a common suffix. Specify these common suffixes with `R1_suffix` and `R2_suffix`.\n\nFor bam files, all reads must be paired and files must have a common suffix, which should be specified with `bam_suffix`.\n\nSpecify either the `R1_suffix` and `R2_suffix`, or `bam_suffix`, but not both.\n\nThe key `samples` is optional. If it is included, it should be a list of sample names, which together with the suffixes above should describe the filenames of the input reads. Eg, if the input files are in fastq format, the input `read_folder`, `R1_suffix` and `R2_suffix`, and `samples` list should specify a list of files that can be found at `/` and `/`.\n\nIf the key `samples` is not included, sample names will be inferred from the files present in the `read_folder` having the specified suffixes. Note that this option requires files to be present on the local filesystem, and is therefore not compatible with cloud execution.\n\n#### Split FASTQ file\n\nThe optional `split` feature alllows to split the provided reads in `n` parts to decrease memory usage and to increase amount of possible threads.\n\n#### Adapters and mean fragment length.\n\nSpecify the adapters for read 1 and read 2, for trimming and merging, using the `read1-adapt` and `read2-adapt` keys. Specify either the mean fragment length, or use the string 'estimate' to indicate that the mean fragment length should be estimated from proper pairs in the alignments.\n\n#### Merging, adapter trimming\n\nThe keys `merge` and `trim` specify if the reads will be merged (if R1 and R2 are overlapping), or have their adapters trimmed using [SeqPrep](https://github.com/jstjohn/SeqPrep). The values for these keys must be either `True` or `False`. If `merge` is `True`, then adapters will be trimmed, regardless of whether `trim` was specified `True` or `False`.\n\n#### Host and virus references\n\nSpecify a name and one of either sequence (`fasta` format) or `bwa` index prefix for both the host and virus using the `host_name`, `host_fasta`, `host_prefix`, `virus_name`, `virus_fasta`, `virus_prefix` keys. The host reference may contian multiple chromosomes, and the virus reference may contain multiple viral sequences. If both a `fasta` file and `bwa` prefix are specified, only the prefix will be used.\n\n#### De-duplication\n\nThe key `dedup` indicates whether duplicate reads should be removed from the reads before merging, trimming and alignment using [bbmap Clumpify](https://jgi.doe.gov/data-and-tools/bbtools/bb-tools-user-guide/clumpify-guide/). Sequence-based duplicate removal is necessary since separate alignments are performed to the host and virus, and removing duplicates from these alignments can result in missing reads, since a read pair may appear to be a duplicate in one alignment (and hence would be removed), but may not be a duplicate in the other alignment. Note that only reads where both members of the pair are duplicates will be removed. Use the parameter `dedup-subs` to set the number of substitutions allowed for reads to be considered duplicates. Since this step is memory-intensive, it is not recommended for large datasets.\n\n#### Options for integration detection (`clip-cutoff`, `min-mapq`, `cigar-tol`)\n\nWhen detecting integrations, only primary alignments with a mapping quality equal to or greater than `min-mapq` will be considered. This number must be between 0 and 60. This paramter is optional, and if not set then a default value of 10 will be used.\n\nThe parameter `clip-cutoff` is used when detecting chimeric integrations: in the case of a simple junction, this parameter is the minimum nubmer of bases that must come from both host and virus. That is, for a `clip-cutoff` value of 20, the read must contain at least 20 bases from the host and 20 bases from the virus. For short integrations (host on either end, virus in the middle), both ends of the read must contain this many bases from the host. For discordant read pairs, a mapped read may contain at most this number of unmapped bases, and an unmapped read may contain at most this number of mapped bases. This paramter is optional, and if not set then a default value of 20 will be used.\n\nThe parameter `cigar-tol` is relevant when there are a small number of non-mapped bases between two mapped regions, or between one mapped region and the end of the read. If the number of these non-mapped bases is equal to or less than `cigar-tol`, then they will be combined with the nearest mapped region. For example, for `cigar-tol: 3` `147M3S` would become `150M`, `98M2I50M` would become `150M`, but `145M5S` would remain unchanged.\n\n#### Post-processing\n\nAfter detection, junction reads/read pairs may be filtered using post-processing. The following types of post-processing are availble:\n\n1. `filter`: Remove any integrations not meeting user-defined criteria. Criteria can be based on the following columns:\n\t- *NoAmbiguousBases* (integer) - the number of bases in a gap or overlap between host and viral alignments\n\t- *OverlapType* (‘none’, ‘gap’, ‘overlap’, ‘discordant’) - type of overlap between host and viral alignments\n\t- *Orientation* (‘hv’, ‘vh’) - in the host, is the junction host-virus (+) or virus-host (-)\n\t- *ViralOrientation* (‘+’, ‘-’) - orientation in which the virus/vector is integrated\n\t- *HostEditDist* (integer) - edit distance of the alignemnt to the host\n\t- *ViralEditDist* (integer) - edit distnace of the alignment to the virus/vector\n\t- *TotalEditDist* (integer) - sum of host and viral edit distances, plus the length of any bases in a gap between host and virus\n\t- *PossibleHostTranslocation* ('True', 'False') - does the read have two complementary alignments to the host genome?\n\t- *PossibleVectorRearrangement* ('True', 'False') - does the read have two complementary alignments to the virus/vector\n\t- *HostAmbiguousLocation* ('True', 'False') - is there a secondary alignment equivalent (same CIGAR) to the primary alignment in the host?\n\t- *ViralAmbiguousLocation* ('True', 'False') - is there a secondary alignment equivalent (same CIGAR) to the primary alignment in the virus/vector?\n\t- *Type* (‘chimeric’, ‘discordant’, 'short') - is this read chimeric, a discordant pair, or does it span both junctions (host/virus/host)?\n\t- *HostMapQ* (integer) - mapping quality of the host alignment\n\t- *ViralMapQ* (integer) - mapping quality of the virus/vector alignment\n\t\n2. `bed-exclude`: Specify a list of `bed` files in order to exclude any integrations that fall within the regions in those `bed` files\n3. `bed-include`: Specify a list of `bed` files in order to only include integrations that fall within the regions in those `bed` files\n\n\nTODO:\n5. `nearest-bed`: Specify a list of `bed` files in order to annotate each integration with the nearest feature in each `bed` file, and the distance between the integration and that feature\n6. `nearest-gtf`: Similar to `nearest-bed`, but with a `gtf` file rather than an `bed` file\n\n#### Merging\n\nIntegration events with overlapping coordinates and the same orientations are merged. There are two modes of merging: in `exact` merging, integrations are only merged if their coordinates are exactly the same in both host and virus/vector, and in `common` merging, integrations are merged if they share common coordinates in both host and virus/vector. The output coordinates in the latter case are the coordinates of the common bases.\n\nUsers may be interested only in integrations with a minimum number of supporting reads. The key `merge-n-min` restricts output to integrations with at least this number of integrations. This file contains the number of reads merged, and the read IDs, so the user can refer back to the summary excel file for more information about each read.\n\n#### Special dataset options\n\nFor convenience, a `global` dataset may additionally be included in the config file. Options from this dataset will be applied to all other datasets in which the `global` dataset contains an option that is not set in the other dataset. For keys that are specified in both, the option from the other dataset will be used (ie `global` options don't overwrite values from other datasets). For example, if the following config file is used:\n\n```\nglobal:\n out_dir: \"/path/to/output/\"\n R1_suffix: \"_L001_R1.fastq.gz\"\n R2_suffix: \"_L001_R2.fastq.gz\"\n read1-adapt: \"AGATCGGAAGAGCACACGTCTGAACTCCAGTCA\"\n read2-adapt: \"AGATCGGAAGAGCGTCGTGTAGGGAAAGAGTGT\"\n merge: True\n trim: True\n host_name: \"macFas5\"\n host_fasta: \"/path/to/refs/macFas5.fa\"\n virus_name: \"pAAV2-OTC_flop\"\n virus_fasta: \"/path/to/refs/pAAV2-OTC.fa\"\n dedup: False\n clip-cutoff: 20\n min-mapq: 10\n cigar-tol: 3\n post:\n - filter\n - dedup\n - mask-exclude:\n - \"/path/to/exclude.bed\"\n - nearest-gtf:\n - \"/path/to/genes.gtf\"\n merge-dist: 100\n \ndataset-1:\n read_folder: \"/path/to/read/folder/1\"\n samples:\n \t- \"sample1\"\n \t- \"sample2\"\n \ndataset-2:\n read_folder: \"/path/to/read/folder/2\"\n bam_suffix: \".bam\"\n```\n\ntwo datasets (`dataset-1` and `dataset-2`) will be analysed. `dataset-1` will consist of samples `sample1` and `sample2`, and `dataset-2` will consist of all the `bam` files in the directory `/path/to/read/folder/2`.\n\n","has_starred","hub_user","immutable_tags_settings",{"_67":11,"_68":69},"enabled","rules",[70],".*","is_automated","permissions",{"_74":75,"_76":11,"_77":11},"read",true,"write","admin","user","storage_size",51050468317,"orgData","recentTags",[84,128,138,144,154,164,174,184,194,204],{"_85":35,"_86":87,"_88":89,"_90":91,"_92":93,"_94":95,"_41":117,"_118":87,"_119":24,"_120":48,"_49":121,"_122":123,"_124":102,"_125":117,"_126":110,"_127":75},"content_type","creator",10452405,"digest","sha256:b8253a9a84a595ada4c542e22bdf5cb79f61f645a7f24d1ceabd39f611dcdfbc","full_size",1033841550,"id",199175083,"images",[96,112],{"_97":98,"_88":99,"_100":39,"_101":102,"_103":104,"_105":106,"_107":39,"_108":-5,"_109":91,"_55":110,"_111":-5},"architecture","amd64","sha256:27c79e92c2aa7b779f5ee407366e96355590ef2681478e33a31e12282568311f","features","last_pulled","2025-12-02T08:47:55.160720978Z","last_pushed","2024-02-12T04:16:26Z","os","linux","os_features","os_version","size","inactive","variant",{"_97":113,"_88":114,"_100":39,"_101":115,"_103":104,"_105":113,"_107":39,"_108":-5,"_109":116,"_55":110,"_111":-5},"unknown","sha256:2b584b098886b919888f7be4f05a53f72691dd7187cf6d43816194e88ae868e2","2024-09-27T04:24:21Z",1257,"2024-02-12T04:16:25.646005Z","last_updater","last_updater_username","media_type","master","repository",10488950,"tag_last_pulled","tag_last_pushed","tag_status","v2",{"_85":35,"_86":87,"_90":129,"_92":130,"_94":131,"_41":136,"_118":87,"_119":24,"_120":47,"_49":137,"_122":123,"_124":134,"_125":136,"_126":58,"_127":75},996040622,130803416,[132],{"_97":98,"_88":133,"_100":39,"_101":134,"_103":135,"_105":106,"_107":39,"_108":-5,"_109":129,"_55":58,"_111":-5},"sha256:0179ce61695d56aa630969cc4b7e0d29f1ed649b1e8d1157b54ac3e4406a33b4","2026-02-17T09:45:07.537179543Z","2022-03-24T04:32:22Z","2022-03-24T04:32:22.028326Z","latest",{"_85":35,"_86":87,"_90":129,"_92":139,"_94":140,"_41":142,"_118":87,"_119":24,"_120":47,"_49":143,"_122":123,"_124":134,"_125":142,"_126":58,"_127":75},199177330,[141],{"_97":98,"_88":133,"_100":39,"_101":134,"_103":135,"_105":106,"_107":39,"_108":-5,"_109":129,"_55":58,"_111":-5},"2022-03-24T04:32:21.713567Z","v1.0",{"_85":35,"_86":87,"_90":145,"_92":146,"_94":147,"_41":152,"_118":87,"_119":24,"_120":47,"_49":153,"_122":123,"_124":150,"_125":152,"_126":110,"_127":75},996039285,199174396,[148],{"_97":98,"_88":149,"_100":39,"_101":150,"_103":151,"_105":106,"_107":39,"_108":-5,"_109":145,"_55":110,"_111":-5},"sha256:6254c2b8220efcfbf88001afb1e81765c31ebb8721096f0269041c10faa01857","2025-08-21T14:30:36.511368718Z","2022-03-24T04:03:32Z","2022-03-24T04:03:32.266729Z","sha-1091f34",{"_85":35,"_86":87,"_90":155,"_92":156,"_94":157,"_41":162,"_118":87,"_119":24,"_120":47,"_49":163,"_122":123,"_124":160,"_125":162,"_126":58,"_127":75},1001470404,195332106,[158],{"_97":98,"_88":159,"_100":39,"_101":160,"_103":161,"_105":106,"_107":39,"_108":-5,"_109":155,"_55":58,"_111":-5},"sha256:aa78f2d862688f23ab1d2e15d791d46806f0b8be45923df52597df735eba7485","2026-02-10T23:16:06.232343374Z","2022-03-03T08:51:15Z","2022-03-03T08:51:15.565932Z","sha-7abe838",{"_85":35,"_86":87,"_90":165,"_92":166,"_94":167,"_41":172,"_118":87,"_119":24,"_120":47,"_49":173,"_122":123,"_124":170,"_125":172,"_126":110,"_127":75},1003452487,183718734,[168],{"_97":98,"_88":169,"_100":39,"_101":170,"_103":171,"_105":106,"_107":39,"_108":-5,"_109":165,"_55":110,"_111":-5},"sha256:715d1ff5b944aec3012919d92ca5e9a049a82d8a7359fa3b42a8d072a4d95f10","2025-08-21T14:30:36.616901267Z","2021-12-21T06:56:53Z","2021-12-21T06:56:52.85565Z","sha-04f78aa",{"_85":35,"_86":87,"_90":175,"_92":176,"_94":177,"_41":182,"_118":87,"_119":24,"_120":47,"_49":183,"_122":123,"_124":180,"_125":182,"_126":110,"_127":75},1003440613,183701996,[178],{"_97":98,"_88":179,"_100":39,"_101":180,"_103":181,"_105":106,"_107":39,"_108":-5,"_109":175,"_55":110,"_111":-5},"sha256:d6aeadb8529c8498bca44a601a819b7070051160dc857f8a9b355047b90bff3c","2025-08-21T14:30:36.513115722Z","2021-12-21T04:03:03Z","2021-12-21T04:03:03.537883Z","sha-3f11633",{"_85":35,"_86":87,"_90":185,"_92":186,"_94":187,"_41":192,"_118":87,"_119":24,"_120":47,"_49":193,"_122":123,"_124":190,"_125":192,"_126":110,"_127":75},1003048881,177030830,[188],{"_97":98,"_88":189,"_100":39,"_101":190,"_103":191,"_105":106,"_107":39,"_108":-5,"_109":185,"_55":110,"_111":-5},"sha256:b62c5278e33707d77e0b4c692a473d05a74bf6b35a06c27ac5b5eb2a9c675b0e","2025-08-21T14:30:36.546403615Z","2021-11-12T02:25:08Z","2021-11-12T02:25:07.189707Z","1.1",{"_85":35,"_86":87,"_90":195,"_92":196,"_94":197,"_41":202,"_118":87,"_119":24,"_120":47,"_49":203,"_122":123,"_124":200,"_125":202,"_126":110,"_127":75},1153041448,130915704,[198],{"_97":98,"_88":199,"_100":39,"_101":200,"_103":201,"_105":106,"_107":39,"_108":-5,"_109":195,"_55":110,"_111":-5},"sha256:fc25da87792ff9861d049898690c78db39b5f7650029ac90254aab4dd5cc4194","2025-08-21T14:30:36.583077826Z","2021-08-02T04:13:07Z","2021-08-02T04:13:24.647115Z","1",{"_85":35,"_86":87,"_90":205,"_92":206,"_94":207,"_41":212,"_118":87,"_119":24,"_120":47,"_49":213,"_122":123,"_124":210,"_125":212,"_126":58,"_127":75},932902097,151435142,[208],{"_97":98,"_88":209,"_100":39,"_101":210,"_103":211,"_105":106,"_107":39,"_108":-5,"_109":205,"_55":58,"_111":-5},"sha256:ff4516ef45db11449a814e603e640c9992f7c3eb6fe86577068f14a0c7381b49","2026-02-10T23:16:39.447785055Z","2021-05-28T13:03:21Z","2021-05-28T13:03:20.598794Z","test","isPotentialSpam","routes/_layout.r.$namespace.$reponame.tags",{"_217":75,"_218":11},"isRunInDesktopEnabled","canDeleteTags","actionData","errors"]