From a8671c2268e4d5f098648c4957ccac696894027a Mon Sep 17 00:00:00 2001
From: juergen <juergen@5a81b35b-ba03-0410-adc8-b2c5c5119f08>
Date: Tue, 22 Jun 2010 16:51:59 +0000
Subject: [PATCH] adding sequence and alignments to io docu
git-svn-id: https://dng.biozentrum.unibas.ch/svn/openstructure/trunk@2443 5a81b35b-ba03-0410-adc8-b2c5c5119f08
---
modules/io/doc/formats.rst | 26 +++++++-----
modules/io/doc/io.rst | 86 +++++++++++++++++++++++++++++++++++---
2 files changed, 96 insertions(+), 16 deletions(-)
diff --git a/modules/io/doc/formats.rst b/modules/io/doc/formats.rst
index ceef7e5f2..91a9f029c 100644
--- a/modules/io/doc/formats.rst
+++ b/modules/io/doc/formats.rst
@@ -7,12 +7,24 @@ Structure File Formats
The following file formats are supported by :func:`~ost.io.LoadEntity`.
-
+
+CRD - CARD format file used by CHARMM
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This trajectory file format is used by the CHARMM program suite (Molecular Modelling).
+*Recognized File Extensions*
+ crd
+
+MAE - Maestro coordinate file format (used by Schroedinger Inc.)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+File format by the popular Maestro package.
+*Recognized File Extensions*
+ mae
+
PDB - Brookhaven PDB File
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Fine grained control over PDB file import is available via the
-:func:`~ost.io.LoadPDB` function. The PDB importer support loading gzipped PDB
-files. gzipped PDB files are detected by the .gz file extension.
+:func:`~ost.io.LoadPDB` function. The PDB importer supports loading gzipped PDB
+files, which are auto-detected by the .gz file extension.
*Recognized File Extensions*
ent, pdb, ent.gz, pdb.gz
@@ -28,12 +40,6 @@ PQR
*Format Name*
pqr
-
-CRD - CARD format file used by CHARMM
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-*Recognized File Extensions*
- crd
SDF
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -78,4 +84,4 @@ PIR
pir
*Format Name*
- pir
\ No newline at end of file
+ pir
diff --git a/modules/io/doc/io.rst b/modules/io/doc/io.rst
index 21c38bc4f..33258a6a2 100644
--- a/modules/io/doc/io.rst
+++ b/modules/io/doc/io.rst
@@ -2,12 +2,9 @@
================================================================================
.. module:: ost.io
- :synopsis: Input and output of sequences, structures and density maps
+ :synopsis: Input and output of sequences, alignments, structures, images and density maps.
-The io module deals with input and output of :class:`entities
-<ost.mol.EntityHandle>`, :class:`alignments <ost.seq.AlignmentHandle>`, and
-:class:`images <ost.img.ImageHandle>`. Importers for common file formats such
-as PDB, SDF, FASTA, CLUSTAL W, DX and CHARMM trajectory files are available.
+The io module deals with input and output of :class:`entities <ost.mol.EntityHandle>`, :class:`alignments <ost.seq.AlignmentHandle>`, :class:`sequences <ost.seq.SequenceHandle>`, :class:`images <ost.img.ImageHandle>`. Importers for common file formats containing molecules such as PDB, SDF and CHARMM trajectory files are available. Sequence and alignment file formats such as FASTA and CLUSTALW are supported as well, alongside various image data (e.g. png, dm3) and density map files (e.g. CCP4, MRC).
Molecular Structures
--------------------------------------------------------------------------------
@@ -100,4 +97,81 @@ file:
.. autofunction:: ost.io.SavePDB
-
\ No newline at end of file
+
+Sequences and Alignments
+--------------------------------------------------------------------------------
+
+Loading sequence or alignment files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. function:: LoadSequence(filename, format='auto')
+
+ Load sequence data from disk. If format is set to 'auto', the function guesses the
+ filetype based on the extension of the file. Files ending in '.fasta', '.aln' will automatically be loaded.
+ For files with non-standard extensions, the format can be set explicitly specifying
+ the 'format' parameter.
+
+ .. code-block:: python
+
+ # recognizes FASTA file by file extension
+ myseq=io.LoadSequence('seq.fasta')
+ # for obtaining a SequenceList
+ seqlist=io.LoadSequenceList('seqs.fasta')
+ # or for multiple aligned fasta files use
+ aln=io.LoadAlignment('algnm.aln',format="clustal")
+
+For a list of file formats supported by :func:`LoadSequence` see :doc:`formats`.
+
+ :raises: :exc:`~ost.io.IOUnknownFormatException` if the format string supplied
+ is not recognized or the file format can not be detected based on the
+ file extension
+
+ :exc:`~ost.io.IOException` if the import fails due to an erroneous or
+ inexistent file
+
+.. function:: LoadSequenceList(filename, format='auto')
+
+ For a desription of how to use :func:`LoadSequenceList` please refer to :func:`LoadSequence`.
+ For a list of file formats supported by :func:`LoadSequenceList` see :doc:`formats`.
+
+.. function:: LoadAlignment(filename, format='auto')
+
+ For a desription of how to use :func:`LoadAlignment` please refer to :func:`LoadSequence`.
+ For a list of file formats supported by :func:`LoadAlignment` see :doc:`formats`.
+
+Saving Sequence Data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. function:: SaveSequence(filename, format='auto')
+
+Saving sequence data is performed by calling :func:`SaveSequence`.
+For files with non-standard extensions, the format can be set explicitly specifying
+the 'format' parameter.
+
+ .. code-block:: python
+
+ # recognizes FASTA file by file extension
+ io.SaveSequence(myseq,'seq.fasta')
+ # for saving a SequenceList
+ io.SaveSequenceList(seqlist,'seqlist.fasta')
+ # or multiple aligned fasta files
+ io.SaveAlignment(aln,'algnm.aln',format="clustal")
+
+For a list of file formats supported by :func:`SaveSequence` see :doc:`formats`.
+
+ :raises: :exc:`~ost.io.IOUnknownFormatException` if the format string supplied
+ is not recognized or the file format can not be detected based on the
+ file extension
+
+ :exc:`~ost.io.IOException` if the import fails due to an erroneous or
+ inexistent file
+
+.. function:: SaveSequenceList(filename, format='auto')
+
+ For a desription of how to use :func:`SaveSequenceList` please refer to :func:`SaveSequence`.
+ For a list of file formats supported by :func:`SaveSequenceList` see :doc:`formats`.
+
+.. function:: SaveAlignment(filename, format='auto')
+
+ For a desription of how to use :func:`SaveAlignment` please refer to :func:`SaveSequence`.
+ For a list of file formats supported by :func:`SaveAlignment` see :doc:`formats`.
+
--
GitLab