From 1bcd7c344cfc5e031e11075e4ea81702d3c4fd56 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20O=27Mara?= Date: Fri, 28 Feb 2020 14:29:53 +1100 Subject: [PATCH] Documentation - API autodocs. - Inline links for documenter. - Logo. - Badges. --- README.md | 77 ++++++++++++++++++++++++++++++++++++++- docs/Project.toml | 6 +++ docs/make.jl | 21 +++++++++++ docs/src/assets/logo.svg | 26 +++++++++++++ docs/src/index.md | 77 +++++++++++++++++++++++++++++++++++++++ docs/src/man/api.md | 38 +++++++++++++++++++ docs/src/man/hts-files.md | 43 +++++++++------------- 7 files changed, 260 insertions(+), 28 deletions(-) create mode 100644 docs/Project.toml create mode 100644 docs/make.jl create mode 100644 docs/src/assets/logo.svg create mode 100644 docs/src/index.md create mode 100644 docs/src/man/api.md diff --git a/README.md b/README.md index 645914e..45061cc 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,76 @@ -# XAM.jl +# XAM.jl -In development: minimal working separation of SAM and BAM from BioAlignments. +[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) +[![Latest Release](https://img.shields.io/github/release/BioJulia/XAM.jl.svg)](https://github.com/BioJulia/XAM.jl/releases/latest) +[![MIT license](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/BioJulia/XAM.jl/blob/master/LICENSE) +[![Stable documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://biojulia.github.io/XAM.jl/stable) +[![Latest documentation](https://img.shields.io/badge/docs-dev-blue.svg)](https://biojulia.github.io/XAM.jl/dev/) +[![Join the chat at https://gitter.im/BioJulia/XAM.jl](https://badges.gitter.im/BioJulia/XAM.jl.svg)](https://gitter.im/BioJulia/XAM.jl) + +> This project follows the [semver](http://semver.org) pro forma and uses the [git-flow branching model](https://nvie.com/posts/a-successful-git-branching-model/ "original +blog post"). + +## Description +XAM provides I/O and utilities for manipulating SAM and BAM formatted alignment map files. + +## Installation +The latest version of XAM is made available to install through BioJulia's package registry. +By default, Julia's package manager only includes the "General" package registry. + +To add the BioJulia registry from the [Julia REPL](https://docs.julialang.org/en/v1/manual/getting-started/), press `]` to enter [pkg mode](https://docs.julialang.org/en/v1/stdlib/Pkg/), then enter the following command: +```julia +registry add https://github.com/BioJulia/BioJuliaRegistry.git +``` + +Once the registry is added to your configuration, you can install XAM while in [pkg mode](https://docs.julialang.org/en/v1/stdlib/Pkg/) with the following: +```julia +add XAM +``` + +If you are interested in the cutting edge of the development, please check out the [develop branch](https://github.com/BioJulia/XAM.jl/tree/develop) to try new features before release. + +## Testing +XAM is tested against Julia `1.X` on Linux, OS X, and Windows. + +**Latest build status:** + +[![Unit tests](https://github.com/BioJulia/XAM.jl/workflows/Unit%20tests/badge.svg?branch=master)](https://github.com/BioJulia/XAM.jl/actions?query=workflow%3A%22Unit+tests%22+branch%3Amaster) +[![Documentation](https://github.com/BioJulia/XAM.jl/workflows/Documentation/badge.svg?branch=master)](https://github.com/BioJulia/XAM.jl/actions?query=workflow%3ADocumentation+branch%3Amaster) +[![codecov](https://codecov.io/gh/BioJulia/XAM.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/BioJulia/XAM.jl) + +## Contributing +We appreciate [contributions](https://github.com/BioJulia/XAM.jl/graphs/contributors) from users including reporting bugs, fixing issues, improving performance and adding new features. + +Take a look at the [contributing files](https://github.com/BioJulia/Contributing) detailed contributor and maintainer guidelines, and code of conduct. + +### Financial contributions +We also welcome financial contributions in full transparency on our [open collective](https://opencollective.com/biojulia). +Anyone can file an expense. +If the expense makes sense for the development the core contributors and the person who filed the expense will be reimbursed. + + +## Backers & Sponsors +Thank you to all our backers and sponsors! + +Love our work and community? [Become a backer](https://opencollective.com/biojulia#backer). + +[![backers](https://opencollective.com/biojulia/backers.svg?width=890)](https://opencollective.com/biojulia#backers) + +Does your company use BioJulia? +Help keep BioJulia feature rich and healthy by [sponsoring the project](https://opencollective.com/biojulia#sponsor). +Your logo will show up here with a link to your website. + +[![](https://opencollective.com/biojulia/sponsor/0/avatar.svg)](https://opencollective.com/biojulia/sponsor/0/website) +[![](https://opencollective.com/biojulia/sponsor/1/avatar.svg)](https://opencollective.com/biojulia/sponsor/1/website) +[![](https://opencollective.com/biojulia/sponsor/2/avatar.svg)](https://opencollective.com/biojulia/sponsor/2/website) +[![](https://opencollective.com/biojulia/sponsor/3/avatar.svg)](https://opencollective.com/biojulia/sponsor/3/website) +[![](https://opencollective.com/biojulia/sponsor/4/avatar.svg)](https://opencollective.com/biojulia/sponsor/4/website) +[![](https://opencollective.com/biojulia/sponsor/5/avatar.svg)](https://opencollective.com/biojulia/sponsor/5/website) +[![](https://opencollective.com/biojulia/sponsor/6/avatar.svg)](https://opencollective.com/biojulia/sponsor/6/website) +[![](https://opencollective.com/biojulia/sponsor/7/avatar.svg)](https://opencollective.com/biojulia/sponsor/7/website) +[![](https://opencollective.com/biojulia/sponsor/8/avatar.svg)](https://opencollective.com/biojulia/sponsor/8/website) +[![](https://opencollective.com/biojulia/sponsor/9/avatar.svg)](https://opencollective.com/biojulia/sponsor/9/website) + + +## Questions? +If you have a question about contributing or using BioJulia software, come on over and chat to us on [Gitter](https://gitter.im/BioJulia/General), or you can try the [Bio category of the Julia discourse site](https://discourse.julialang.org/c/domain/bio). diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 0000000..3506869 --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,6 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f" + +[compat] +Documenter = "0.24" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 0000000..fcbd601 --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,21 @@ +using Pkg +using Documenter, XAM + +makedocs( + format = Documenter.HTML( + edit_link = "develop" + ), + modules = [XAM, XAM.SAM, XAM.BAM], + sitename = "XAM.jl", + pages = [ + "Home" => "index.md", + "SAM and BAM" => "man/hts-files.md", + "API Reference" => "man/api.md" + ], + authors = replace(join(Pkg.TOML.parsefile("Project.toml")["authors"], ", "), r" <.*?>" => "" ) * ", The BioJulia Organisation, and other contributors." +) +deploydocs( + repo = "github.com/BioJulia/XAM.jl.git", + devbranch = "develop", + push_preview = true +) diff --git a/docs/src/assets/logo.svg b/docs/src/assets/logo.svg new file mode 100644 index 0000000..1b2ea24 --- /dev/null +++ b/docs/src/assets/logo.svg @@ -0,0 +1,26 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 0000000..97d0001 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,77 @@ +# XAM.jl + +[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) +[![Latest Release](https://img.shields.io/github/release/BioJulia/XAM.jl.svg)](https://github.com/BioJulia/XAM.jl/releases/latest) +[![MIT license](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/BioJulia/XAM.jl/blob/master/LICENSE) +[![Stable documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://biojulia.github.io/XAM.jl/stable) +[![Latest documentation](https://img.shields.io/badge/docs-dev-blue.svg)](https://biojulia.github.io/XAM.jl/dev/) +[![Join the chat at https://gitter.im/BioJulia/XAM.jl](https://badges.gitter.im/BioJulia/XAM.jl.svg)](https://gitter.im/BioJulia/XAM.jl) + +> This project follows the [semver](http://semver.org) pro forma and uses the [git-flow branching model](https://nvie.com/posts/a-successful-git-branching-model/). + +## Description + +XAM provides I/O and utilities for manipulating SAM and BAM formatted alignment map files. + + +## Installation +The latest version of XAM is made available to install through BioJulia's package registry. +By default, Julia's package manager only includes the "General" package registry. + +To add the BioJulia registry from the [Julia REPL](https://docs.julialang.org/en/v1/manual/getting-started/), press `]` to enter [pkg mode](https://docs.julialang.org/en/v1/stdlib/Pkg/), then enter the following command: +```julia +registry add https://github.com/BioJulia/BioJuliaRegistry.git +``` + +Once the registry is added to your configuration, you can install XAM while in [pkg mode](https://docs.julialang.org/en/v1/stdlib/Pkg/) with the following: +```julia +add XAM +``` + +If you are interested in the cutting edge of the development, please check out the [develop branch](https://github.com/BioJulia/XAM.jl/tree/develop) to try new features before release. + +## Testing +XAM is tested against Julia `1.X` on Linux, OS X, and Windows. + +**Latest build status:** + +[![Unit tests](https://github.com/BioJulia/XAM.jl/workflows/Unit%20tests/badge.svg?branch=master)](https://github.com/BioJulia/XAM.jl/actions?query=workflow%3A%22Unit+tests%22+branch%3Amaster) +[![Documentation](https://github.com/BioJulia/XAM.jl/workflows/Documentation/badge.svg?branch=master)](https://github.com/BioJulia/XAM.jl/actions?query=workflow%3ADocumentation+branch%3Amaster) +[![codecov](https://codecov.io/gh/BioJulia/XAM.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/BioJulia/XAM.jl) + +## Contributing +We appreciate [contributions](https://github.com/BioJulia/XAM.jl/graphs/contributors) from users including reporting bugs, fixing issues, improving performance and adding new features. + +Take a look at the [contributing files](https://github.com/BioJulia/Contributing) detailed contributor and maintainer guidelines, and code of conduct. + +### Financial contributions +We also welcome financial contributions in full transparency on our [open collective](https://opencollective.com/biojulia). +Anyone can file an expense. +If the expense makes sense for the development the core contributors and the person who filed the expense will be reimbursed. + + +## Backers & Sponsors +Thank you to all our backers and sponsors! + +Love our work and community? [Become a backer](https://opencollective.com/biojulia#backer). + +[![backers](https://opencollective.com/biojulia/backers.svg?width=890)](https://opencollective.com/biojulia#backers) + +Does your company use BioJulia? +Help keep BioJulia feature rich and healthy by [sponsoring the project](https://opencollective.com/biojulia#sponsor). +Your logo will show up here with a link to your website. + +[![](https://opencollective.com/biojulia/sponsor/0/avatar.svg)](https://opencollective.com/biojulia/sponsor/0/website) +[![](https://opencollective.com/biojulia/sponsor/1/avatar.svg)](https://opencollective.com/biojulia/sponsor/1/website) +[![](https://opencollective.com/biojulia/sponsor/2/avatar.svg)](https://opencollective.com/biojulia/sponsor/2/website) +[![](https://opencollective.com/biojulia/sponsor/3/avatar.svg)](https://opencollective.com/biojulia/sponsor/3/website) +[![](https://opencollective.com/biojulia/sponsor/4/avatar.svg)](https://opencollective.com/biojulia/sponsor/4/website) +[![](https://opencollective.com/biojulia/sponsor/5/avatar.svg)](https://opencollective.com/biojulia/sponsor/5/website) +[![](https://opencollective.com/biojulia/sponsor/6/avatar.svg)](https://opencollective.com/biojulia/sponsor/6/website) +[![](https://opencollective.com/biojulia/sponsor/7/avatar.svg)](https://opencollective.com/biojulia/sponsor/7/website) +[![](https://opencollective.com/biojulia/sponsor/8/avatar.svg)](https://opencollective.com/biojulia/sponsor/8/website) +[![](https://opencollective.com/biojulia/sponsor/9/avatar.svg)](https://opencollective.com/biojulia/sponsor/9/website) + + +## Questions? +If you have a question about contributing or using BioJulia software, come on over and chat to us on [Gitter](https://gitter.im/BioJulia/General), or you can try the [Bio category of the Julia discourse site](https://discourse.julialang.org/c/domain/bio). diff --git a/docs/src/man/api.md b/docs/src/man/api.md new file mode 100644 index 0000000..d30bca2 --- /dev/null +++ b/docs/src/man/api.md @@ -0,0 +1,38 @@ +```@meta +CurrentModule = XAM +DocTestSetup = quote + using XAM +end +``` + +# API Reference + +## SAM API + +### Public + +```@autodocs +Modules = [XAM.SAM] +private = false +``` + +### Internal +```@autodocs +Modules = [XAM.SAM] +public = false +``` + +## BAM API + +### Public + +```@autodocs +Modules = [XAM.BAM] +private = false +``` + +### Internal +```@autodocs +Modules = [XAM.BAM] +public = false +``` diff --git a/docs/src/man/hts-files.md b/docs/src/man/hts-files.md index 81783a9..de87b32 100644 --- a/docs/src/man/hts-files.md +++ b/docs/src/man/hts-files.md @@ -1,15 +1,10 @@ # SAM and BAM - ## Introduction -High-throughput sequencing (HTS) technologies generate a large amount of data in the form of a large number of nucleotide sequencing reads. -One of the most common tasks in bioinformatics is to align these reads against known reference genomes, chromosomes, or contigs. -BioAlignments provides several data formats commonly used for this kind of task. +The `XAM` package offers high-performance tools for SAM and BAM file formats, which are the most popular file formats. -BioAlignments offers high-performance tools for SAM and BAM file formats, which are the most popular file formats. - -If you have questions about the SAM and BAM formats or any of the terminology used when discussing these formats, see the published [specification][samtools-spec], which is maintained by the [samtools group][samtools]. +If you have questions about the SAM and BAM formats or any of the terminology used when discussing these formats, see the published [specification](https://samtools.github.io/hts-specs/SAMv1.pdf), which is maintained by the [samtools group](https://samtools.github.io/). A very very simple SAM file looks like the following: @@ -28,7 +23,7 @@ Where the first two lines are part of the "header", and the following lines are Each record describes how a read aligns to some reference sequence. Sometimes one record describes one read, but there are other cases like chimeric reads and split alignments, where multiple records apply to one read. In the example above, `r003` is a chimeric read, and `r004` is a split alignment, and `r001` are mate pair reads. -Again, we refer you to the official [specification][samtools-spec] for more details. +Again, we refer you to the official [specification](https://samtools.github.io/hts-specs/SAMv1.pdf) for more details. A BAM file stores this same information but in a binary and compressible format that does not make for pretty printing here! @@ -37,7 +32,7 @@ A BAM file stores this same information but in a binary and compressible format A typical script iterating over all records in a file looks like below: ```julia -using BioAlignments +using XAM # Open a BAM file. reader = open(BAM.Reader, "data.bam") @@ -72,7 +67,7 @@ end Both `SAM.Reader` and `BAM.Reader` implement the `header` function, which returns a `SAM.Header` object. To extract certain information out of the headers, you can use the `find` method on the header to extract information according to SAM/BAM tag. -Again we refer you to the [specification][samtools-spec] for full details of all the different tags that can occur in headers, and what they mean. +Again we refer you to the [specification](https://samtools.github.io/hts-specs/SAMv1.pdf) for full details of all the different tags that can occur in headers, and what they mean. Below is an example of extracting all the info about the reference sequences from the BAM header. In SAM/BAM, any description of a reference sequence is stored in the header, under a tag denoted `SQ` (think `reference SeQuence`!). @@ -110,7 +105,8 @@ In the above we can see there were 7 sequences in the reference: 5 chromosomes, ## SAM and BAM Records -BioAlignments supports the following accessors for `SAM.Record` types. +### SAM.Record +The `XAM` package supports the following accessors for `SAM.Record` types. ```@docs XAM.SAM.flag @@ -134,7 +130,8 @@ XAM.SAM.quality XAM.SAM.auxdata ``` -BioAlignments supports the following accessors for `BAM.Record` types. +### BAM.Record +The `XAM` package supports the following accessors for `BAM.Record` types. ```@docs XAM.BAM.flag @@ -178,7 +175,7 @@ Tagged auxiliary data follows a format of `TAG:TYPE:VALUE`. | 'H' | Byte array in Hex format | | 'B' | Integer of numeric array | -For more information about these tags and their types we refer you to the [SAM/BAM specification][samtools-spec] and the additional [optional fields specification][samtags] document. +For more information about these tags and their types we refer you to the [SAM/BAM specification](https://samtools.github.io/hts-specs/SAMv1.pdf) and the additional [optional fields specification](https://samtools.github.io/hts-specs/SAMtags.pdf) document. There are some tags that are reserved, predefined standard tags, for specific uses. @@ -200,8 +197,8 @@ end ## Getting records in a range -BioAlignments supports the BAI index to fetch records in a specific range from a BAM file. -[Samtools][samtools] provides `index` subcommand to create an index file (.bai) from a sorted BAM file. +The `XAM` package supports the BAI index to fetch records in a specific range from a BAM file. +[Samtools](https://samtools.github.io/) provides `index` subcommand to create an index file (.bai) from a sorted BAM file. ```console $ samtools index -b SRR1238088.sort.bam @@ -209,7 +206,7 @@ $ ls SRR1238088.sort.bam* SRR1238088.sort.bam SRR1238088.sort.bam.bai ``` -`eachoverlap(reader, chrom, range)` returns an iterator of BAM records overlapping the query interval: +The method `eachoverlap(reader, chrom, range)` returns an iterator of BAM records overlapping the query interval: ```julia reader = open(BAM.Reader, "SRR1238088.sort.bam", index="SRR1238088.sort.bam.bai") @@ -222,14 +219,14 @@ close(reader) ## Getting records overlapping genomic features -`eachoverlap` also accepts the `Interval` type defined in [GenomicFeatures.jl][genomicfeatures]. +The `eachoverlap` method also accepts the `Interval` type defined in [GenomicFeatures.jl](https://github.com/BioJulia/GenomicFeatures.jl). This allows you to do things like first read in the genomic features from a GFF3 file, and then for each feature, iterate over all the BAM records that overlap with that feature. ```julia -# Load GFF3 module. using GenomicFeatures -using BioAlignments +using GFF3 +using XAM # Load genomic features from a GFF3 file. features = open(collect, GFF3.Reader, "TAIR10_GFF3_genes.gff") @@ -289,7 +286,7 @@ SAM.Writer(IOStream()) ``` -To make a BAM Writer is slightly different, as you need to use a specific stream type from the [BGZFStreams][bgzfstreams] package: +To make a BAM Writer is slightly different, as you need to use a specific stream type from the (https://github.com/BioJulia/BGZFStreams.jl)[https://github.com/BioJulia/BGZFStreams.jl] package: ```julia julia> using BGZFStreams @@ -305,9 +302,3 @@ Once you have a BAM or SAM writer, you can use the `write` method to write `BAM. julia> write(bamw, rec) # Here rec is a `BAM.Record` 330780 ``` - -[samtools]: https://samtools.github.io/ -[samtools-spec]: https://samtools.github.io/hts-specs/SAMv1.pdf -[samtags]: https://samtools.github.io/hts-specs/SAMtags.pdf -[bgzfstreams]: https://github.com/BioJulia/BGZFStreams.jl -[genomicfeatures]: https://github.com/BioJulia/GenomicFeatures.jl