start of docs

README.md

@@ -3,6 +3,7 @@ tools for pedigree files
 
 [![PyPI version](https://badge.fury.io/py/pedagree.svg)](http://badge.fury.io/py/pedagree)
 [![Build Status](https://travis-ci.org/brentp/pedagree.svg?branch=master)](https://travis-ci.org/brentp/pedagree)
+[![Documentation Status](https://readthedocs.org/projects/pedagree/badge/?version=latest)](http://pedagree.readthedocs.org/en/latest/?badge=latest)
 
 **NOTE** this module used to be named to "peddy".
 

docs/Makefile

@@ -0,0 +1,177 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pedagree.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pedagree.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/pedagree"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pedagree"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/_build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: afd4f162f81866546b34bf43a60ac9dd
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_build/html/_sources/index.txt

@@ -0,0 +1,97 @@
+manipulation, validation and exploration of pedigrees
+=====================================================
+
+Pedagree is a python module for manipulating pedigree files.
+While the python module has sever useful features,
+most users will be intereseted in `pedagree` for its 
+utility in finding discrepancies between the relationships specified
+in `.ped` files and the relationships inferred from a 
+corresponding `.vcf` file such as can occur from sample-swaps 
+or pedigree misspecifications.
+
+The code to do this is quite simple. Below, we check for pedigree
+violations by looking at 5,000 sites (see docs for more details on selection)
+and for sex discrepancies by looking at the non-PA regions of the X
+chromosome where males should have very few HET calls.
+
+.. code-block:: python
+
+    from pedagree import Ped
+    p = Ped('ceph1463.ped')
+    ped_df = p.ped_check('ceph1463.vcf.gz', plot='ped-check.png')
+    sex_df = p.sex_check('ceph1463.vcf.gz', plot='sex-check.png', cutoff=0.15)
+
+This will create the images:
+
+.. image:: _static/ped-check.png
+
+where samples are placed in the plot according to their relationship inferred from
+the genotypes in the VCF and colored by their expected relationship from the PED file.
+Parent-child relations (which should have IBS0 of 0) have an outline to differentiate
+them from sib-sib relations.
+
+and
+
+.. image:: _static/sex-check.png
+
+From both of these cases, we can see that it doesn't look like there are any
+sample mixups. See the docs here for an example of how a sample mixup appears.
+
+
+Both of these commands also create pandas dataframes that can be saved to a file with:
+
+.. code-block:: python
+
+    ped_df.to_csv('ped-check.tsv', sep="\t", index=False)
+    sex_df.to_csv('sex-check.tsv', sep="\t", index=False)
+
+The `sex-check` file will look like::
+
+    error   het_count   het_ratio   hom_alt_count   hom_ref_count   ped_sex predicted_sex   sample
+    FALSE   27056   0.1263089096893163  86640   127565  male    male    NA12877
+    FALSE   103578  0.7371260212360158  48197   92319   female  female  NA12878
+    FALSE   99578   0.7035623949015785  50029   91505   female  female  NA12879
+    FALSE   98933   0.6946225083727102  51852   90575   female  female  NA12880
+    FALSE   97733   0.6820833856762001  51843   91443   female  female  NA12881
+    FALSE   25568   0.11903775333001225 85114   129675  male    male    NA12882
+    FALSE   25740   0.12030398489423158 82830   131128  male    male    NA12883
+    FALSE   26380   0.12349609100697533 84861   128749  male    male    NA12884
+    FALSE   98882   0.68974609375   51608   91752   female  female  NA12885
+    FALSE   27341   0.12795900219965367 85473   128197  male    male    NA12886
+    FALSE   101838  0.7297442548709092  49321   90232   female  female  NA12887
+    FALSE   24317   0.11512477334381199 84141   127082  male    male    NA12888
+    FALSE   28980   0.13943418013856812 79538   128302  male    male    NA12889
+    FALSE   100617  0.7108129874533741  48475   93077   female  female  NA12890
+    FALSE   24443   0.11661792279543319 83839   125760  male    male    NA12891
+    FALSE   100453  0.7119832162677459  47684   93405   female  female  NA12892
+    FALSE   24774   0.11745685567987862 84482   126438  male    male    NA12893
+
+And we can see that there are no inferred errors along with other information used to make that inference.
+
+The `ped-check` file will contain `n_samples` \* `n_samples` number of rows like below::
+
+    ibs0	ibs2	ibs2*	n	rel	sample_a	sample_b	pedigree_distance	pedigree_parents	predicted_parents	parent_error
+    0.0801	0.0042	0.0165	4722	0.0245	NA12877	NA12878	0.0000	False	False	False
+    0.0000	0.0125	0.0360	4723	0.5401	NA12877	NA12879	0.5000	True	True	False
+    0.0000	0.0108	0.0390	4723	0.5482	NA12877	NA12880	0.5000	True	True	False
+    0.0000	0.0119	0.0407	4723	0.5770	NA12877	NA12881	0.5000	True	True	False
+    0.0000	0.0108	0.0351	4723	0.5448	NA12877	NA12882	0.5000	True	True	False
+    0.0000	0.0112	0.0392	4723	0.5438	NA12877	NA12883	0.5000	True	True	False
+    0.0000	0.0114	0.0379	4723	0.5452	NA12877	NA12884	0.5000	True	True	False
+    0.0000	0.0110	0.0358	4723	0.5341	NA12877	NA12885	0.5000	True	True	False
+    0.0000	0.0114	0.0390	4723	0.5597	NA12877	NA12886	0.5000	True	True	False
+
+Using `IBS0`, we can infer the parent-child relationship of a pair of samples. If the inferred value
+doesn't match the relationship in the ped file, then the `parent_error` column will be `True`.
+
+..
+    .. toctree::
+       :maxdepth: 2
+..
+    Indices and tables
+    ==================
+..
+    * :ref:`genindex`
+    * :ref:`modindex`
+    * :ref:`search`
+