
<!-- README.md is generated from README.Rmd. Please edit that file -->

# seqmagick: Sequence Manipulation Utilities

<!-- badges: start -->

[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/seqmagick)](https://cran.r-project.org/package=seqmagick)
[![CRAN_Download_Badge](https://cranlogs.r-pkg.org/badges/grand-total/seqmagick?color=green)](https://cran.r-project.org/package=seqmagick)
<!-- badges: end -->

Tools for reading and writing biological sequences in multiple formats,
including ‘FASTA’, ‘PHYLIP’, ‘CLUSTAL’, ‘STOCKHOLM’, ‘MEGA’ and
‘GenBank’. Supports interleaved and sequential layouts where applicable,
and reads or writes gzip, bzip2 and xz compressed files transparently.
Converts between formats, renames sequences via a two-column mapping,
summarizes sequence counts, lengths, GC content and ambiguous
characters, and manipulates sequence sets (e.g., filtering by patterns
and computing consensus sequences from alignments). Also includes
functions to download nucleotide records from NCBI by accession.

## :writing_hand: Authors

YuLab@SMU <https://yulab-smu.top>

## :page_facing_up: Supported file formats

| Format                  | Read               | Write              |
|:------------------------|:-------------------|:-------------------|
| FASTA (.fas/.fa/.fasta) | :heavy_check_mark: | :heavy_check_mark: |
| PHYLIP (.phy)           | :heavy_check_mark: | :heavy_check_mark: |
| CLUSTAL (.clw)          | :heavy_check_mark: | \-                 |
| STOCKHOLM (.sth)        | :heavy_check_mark: | \-                 |
| MEGA (.meg)             | :heavy_check_mark: | \-                 |
| GenBank (.gb)           | :heavy_check_mark: | \-                 |
| NCBI (online)           | :heavy_check_mark: | \-                 |

Both sequential and interleaved layouts are supported for FASTA and
PHYLIP. Compressed files (`gzip`, `bzip2`, `xz`) are handled
transparently.

## :hammer: Installation

Install from CRAN:

``` r
install.packages("seqmagick")
```

Or grab the development version from GitHub:

``` r
if (!requireNamespace("remotes", quietly=TRUE))
    install.packages("remotes")
remotes::install_github("YuLab-SMU/seqmagick")
```

## :bulb: Quick Examples

``` r
library(seqmagick)

fas <- system.file("extdata/HA.fas", package = "seqmagick")

## reading/writing FASTA files
x <- fa_read(fas)
fa_write(x[1:5], "sub.fa.gz")     # gzip/bzip2/xz supported

## a quick summary (counts, lengths, GC content)
fa_summary(fas)

## sequence manipulation
bs_filter(x, 'ATGAAAGTAAAA', by='sequence')   # keep matching sequences

## renaming sequences via two-column mapping
map <- data.frame(old = names(x)[1:2],
                  new = c("HA_HK", "HA_BR"))
y <- bs_rename(x, map)

## format conversion (requires aligned sequences)
fas2phy("aln.fas", "aln.phy")
phy2fas("aln.phy", "aln.fas")

## download nucleotide records from NCBI
seqs <- ncbi_fa_read(acc = c("AB115403", "CY084969"))
```

For more details, please see the [online
vignette](https://CRAN.R-project.org/package=seqmagick).

If you use `seqmagick`, please cite:

> Yu G (2026). *seqmagick: Sequence Manipulation Utilities*. R package
> version 0.1.9, <https://github.com/YuLab-SMU/seqmagick>.

<br>
