From: Diane Trout Date: Tue, 15 Jan 2013 23:09:56 +0000 (-0800) Subject: Start making documentation for htsworkflow. X-Git-Url: http://woldlab.caltech.edu/gitweb/?p=htsworkflow.git;a=commitdiff_plain;h=ea083869640f95843b72c0778d16bba39086dee5 Start making documentation for htsworkflow. This is a tiny start toward creating documentation for htsworkflow, mostly I was getting confused about some of my classes and thought I should try to get some API documentation going. Since I wanted to make sure I had the docstring syntax right I needed some way to actually build the documentation, and so I might as well commit what little documentation I created. --- diff --git a/.gitignore b/.gitignore index 6d73f11..3eb65bb 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,4 @@ .tox dist RELEASE-VERSION +docs/build/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..6fe1342 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,153 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.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 ' where 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 " 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 " 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/HTS-Workflow.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/HTS-Workflow.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/HTS-Workflow" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/HTS-Workflow" + @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." + +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." diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 0000000..e6c6c11 --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,134 @@ +Runfolder Processing +==================== + +Runfolder +--------- + +The PipelineRun class is designed to combine information +from the following importers. + +* Image Analysis (one of the following) + + * :class:`Firecrest` + * :class:`IPAR` + +* BaseCaller + + * :class:`Bustard` + +* Sequence Alignment + + * :class:`Gerald` + +.. automodule:: htsworkflow.pipelines.runfolder + :members: + +.. _Firecrest: + +Firecrest +--------- + +.. automodule:: htsworkflow.pipelines.firecrest + :members: + +.. _IPAR: + +IPAR +---- + +.. automodule:: htsworkflow.pipelines.ipar + :members: + +.. _Bustard: + +Bustard +------- +.. automodule:: htsworkflow.pipelines.bustard + :members: + +.. _Gerald: + +Gerald +------ + +.. automodule:: htsworkflow.pipelines.gerald + :members: + +.. _Eland: + +Eland +----- + +.. automodule:: htsworkflow.pipelines.eland + :members: + +.. _Summary: + +Summary +------- + +.. automodule:: htsworkflow.pipelines.summary + :members: + +Sequence Archival +================= + +srf +--- + +.. automodule:: htsworkflow.pipelines.srf + :members: + +Fastq conversion +================ + +srf2fastq +--------- + +.. automodule:: htsworkflow.pipelines.srf2fastq + :members: + +qseq2fastq +---------- + +.. automodule:: htsworkflow.pipelines.qseq2fastq + :members: + +desplit_fastq +------------- + +.. automodule:: htsworkflow.pipelines.desplit_fastq + :members: + +sequences +--------- + +.. automodule:: htsworkflow.pipelines.sequences + :members: + +Utilities +========= + +.. automodule:: htsworkflow.pipelines.genome_mapper + :members: + +.. automodule:: htsworkflow.pipelines.genomemap + :members: + +.. automodule:: htsworkflow.pipelines.samplekey + :members: + +.. automodule:: htsworkflow.pipelines.recipe_parser + :members: + +Run Automation +============== + +.. automodule:: htsworkflow.pipelines.configure_run + :members: + +.. automodule:: htsworkflow.pipelines.retrieve_config + :members: + +.. automodule:: htsworkflow.pipelines.run_status + :members: diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..08f47eb --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,290 @@ +# -*- coding: utf-8 -*- +# +# HTS-Workflow documentation build configuration file, created by +# sphinx-quickstart on Mon Jan 14 10:18:40 2013. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) +sys.path.insert(0, os.path.abspath('../../htsworkflow')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.coverage', 'sphinx.ext.viewcode'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['.templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'HTS-Workflow' +copyright = u'2013, Diane Trout' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.5' +# The full version, including alpha/beta/rc tags. +release = '0.5.4' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['.static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'HTS-Workflowdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'HTS-Workflow.tex', u'HTS-Workflow Documentation', + u'Diane Trout', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'hts-workflow', u'HTS-Workflow Documentation', + [u'Diane Trout'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'HTS-Workflow', u'HTS-Workflow Documentation', + u'Diane Trout', 'HTS-Workflow', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + + +# -- Options for Epub output --------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = u'HTS-Workflow' +epub_author = u'Diane Trout' +epub_publisher = u'Diane Trout' +epub_copyright = u'2013, Diane Trout' + +# The language of the text. It defaults to the language option +# or en if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +#epub_exclude_files = [] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..9a15dbd --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,22 @@ +.. HTS-Workflow documentation master file, created by + sphinx-quickstart on Mon Jan 14 10:18:40 2013. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to HTS-Workflow's documentation! +======================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + api + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/htsworkflow/pipelines/firecrest.py b/htsworkflow/pipelines/firecrest.py index 85b9d39..3519eb0 100644 --- a/htsworkflow/pipelines/firecrest.py +++ b/htsworkflow/pipelines/firecrest.py @@ -24,9 +24,9 @@ from htsworkflow.pipelines import \ LOGGER = logging.getLogger(__name__) -__docformat__ = "restructuredtext en" - class Firecrest(object): + """Gather information about older firecrest runs + """ XML_VERSION=1 # xml tag names @@ -39,6 +39,12 @@ class Firecrest(object): MATRIX = 'matrix' def __init__(self, xml=None): + """Initialize a Firecrest object + + consider using factory :function:firecrest + + :param xml: xml serialzation element to initialze from [optional] + """ self.start = None self.stop = None self.version = None @@ -58,6 +64,8 @@ class Firecrest(object): time = property(_get_time, doc='return run time as seconds since epoch') def dump(self): + """Report debugginf information + """ print "Starting cycle:", self.start print "Ending cycle:", self.stop print "Firecrest version:", self.version @@ -65,6 +73,8 @@ class Firecrest(object): print "user:", self.user def get_elements(self): + """Return XML serialization structure. + """ attribs = {'version': str(Firecrest.XML_VERSION) } root = ElementTree.Element(Firecrest.FIRECREST, attrib=attribs) version = ElementTree.SubElement(root, Firecrest.SOFTWARE_VERSION) diff --git a/htsworkflow/pipelines/runfolder.py b/htsworkflow/pipelines/runfolder.py index f23b255..b072dd9 100644 --- a/htsworkflow/pipelines/runfolder.py +++ b/htsworkflow/pipelines/runfolder.py @@ -1,5 +1,4 @@ -""" -Core information needed to inspect a runfolder. +"""Core information needed to inspect a runfolder. """ from glob import glob import logging @@ -29,14 +28,34 @@ from htsworkflow.util.queuecommands import QueueCommands from htsworkflow.pipelines import srf class PipelineRun(object): - """ - Capture "interesting" information about a pipeline run + """Capture "interesting" information about a pipeline run + + :Variables: + - `pathname` location of the root of this runfolder + - `name` read only property containing name of run xml file + - `flowcell_id` read-only property containing flowcell id (bar code) + - `datadir` location of the runfolder data dir. + - `image_analysis` generic name for Firecrest or IPAR image analysis + - `bustard` summary base caller + - `gerald` summary of sequence alignment and quality control metrics """ XML_VERSION = 1 PIPELINE_RUN = 'PipelineRun' FLOWCELL_ID = 'FlowcellID' def __init__(self, pathname=None, flowcell_id=None, xml=None): + """Initialize a PipelineRun object + + :Parameters: + - `pathname` the root directory of this run folder. + - `flowcell_id` the flowcell ID in case it can't be determined + - `xml` Allows initializing an object from a serialized xml file. + + :Types: + - `pathname` str + - `flowcell_id` str + - `ElementTree` str + """ if pathname is not None: self.pathname = os.path.normpath(pathname) else: @@ -52,6 +71,10 @@ class PipelineRun(object): self.set_elements(xml) def _get_flowcell_id(self): + """Return the flowcell ID + + Attempts to find the flowcell ID through several mechanisms. + """ # extract flowcell ID if self._flowcell_id is None: self._flowcell_id = self._get_flowcell_id_from_runinfo() @@ -71,6 +94,8 @@ class PipelineRun(object): def _get_flowcell_id_from_flowcellid(self): """Extract flowcell id from a Config/FlowcellId.xml file + + :return: flowcell_id or None if not found """ config_dir = os.path.join(self.pathname, 'Config') flowcell_id_path = os.path.join(config_dir, 'FlowcellId.xml') @@ -80,6 +105,8 @@ class PipelineRun(object): def _get_flowcell_id_from_runinfo(self): """Read RunInfo file for flowcell id + + :return: flowcell_id or None if not found """ runinfo = os.path.join(self.pathname, 'RunInfo.xml') if os.path.exists(runinfo): @@ -89,9 +116,10 @@ class PipelineRun(object): if len(fc_nodes) == 1: return fc_nodes[0].text - def _get_flowcell_id_from_path(self): """Guess a flowcell name from the path + + :return: flowcell_id or None if not found """ path_fields = self.pathname.split('_') if len(path_fields) > 0: @@ -105,22 +133,37 @@ class PipelineRun(object): return self.gerald.runfolder_name runfolder_name = property(_get_runfolder_name) - def get_elements(self): + def _get_run_id(self): + """Return a identifer for a run. + + For pre-multiplexing runs this is just the cycle range C1-123 + For post-multiplexing runs the "suffix" that we add to + differentiate runs will be added to the range. + E.g. Unaligned_6mm may produce C1-200_6mm """ - make one master xml file from all of our sub-components. + pass + + def get_elements(self): + """make one master xml file from all of our sub-components. + + :return: an ElementTree containing all available pipeline + run xml compoents. """ root = ElementTree.Element(PipelineRun.PIPELINE_RUN) flowcell = ElementTree.SubElement(root, PipelineRun.FLOWCELL_ID) flowcell.text = self.flowcell_id root.append(self.image_analysis.get_elements()) root.append(self.bustard.get_elements()) - root.append(self.gerald.get_elements()) + if self.gerald: + root.append(self.gerald.get_elements()) return root def set_elements(self, tree): - # this file gets imported by all the others, - # so we need to hide the imports to avoid a cyclic imports + """Initialize a PipelineRun object from an run.xml ElementTree. + :param tree: parsed ElementTree + :type tree: ElementTree + """ tag = tree.tag.lower() if tag != PipelineRun.PIPELINE_RUN.lower(): raise ValueError('Pipeline Run Expecting %s got %s' % ( @@ -145,8 +188,13 @@ class PipelineRun(object): LOGGER.warn('PipelineRun unrecognized tag %s' % (tag,)) def _get_run_name(self): - """ - Given a run tuple, find the latest date and use that as our name + """Compute the run name for the run xml file + + Attempts to find the latest date from all of the run + components. + + :return: run xml name + :rtype: str """ if self._name is None: tmax = max(self.image_analysis.time, self.bustard.time, self.gerald.time) @@ -156,6 +204,12 @@ class PipelineRun(object): name = property(_get_run_name) def save(self, destdir=None): + """Save a run xml file. + + :param destdir: Directory name to save too, uses current directory + if not specified. + :type destdir: str + """ if destdir is None: destdir = '' LOGGER.info("Saving run report " + self.name) @@ -165,6 +219,14 @@ class PipelineRun(object): ElementTree.ElementTree(xml).write(dest_pathname) def load(self, filename): + """Load a run xml into this object. + + :Parameters: + - `filename` location of a run xml file + + :Types: + - `filename` str + """ LOGGER.info("Loading run report from " + filename) tree = ElementTree.parse(filename).getroot() self.set_elements(tree) @@ -174,7 +236,7 @@ def load_pipeline_run_xml(pathname): Load and instantiate a Pipeline run from a run xml file :Parameters: - - `pathname` : location of an run xml file + - `pathname` location of an run xml file :Returns: initialized PipelineRun object """ @@ -183,19 +245,16 @@ def load_pipeline_run_xml(pathname): return run def get_runs(runfolder, flowcell_id=None): - """ - Search through a run folder for all the various sub component runs - and then return a PipelineRun for each different combination. + """Find all runs associated with a runfolder. + + We end up with multiple analysis runs as we sometimes + need to try with different parameters. This attempts + to return a list of all the various runs. For example if there are two different GERALD runs, this will generate two different PipelineRun objects, that differ in there gerald component. """ - from htsworkflow.pipelines import firecrest - from htsworkflow.pipelines import ipar - from htsworkflow.pipelines import bustard - from htsworkflow.pipelines import gerald - datadir = os.path.join(runfolder, 'Data') LOGGER.info('Searching for runs in ' + datadir) @@ -284,7 +343,6 @@ def build_hiseq_runs(image_analysis, runs, datadir, runfolder, flowcell_id): LOGGER.warn("Aligned directory %s without matching unalinged, skipping", aligned) continue - g = gerald.gerald(aligned) print "scan for aligned then remove them from unaligned list" try: p = PipelineRun(runfolder, flowcell_id) diff --git a/htsworkflow/pipelines/srf.py b/htsworkflow/pipelines/srf.py index d7efc7d..5a6c969 100644 --- a/htsworkflow/pipelines/srf.py +++ b/htsworkflow/pipelines/srf.py @@ -42,7 +42,7 @@ def make_srf_commands(run_name, bustard_dir, lanes, site_name, destdir, cmdlevel make a subprocess-friendly list of command line arguments to run solexa2srf generates files like: woldlab:080514_HWI-EAS229_0029_20768AAXX:8.srf - site run name lane + site run name lane run_name - most of the file name (run folder name is a good choice) lanes - list of integers corresponding to which lanes to process