{"id":13710363,"url":"https://github.com/adnaniazi/tailfindr","last_synced_at":"2025-05-06T19:30:55.243Z","repository":{"id":41902162,"uuid":"142865477","full_name":"adnaniazi/tailfindr","owner":"adnaniazi","description":"An R package for estimating poly(A)-tail lengths in Oxford Nanopore RNA and DNA reads.","archived":false,"fork":false,"pushed_at":"2024-10-14T06:20:18.000Z","size":19434,"stargazers_count":53,"open_issues_count":17,"forks_count":18,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-13T20:40:45.580Z","etag":null,"topics":["bioinformatics","cdna","nanopore","r","rna"],"latest_commit_sha":null,"homepage":"https://www.cbu.uib.no/valen/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adnaniazi.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-30T11:17:54.000Z","updated_at":"2024-10-29T17:13:05.000Z","dependencies_parsed_at":"2024-06-10T15:10:31.089Z","dependency_job_id":null,"html_url":"https://github.com/adnaniazi/tailfindr","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adnaniazi%2Ftailfindr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adnaniazi%2Ftailfindr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adnaniazi%2Ftailfindr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adnaniazi%2Ftailfindr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adnaniazi","download_url":"https://codeload.github.com/adnaniazi/tailfindr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252753200,"owners_count":21798930,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioinformatics","cdna","nanopore","r","rna"],"created_at":"2024-08-02T23:00:55.015Z","updated_at":"2025-05-06T19:30:51.852Z","avatar_url":"https://github.com/adnaniazi.png","language":"R","funding_links":[],"categories":["Software packages"],"sub_categories":["Poly(A) tail length estimation"],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\noptions(tibble.print_min = 5, tibble.print_max = 5)\n```\n\n\u003cimg src=\"man/figures/tailfindr-logo.png\" width=\"100\" /\u003e\n\n\n\n\u003c!-- badges: start --\u003e\n\n\u003c!-- badges: end --\u003e\n\n## tailfindr?\n\ntailfindr is a R package for estimating poly(A)-tail lengths in Oxford Nanopore reads. \n\n## Features of *tailfindr*\n\n* Works for both RNA and DNA reads. In the case of DNA reads, it estimates both poly(A)- and poly(T)-tail lengths.\n* Supports data that has been basecalled with Albacore or Guppy. It also support data that has been basecalled using the newer 'flipflop' model.\n* Can work on single or multi-fast5 file reads.\n\n*tailfindr* has been developed at [Valen Lab](https://www.cbu.uib.no/valen/) in [Computational Biology Unit](https://www.cbu.uib.no/) at the [University of Bergen](https://www.uib.no/), Norway.\n\n## Installation\n\n#### Step 1. Installing VBZ plugin\n\nVBZ is a compression format used by Nanopore to compress the data inside a FAST5 file. You must install VBZ plugin for your operating system so that tailfindr can successfully read FAST5 files. Download and install VBZ plugin from [here](https://github.com/nanoporetech/vbz_compression/releases).\n\n\n#### Step 2. Installing HDF5 library\n\ntailfindr depends on the HDF5 library for reading Fast5 files. For OS X and Linux, the HDF5 library needs to be installed via one of the (shell) commands specified below:\n\n| System                                    | Command\n|:------------------------------------------|:---------------------------------|\n|**OS X (using Homebrew)**                  | `brew install hdf5`\n|**Debian-based systems (including Ubuntu)**| `sudo apt-get install libhdf5-dev` \n|**Systems supporting yum and RPMs**        | `sudo yum install hdf5-devel`\n\nHDF5 1.8.14 has been pre-compiled for Windows and is available [here](https://github.com/mannau/h5-libwin) \u0026mdash; thus no manual installation is required.\n\n#### Step 3. Installing devtools\nCurrently, *tailfindr* is not listed on CRAN/Bioconductor, so you need to install it using `devtools`. To install `devtools` use the following command in R/R-studio:\n\n```{r, message = FALSE, eval = FALSE}\ninstall.packages(\"devtools\")\n```\n\n#### Step 4. Installing rbokeh\nrbokeh has been delisted from CRAN and therefore tailfindr cannot install itself. You need to manually install it yourself using the command below: \n\n```{r, message = FALSE, eval = FALSE}\ndevtools::install_url('https://cran.r-project.org/src/contrib/Archive/rbokeh/rbokeh_0.5.1.tar.gz', type = \"source\", dependencies = TRUE)\n```\n\n#### Step 5. Installing tailfindr\n\nNow you can install tailfindr using the command below in R/R-studio:\n````{r, message = FALSE, eval = FALSE}\ndevtools::install_github(\"adnaniazi/tailfindr\")\n```\nIf you also want to build the vignette while installing tailfindr, then run the command below:\n```{r, message = FALSE, eval = FALSE}\nremotes::install_github('adnaniazi/tailfindr', build = TRUE, build_opts = c(\"--no-resave-data\", \"--no-manual\"), force = TRUE)\n```\n\nNow you are ready to use *tailfindr*.\n\n## Usage\n\n#### 1. Minimal working example\n\n`find_tails()` is the main function that you can use to find tail lengths in both RNA and DNA reads. It saves a CSV file containing all the tail-length data. Furthermore, it also returns the same data as a tibble. \n\nGive below is a minimal use case in which we will run tailfindr on example RNA reads present in the tailfindr package. \n\n```{r, message = FALSE, eval = FALSE}\nlibrary(tailfindr)\ndf \u003c- find_tails(fast5_dir = system.file('extdata', 'rna', package = 'tailfindr'),\n                 save_dir = '~/Downloads',\n                 csv_filename = 'rna_tails.csv',\n                 num_cores = 2)\n```\nIn the above example, *tailfindr* returns a tibble containing the tail data which is then stored in the variable `df`. tailfindr also saves this dataframe as a csv file (`rna_tails.csv`) in the user-specified `save_dir`, which in this case is set to `~/Downloads`. A logfile is also saved in the `save_dir`. The parameter `num_cores` can be increased depending on the number of *physical* cores at your disposal.\n\n#### 2. Plotting the tail\n\nAdditionally, *tailfindr* allows you to generate plots that show the tail location in the raw squiggle. You can save these plots as interactive `.html` files by using `'rbokeh'` as the `plotting_library`. You can zoom in on the tail region in the squiggle and see the exact location of the tail.\n\nGive below is a minimal use case in which we will run tailfindr on example cDNA reads present in the tailfindr package, and also save the plots:\n\n```{r, message = FALSE, eval = FALSE}\ndf \u003c- find_tails(fast5_dir = system.file('extdata', 'cdna', package = 'tailfindr'),\n                 save_dir = '~/Downloads',\n                 csv_filename = 'cdna_tails.csv',\n                 num_cores = 2,\n                 save_plots = TRUE,\n                 plotting_library = 'rbokeh')\n```\n![Poly(T) read squiggle plot](https://github.com/adnaniazi/tailfindr/raw/master/man/figures/poly_t_without_debug.gif)\n\nHowever, note that generating plots can slow down the performance of tailfindr. We recommend that you generate these plots only for a small subset of your reads.\n\n#### 3. Plotting the tail and debug traces\n\n*tailfindr* can plot additional information that it used while deriving the tail boundaries. Please read our preprint to learn how *tailfindr* works. To plot this information, set the `plot_debug_traces` parameter to `TRUE`.\n```{r, message = FALSE, eval = FALSE}\ndf \u003c- find_tails(fast5_dir = system.file('extdata', 'cdna', package = 'tailfindr'),\n                 save_dir = '~/Downloads',\n                 csv_filename = 'cdna_tails.csv',\n                 num_cores = 2,\n                 save_plots = TRUE,\n                 plot_debug_traces = TRUE,\n                 plotting_library = 'rbokeh')\n```\n![Poly(A) read squiggle plot](https://github.com/adnaniazi/tailfindr/raw/master/man/figures/poly_a_with_debug.gif)\n\n\n#### 4. Specifying custom basecall group\n*tailfindr* needs `Fastq` and `Events/Move` table to work on. By default, it searches for them in the `Basecall_1D_000` group in the Analyses section of the FAST5 file. If for whatever reason, you need *tailfindr* to read data from another basecall group -- lets say `Basecall_1D_001` -- then you can run *tailfindr* as below:\n```{r, message = FALSE, eval = FALSE}\ndf \u003c- find_tails(fast5_dir = system.file('extdata', 'rna_basecall_1D_001', package = 'tailfindr'),\n                 save_dir = '~/Downloads',\n                 csv_filename = 'rna_tails.csv',\n                 num_cores = 2,\n                 basecall_group = 'Basecall_1D_001',\n                 save_plots = TRUE,\n                 plot_debug_traces = TRUE,\n                 plotting_library = 'rbokeh')\n```\nIn this case, the input FAST5 have two basecall groups: `Basecall_1D_000` and `Basecall_1D_001` but we configured *tailfindr* to use `Events/Move` table from the `Basecall_1D_001` group.\n\nThere are more options available in the find_tails() function. Please see its [documentation](https://rdrr.io/github/adnaniazi/tailfindr/man/find_tails.html). \n\n#### 5. Specifying custom cDNA primers\n\nIf you have used custom front and end primers while designing you cDNA sequences, you can now specify them in *tailfindr*. *tailfindr* will use these sequences instead of the defaults ones to find the orientation of the reads and one of the ends of the poly(A)/(T) tail. Here is how you call *tailfindr* if you have used custom primers:\n\n```{r, message = FALSE, eval = FALSE}\ndf \u003c- find_tails(fast5_dir = system.file('extdata', 'cdna', package = 'tailfindr'),\n                 save_dir = '~/Downloads/tailfindr_output',\n                 csv_filename = 'cdna_tails.csv',\n                 num_cores = 4,\n                 dna_datatype = 'custom-cdna',\n                 front_primer = \"TTTCTGTTGGTGCTGATATTGCTGCCATTACGGCCGG\",\n                 end_primer = \"ACTTGCCTGTCGCTCTATCTT\")\n```\n\nImportant thing to note here is the use of three additional parameters: `dna_datatype`, `front_primer`, and `end_primer`.\n\n`front_primer` and `end_primer` sequences should always be specified in the 5' to 3' direction. \n\n![cDNA](https://github.com/adnaniazi/tailfindr/raw/master/man/figures/cdna_construct.png)\n\n\n\n\n### Description of the CSV/Dataframe columns\n*tailfindr* returns tail data in a dataframe and also saves this information in a user-specified CSV file. The columns generated depend on the whether *tailfindr* was run on RNA or DNA data. Below is a description of columns for both thses scenarios:\n\n##### When input data is RNA\n\n| Column Names   | Datatype  | Description                                                                                                |\n|:---------------|:----------|:-----------------------------------------------------------------------------------------------------------|\n| read_id        | character | Read ID as given in the Fast5 file                                                                         |\n| tail_start     | numeric   | Sample index of start site of the tail in raw data                                                         |\n| tail_end       | numeric   | Sample index of end site of the tail in raw data                                                           |\n| samples_per_nt | numeric   | Read rate in terms of samples per nucleotide                                                               |\n| tail_length    | numeric   | Tail length in nucleotides. It is the difference between `tail_end` and `tail_start` divided by `samples_per_nt` |\n| file_path      | character | Absolute path of the Fast5 file                                                                            |\n\n##### When input data is DNA\nHere are the columns that you will get from *tailfindr* if you have run it on DNA data:\n\n| Column Names   | Datatype         | Description                                                                                                                                                                       |\n|----------------|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| read_id        | character        | Read ID as given in the Fast5 file                                                                                                                                                |\n| read_type      | character factor | Whether a read is `\"polyA\"`, `\"polyT\"`, or `\"invalid\"`. Invalid reads are those in which *tailfindr* wasn't able to find Nanopore primers with high confidence.                           |\n| tail_is_valid  | logical          | Whether a poly(A) tail is a full-length read or not. This is important because a poly(A) tail is at the end of the read, and premature termination of reads is prevelant in cDNA. |\n| tail_start     | numeric          | Sample index of start site of the tail in raw data                                                                                                                                |\n| tail_end       | numeric          | Sample index of end site of the tail in raw data                                                                                                                                  |\n| samples_per_nt | numeric          | Read rate in terms of samples per nucleotide                                                                                                                                      |\n| tail_length    | numeric          | Tail length in nucleotides. It is the difference between `tail_end` and `tail_start` divided by `samples_per_nt`                                                                        |\n| file_path      | character        | Absolute path of the Fast5 file                                                                                                                                                   |\n## The devil👹 in the details\n\n* tailfindr needs the `Events/Move` table in the FAST5 file to calculate the read-specific normalizer -- `samples_per_nt` -- which is used to convert tail length in samples to tail length in nucleotides. If your data was basecalled with *MinKNOW-Live-Basecalling*, then the Events/Move table might not be saved in the FAST5 file. In such a case, you can rebasecall your reads and adjust the `basecall_group` parameter accordingly when calling `find_tails()` function as demonstrated in the use case # 4 above. This is because now the Events/Move table will now be under `Basecall_1D_001` instead of  *tailfindr's* default search location `Basecall_1D_000`. See the figure below: The panel on left shows that the MinKNOW live basecalled read; it has no Event/Move table. The panel on the right shows the same read after it has been re-basecalled using standalone Guppy. Now there is Event/Move table under the freshly-added basaecall group (`Basecall_1D_001`). `find_tails()`  should be called with `basecall_group` set to `\"Basecall_1D_001\"` as shown in the use case # 4 above.\n\n![MinKNOW Live Basecalling problem](https://github.com/adnaniazi/tailfindr/raw/master/man/figures/minkow_live_basecalling.png)\n\n\n* For DNA data, *tailfindr* decides whether a read is poly(A) or poly(T) based on finding Nanopore primers/adaptors. If you are using the flipflop model to basecall DNA data, please ensure that the nanopore adaptors are not trimmed off while basecalling. This can be done by turning off `enabling_trimming` option in the basecalling script. The script below shows you how we have basecalled our reads using the flipflop model\n\n```{r, engine='bash', message = FALSE, eval = FALSE}\n#!/bin/sh\nINPUT=/raw/fast5/files/path/\nOUTPUT=/output/folder/path/\nguppy_basecaller \\\n    --config dna_r9.4.1_450bps_flipflop.cfg \\\n    --input $INPUT \\\n    --save_path $OUTPUT \\\n    --recursive \\\n    --fast5_out \\\n    --hp_correct 1 \\\n    --disable_pings 1 \\\n    --enable_trimming 0 \n```\n\n* *tailfindr* has been tested and validated using the following sequencing kits:\n1. SQK-RNA001 and SQK-RNA002 for RNA \n2. SQK-LSK108 and SQK-LSK109 for DNA\n3. SQK-PCS110 for PCR cDNA\n\n\n* *tailfindr* has been tested and validated using the basecallers:\n1. Albacore v2.3.1 and v2.3.3.\n2. Guppy v2.2.2, v2.3.1, v3.0.1. Guppy v2.2.2, v2.3.1 were tested with flipflop basecalling for DNA, and Guppy v3.0.1 was tested with flipflop basecalling for RNA.\n\n## Want to know more?\nWe have written a book chapter on how you can use *tailfindr* for transcript isofrom-specific poly(A) tail profiling. It has a detailed protocol and analysis pipeline for processing the data through *tailfindr* .The chapter can be downloaded from [here](https://adnaniazi.com/website-assets/niazi_and_krause_2019_springer_book_chapter.pdf).\n\n\n## Getting help\n\nIf you encounter a clear bug, please file a minimal reproducible example on [github](https://github.com/adnaniazi/tailfindr/issues). Please do provide us a few reads (around 10) so that we can reproduce the problem at our end, and figure out a solution for you.\n\n## Citation\nKrause, M., Niazi, A. M., Labun, K., Cleuren, Y. N. T., Müller, F. S., \u0026 Valen, E. (2019). *tailfindr*: alignment-free poly(A) length measurement for Oxford Nanopore RNA and DNA sequencing. Rna, 25(10), 1229–1241. doi: 10.1261/rna.071332.119\n\n\n## License\n\nAnd of course:\n\nGPL-3: https://www.gnu.org/licenses/gpl-3.0.en.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadnaniazi%2Ftailfindr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadnaniazi%2Ftailfindr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadnaniazi%2Ftailfindr/lists"}