Added R package documentation to main docs site (#125)

docs/index.rst

@@ -21,3 +21,4 @@ include
     miairr/overview
     formats/overview
     Python Library <lang/python/overview>
+    R Library <lang/R/overview>

docs/lang/R/about.rst

@@ -0,0 +1,20 @@
+About
+=====
+
+AIRR Standards Reference Library
+--------------------------------
+
+R package for importing AIRR standard formatted data.
+
+Dependencies
+------------
+
+| **Imports:** methods, readr, stats, stringi, yaml
+| **Suggests:** knitr, rmarkdown, testthat
+
+Authors
+-------
+
+| `Jason Vander Heiden <mailto:jason.vanderheiden@yale.edu>`__ (aut,
+  cre)
+| `Susanna Marquez <mailto:susanna.marquez@yale.edu>`__ (aut)

docs/lang/R/news.rst

@@ -0,0 +1,7 @@
+Release Notes
+=============
+
+Version 1.1.0: April 20, 2018
+-----------------------------
+
+Initial release.

docs/lang/R/overview.rst

@@ -0,0 +1,37 @@
+.. _ROverview:
+
+R Library
+================================================================================
+
+An R library providing AIRR schema definitions and read, write, and validation
+functions for AIRR standard formatted data files.
+
+**Download & Installation**
+
+To build from the `source code <https://github.com/airr-community/airr-standards>`_,
+first install the build dependencies::
+
+    install.packages(c("devtools", "roxygen2"))
+
+To install the latest development code via devtools::
+
+    library(devtools)
+    install_github("airr-community/airr-standards/lang/R@master")
+
+Note, using ``install_github`` will not build the documentation. To generate the
+documentation, clone the repository and build as normal. Then run the following
+R commands from the package root ``lang/R``::
+
+    library(devtools)
+    install_deps(dependencies=T)
+    document()
+    install()
+
+.. toctree::
+    :maxdepth: 3
+    :hidden:
+
+    About <about>
+    vignettes/Usage-Vignette
+    Reference Manul <topics>
+    Release Notes <news>

docs/lang/R/topics.rst

@@ -0,0 +1,17 @@
+.. _RTopics:
+
+Reference Topics
+===========================
+
+.. .. include:: topics/airr.rst
+
+.. toctree::
+    :caption: Reference Topics
+    :maxdepth: 1
+
+    topics/read_airr
+    topics/write_airr
+    topics/load_schema
+    topics/Schema-class
+    topics/AlignmentSchema
+    topics/RearrangementSchema

docs/lang/R/topics/AlignmentSchema.rst

@@ -0,0 +1,21 @@
+AlignmentSchema
+---------------
+
+**Alignment Schema**
+
+Description
+~~~~~~~~~~~
+
+AIRR Alignment object schema
+
+Usage
+~~~~~
+
+::
+
+    AlignmentSchema
+
+Format
+~~~~~~
+
+A `Schema <Schema-class.md>`__ object.

docs/lang/R/topics/RearrangementSchema.rst

@@ -0,0 +1,27 @@
+RearrangementSchema
+-------------------
+
+**Rearrangment Schema**
+
+Description
+~~~~~~~~~~~
+
+AIRR Rearrangement object schema
+
+Usage
+~~~~~
+
+::
+
+    RearrangementSchema
+
+Format
+~~~~~~
+
+A `Schema <Schema-class.md>`__ object.
+
+See also
+~~~~~~~~
+
+See `read_airr <read_airr.md>`__ and `write_airr <write_airr.md>`__ for
+reading and writing.

docs/lang/R/topics/Schema-class.rst

@@ -0,0 +1,50 @@
+Schema-class
+------------
+
+**S4 class defining an AIRR standard schema**
+
+Description
+~~~~~~~~~~~
+
+``Schema`` defines a common data structure for AIRR standards.
+
+Usage
+~~~~~
+
+::
+
+    "names"(x)
+
+::
+
+    "["(x, i)
+
+::
+
+    "$"(x, name)
+
+Arguments
+~~~~~~~~~
+
+x
+    ``Schema`` object.
+i
+    field name.
+name
+    field name.
+
+Slots
+~~~~~
+
+``required``
+    ``character`` vector of required fields.
+``optional``
+    ``character`` vector of non-required fields.
+``properties``
+    ``list`` of field definitions.
+
+See also
+~~~~~~~~
+
+See `load_schema <load_schema.md>`__ loading a ``Schema`` from
+definitions file.

docs/lang/R/topics/airr.rst

@@ -0,0 +1,9 @@
+airr
+----
+
+**airr**
+
+Description
+~~~~~~~~~~~
+
+AIRR API Package

docs/lang/R/topics/load_schema.rst

@@ -0,0 +1,57 @@
+load_schema
+-----------
+
+**Load a schema definition**
+
+Description
+~~~~~~~~~~~
+
+``load_schema`` loads an AIRR object definition from the internal
+definition set.
+
+Usage
+~~~~~
+
+::
+
+    load_schema(definition)
+
+Arguments
+~~~~~~~~~
+
+definition
+    name of the schema definition.
+
+Value
+~~~~~
+
+A `Schema <Schema-class.md>`__ object for the ``definition``.
+
+Details
+~~~~~~~
+
+Valid definitions include:
+
+-  ``"Rearrangement"``
+-  ``"Alignment"``
+-  ``"Study"``
+-  ``"Subject"``
+-  ``"Diagnosis"``
+-  ``"Sample"``
+-  ``"CellProcessing"``
+-  ``"NucleicAcidProcessing"``
+-  ``"RawSequenceData"``
+-  ``"SoftwareProcessing"``
+
+Examples
+~~~~~~~~
+
+.. code:: r
+
+    # Load the rearrangement definition
+    schema <- load_schema("Rearrangement")
+
+See also
+~~~~~~~~
+
+See `Schema <Schema-class.md>`__ for the return object.

docs/lang/R/topics/read_airr.rst

@@ -0,0 +1,75 @@
+read_airr
+---------
+
+**Read an AIRR TSV**
+
+Description
+~~~~~~~~~~~
+
+``read_airr`` reads a TSV containing AIRR records.
+
+Usage
+~~~~~
+
+::
+
+    read_airr(file, base = c("0", "1"), schema = RearrangementSchema, ...)
+
+::
+
+    validate_airr(data, schema = RearrangementSchema)
+
+::
+
+    read_rearrangement(file, base = c("0", "1"), ...)
+
+::
+
+    read_alignment(file, base = c("0", "1"), ...)
+
+Arguments
+~~~~~~~~~
+
+file
+    input file path.
+base
+    starting index for positional fields in the input file. If ``"0"``,
+    then fields ending in ``"_start"`` and ``"_end"`` are 0-based
+    half-open intervals (python style) in the input file and will be
+    converted to 1-based closed-intervals (R style). If ``"1"``, then
+    these fields will not be modified.
+schema
+    ``Schema`` object defining the output format.
+…
+    additional arguments to pass to
+    `read_tsv <http://www.rdocumentation.org/packages/readr/topics/read_delim>`__.
+
+Value
+~~~~~
+
+A data.frame of the TSV file with appropriate type and position
+conversion for fields defined in the specification.
+
+Details
+~~~~~~~
+
+``validate_airr`` validares an AIRR data.frame
+
+``read_rearrangement`` reads an AIRR TSV containing Rearrangement data.
+
+``read_alignment`` reads an AIRR TSV containing Alignment data.
+
+Examples
+~~~~~~~~
+
+.. code:: r
+
+    ### Not run:
+    # Read a Rearrangement TSV file with default options
+    # df <- read_rearrangement("file.tsv")
+
+See also
+~~~~~~~~
+
+See `Schema <Schema-class.md>`__ for the AIRR schema object definition.
+See `write_airr <write_airr.md>`__ for writing to AIRR data.