Skip to content

Commit 4456a96

Browse files
author
Daniel Danis
committed
Init the read the docs
1 parent f854ec6 commit 4456a96

9 files changed

+377
-0
lines changed

.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -181,3 +181,5 @@ buildNumber.properties
181181
# https://github.com/takari/maven-wrapper#usage-without-binary-jar
182182
.mvn/wrapper/maven-wrapper.jar
183183

184+
# Docs
185+
_build/

docs/Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SPHINXPROJ = svart
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

+159
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# Configuration file for the Sphinx documentation builder.
4+
#
5+
# This file does only contain a selection of the most common options. For a
6+
# full list see the documentation:
7+
# http://www.sphinx-doc.org/en/master/config
8+
9+
# -- Path setup --------------------------------------------------------------
10+
11+
# If extensions (or modules to document with autodoc) are in another directory,
12+
# add these directories to sys.path here. If the directory is relative to the
13+
# documentation root, use os.path.abspath to make it absolute, like shown here.
14+
#
15+
# import os
16+
# import sys
17+
# sys.path.insert(0, os.path.abspath('.'))
18+
19+
20+
# -- Project information -----------------------------------------------------
21+
22+
project = 'svart'
23+
copyright = '2020, Jules Jacobsen, Daniel Danis'
24+
author = 'Jules Jacobsen, Daniel Danis'
25+
26+
# The short X.Y version
27+
version = '1.0'
28+
# The full version, including alpha/beta/rc tags
29+
release = 'v1.0.0-SNAPSHOT'
30+
31+
32+
# -- General configuration ---------------------------------------------------
33+
34+
# If your documentation needs a minimal Sphinx version, state it here.
35+
#
36+
# needs_sphinx = '1.0'
37+
38+
# Add any Sphinx extension module names here, as strings. They can be
39+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
40+
# ones.
41+
extensions = [
42+
'sphinx.ext.mathjax',
43+
]
44+
45+
# Add any paths that contain templates here, relative to this directory.
46+
templates_path = ['_templates']
47+
48+
# The suffix(es) of source filenames.
49+
# You can specify multiple suffix as a list of string:
50+
#
51+
# source_suffix = ['.rst', '.md']
52+
source_suffix = '.rst'
53+
54+
# The master toctree document.
55+
master_doc = 'index'
56+
57+
# The language for content autogenerated by Sphinx. Refer to documentation
58+
# for a list of supported languages.
59+
#
60+
# This is also used if you do content translation via gettext catalogs.
61+
# Usually you set "language" from the command line for these cases.
62+
language = None
63+
64+
# List of patterns, relative to source directory, that match files and
65+
# directories to ignore when looking for source files.
66+
# This pattern also affects html_static_path and html_extra_path .
67+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
68+
69+
# The name of the Pygments (syntax highlighting) style to use.
70+
pygments_style = 'sphinx'
71+
72+
73+
# -- Options for HTML output -------------------------------------------------
74+
75+
# The theme to use for HTML and HTML Help pages. See the documentation for
76+
# a list of builtin themes.
77+
#
78+
html_theme = 'alabaster'
79+
80+
# Theme options are theme-specific and customize the look and feel of a theme
81+
# further. For a list of options available for each theme, see the
82+
# documentation.
83+
#
84+
# html_theme_options = {}
85+
86+
# Add any paths that contain custom static files (such as style sheets) here,
87+
# relative to this directory. They are copied after the builtin static files,
88+
# so a file named "default.css" will overwrite the builtin "default.css".
89+
html_static_path = ['_static']
90+
91+
# Custom sidebar templates, must be a dictionary that maps document names
92+
# to template names.
93+
#
94+
# The default sidebars (for documents that don't match any pattern) are
95+
# defined by theme itself. Builtin themes are using these templates by
96+
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
97+
# 'searchbox.html']``.
98+
#
99+
# html_sidebars = {}
100+
101+
102+
# -- Options for HTMLHelp output ---------------------------------------------
103+
104+
# Output file base name for HTML help builder.
105+
htmlhelp_basename = 'svartdoc'
106+
107+
108+
# -- Options for LaTeX output ------------------------------------------------
109+
110+
latex_elements = {
111+
# The paper size ('letterpaper' or 'a4paper').
112+
#
113+
# 'papersize': 'letterpaper',
114+
115+
# The font size ('10pt', '11pt' or '12pt').
116+
#
117+
# 'pointsize': '10pt',
118+
119+
# Additional stuff for the LaTeX preamble.
120+
#
121+
# 'preamble': '',
122+
123+
# Latex figure (float) alignment
124+
#
125+
# 'figure_align': 'htbp',
126+
}
127+
128+
# Grouping the document tree into LaTeX files. List of tuples
129+
# (source start file, target name, title,
130+
# author, documentclass [howto, manual, or own class]).
131+
latex_documents = [
132+
(master_doc, 'Svart.tex', 'Svart Documentation',
133+
'Jules Jacobsen, Daniel Danis', 'manual'),
134+
]
135+
136+
137+
# -- Options for manual page output ------------------------------------------
138+
139+
# One entry per manual page. List of tuples
140+
# (source start file, name, description, authors, manual section).
141+
man_pages = [
142+
(master_doc, 'Svart', 'Svart Documentation',
143+
[author], 1)
144+
]
145+
146+
147+
# -- Options for Texinfo output ----------------------------------------------
148+
149+
# Grouping the document tree into Texinfo files. List of tuples
150+
# (source start file, target name, title, author,
151+
# dir menu entry, description, category)
152+
texinfo_documents = [
153+
(master_doc, 'Svart', 'Svart Documentation',
154+
author, 'svart', 'A library to ease representation of variants and performing genomic manipulations.',
155+
'Bioinformatics'),
156+
]
157+
158+
159+
# -- Extension configuration -------------------------------------------------

docs/explanations.rst

+96
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
.. _rstexplanations:
2+
3+
===============
4+
Building blocks
5+
===============
6+
7+
This document describes concepts and building blocks of the Svart library. We start by explaining how the library models
8+
the genomic assembly and contigs. Then we explain concepts that are necessary for defining a (genomic) region, including
9+
coordinate system and strand. Finally, we describe how the library models genomic variation.
10+
11+
Genomic Assembly
12+
~~~~~~~~~~~~~~~~
13+
14+
Svart adopts NCBI's representation of genomic assembly, where the assembly is a collection of
15+
contigs with some metadata.
16+
17+
There are three ways how to create a ``GenomicAssembly``:
18+
19+
Built in Genomic Assemblies
20+
###########################
21+
22+
Svart ships with several built-in genomic assemblies for *Homo sapiens* and *Mus musculus* organisms:
23+
24+
.. TODO - Make this a table?
25+
26+
* ``GRCh37.p13``
27+
* ``GRCh38.p13``
28+
* ``GRCm39``
29+
* ``GRCm38.p6``
30+
31+
Let's get our hands on the ``GRCh38.p13`` assembly::
32+
33+
GenomicAssembly grch38p13 = GenomicAssemblies.GRCh38p13();
34+
35+
System.out.println(grch38p13.name() + ':' + grch38p13.organismName());
36+
// prints `GRCh38.p13:Homo sapiens (human)`
37+
38+
NCBI assembly report file
39+
#########################
40+
41+
Svart provides a parser that reads NCBI's genomic assembly report file and returns the corresponding ``GenomicAssembly``.
42+
43+
Let's read for `GRCm38.p6 assembly report`_ from NCBI's FTP site using the corresponding RefSeq assembly accession ``GCF_000001635.26``::
44+
45+
GenomicAssembly grcm38p6 = GenomicAssemblies.downloadAssembly("GCF_000001635.26");
46+
47+
System.out.println(grcm38p6.name() + ':' + grcm38p6.organismName());
48+
// prints `GRCm38.p6:Mus musculus (house mouse)`
49+
50+
From scratch
51+
############
52+
53+
Let's create an example genomic assembly with metadata corresponding to ``GRCh38.p13``. The assembly contains the first
54+
2 contigs of the assembly::
55+
56+
List<Contig> contigs = List.of(
57+
Contig.of(1, "1", SequenceRole.ASSEMBLED_MOLECULE, "1", AssignedMoleculeType.CHROMOSOME, 248_956_422, "CM000663.2", "NC_000001.11", "chr1"),
58+
Contig.of(2, "2", SequenceRole.ASSEMBLED_MOLECULE, "2", AssignedMoleculeType.CHROMOSOME, 248_956_422, "CM000664.2", "NC_000002.12", "chr2"));
59+
GenomicAssembly assembly = GenomicAssembly.of("GRCh38.p13", "Homo sapiens (human)", "9606",
60+
"Genome Reference Consortium", "2019-02-28",
61+
"GCA_000001405.28", "GCF_000001405.39",
62+
contigs);
63+
64+
System.out.println(assembly.name() + ':' + assembly.organismName());
65+
// prints `GRCh38.p13:Homo sapiens (human)`
66+
67+
68+
Contig
69+
~~~~~~
70+
71+
In Svart, contig is a linear
72+
73+
Coordinate Systems
74+
~~~~~~~~~~~~~~~~~~
75+
76+
.. TODO - explain the contemporary coordinate systems used in genomics,
77+
- how this is different from another domains (e.g. joda-time) where only a single coordinate system is allowed,
78+
- difference between coordinates and positions,
79+
- why we define all 4 possible coordinate systems
80+
81+
Strand
82+
~~~~~~
83+
84+
.. TODO - explain why we use 2 strands and not the strands of GFF format
85+
- methods of `Stranded<T>` that allow conversions of coordinates between strands
86+
- why strand of breakend variants cannot be changed
87+
88+
Genomic Region
89+
~~~~~~~~~~~~~~
90+
91+
.. TODO -
92+
93+
Variant
94+
~~~~~~~
95+
96+
.. _GRCm38.p6 assembly report: ftp://ftp.ncbi.nlm.nih.gov/genomes/all/GCA/000/001/405/GCA_000001405.14_GRCh37.p13/GCA_000001405.14_GRCh37.p13_assembly_report.txt

docs/getstarted.rst

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.. _rstgetstarted:
2+
3+
===========
4+
Get started
5+
===========
6+
7+
Let's show a couple of use cases here - reading BED files, VCF files, etc..
8+
9+

docs/index.rst

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
=====
2+
Svart
3+
=====
4+
5+
**A library to ease representation of variants and performing genomic manipulations.**
6+
7+
Svart is a library for representing genomic variants and regions. It attempts to solve several common issues:
8+
9+
* Coordinate system off-by-one errors
10+
* Representation of VCF small, structural and breakend variants with a consistent API
11+
* Different variant trimming strategies
12+
13+
The library provides a consistent API for creating, manipulating and comparing variation of different types by providing default implementations and extensible base classes and interfaces along with immutable default implementations which developers can utilise to gain maximum utility from a minimum amount of code without having to address issues in bioinformatics which are a common source of duplicated code and frequently errors.
14+
15+
The code is completely free of external dependencies.
16+
17+
18+
.. toctree::
19+
:maxdepth: 2
20+
:caption: Contents:
21+
22+
getstarted
23+
explanations
24+
usecases
25+
motivation

docs/make.bat

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
set SPHINXPROJ=svart
13+
14+
if "%1" == "" goto help
15+
16+
%SPHINXBUILD% >NUL 2>NUL
17+
if errorlevel 9009 (
18+
echo.
19+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
20+
echo.installed, then set the SPHINXBUILD environment variable to point
21+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
22+
echo.may add the Sphinx directory to PATH.
23+
echo.
24+
echo.If you don't have Sphinx installed, grab it from
25+
echo.http://sphinx-doc.org/
26+
exit /b 1
27+
)
28+
29+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
30+
goto end
31+
32+
:help
33+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
34+
35+
:end
36+
popd

docs/motivation.rst

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. _rstmotivation:
2+
3+
==========
4+
Motivation
5+
==========
6+
7+
This is intended to be used as a standard library for various Monarch and Monarch-related projects involving genomic
8+
variation such as Jannovar, Exomiser, and Squirls.
9+
10+
These projects are inter-dependent to some extent and all require some level of ability to represent and manipulate
11+
genomic variation.
12+
13+
Given the inter-dependency there is substantial copying/re-implementation in the code-bases of these projects
14+
of various core concepts surrounding genomic variation. This library aims to provide a common set of interfaces
15+
and implementations which can be used to fulfill their collective use-cases and so reduce code duplication, bugs,
16+
and GC pressure due to object conversion between common types.
17+
18+
Success Metrics
19+
~~~~~~~~~~~~~~~
20+
21+
* *Jannovar* will be able to function with only minor changes to replace a few core components API with the Svart elements.
22+
For example the Jannovar `VariantDescription` should be replaceable with `Variant`
23+
* *Exomiser* will be able to function by implementing the `Variant` interface or extending the `BaseVariant` class

docs/usecases.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. _rstusecases:
2+
3+
=========
4+
Use cases
5+
=========
6+
7+
.. TODO - we show recipes for using Svart, including content of `UseCaseTests`

0 commit comments

Comments
 (0)