diff --git a/modules/index.rst b/modules/index.rst index 89bb6d3614d7c91c7fb9050a1fc9f9ab73deecc3..ba74e38481d3064723df642a3330b3b210c4b4ba 100644 --- a/modules/index.rst +++ b/modules/index.rst @@ -57,6 +57,7 @@ Density Maps and Images **Overview**: :doc:`images intro <intro-02>` | :doc:`img module <img/base/img>` | :doc:`img.alg module <img/alg/alg>` +**Input/Output**: :ref:`loading and saving density maps <img-io>` @@ -93,7 +94,9 @@ Varia **Datasets:** :doc:`tabular data <table>` -**File Formats:** :doc:`supported file formats <io/formats>` +**File Formats:** :doc:`supported structure file formats <io/structure_formats>` +**File Formats:** :doc:`supported sequence file formats <io/sequence_formats>` +**File Formats:** :doc:`supported image file formats <io/image_formats>` Extending OpenStructure diff --git a/modules/io/doc/formats.rst b/modules/io/doc/formats.rst deleted file mode 100644 index fc6fee4cb8e12e0b2ed01731d0a213be18270b76..0000000000000000000000000000000000000000 --- a/modules/io/doc/formats.rst +++ /dev/null @@ -1,186 +0,0 @@ -Supported File Formats -================================================================================ - -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 - -PDB - Brookhaven PDB File -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Fine grained control over PDB file import is available via the -: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 - -*Format Name* - pdb - -PQR -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - pqr - -*Format Name* - pqr - -SDF - Structured Data File -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - sdf - -Sequence File Formats --------------------------------------------------------------------------------- - -FASTA -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - fasta, fna, fas, fa, fsa - -*Format Name* - fasta - -ClustalW -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - aln - -*Format Name* - clustal - -Promod -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - ali - -*Format Name* - promod - - -Image File Formats --------------------------------------------------------------------------------- - -DAT -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - dat, img - -*Format Name* - Simple binary format for square images - -DF3 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - df3 - -*Format Name* - PovRay Density file format - -DM3 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - dm3 - -*Format Name* - Format used by Gatan Inc.'s Digital Micrograph software - -DX -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - dx - -*Format Name* - Format used by the OpenDX software package - -IPL -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - ipl - -*Format Name* - Ditabis Micron Image Plate Scanner Format - -JPK -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - jpk - -*Format Name* - Format used by JPK Instruments AG's software (Customized Tiff format) - -MRC -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - map, ccp4, mrc - -*Format Name* - Format used by the MRC software package - -NanoScope -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - mod - -*Format Name* - Format used by software from Veeco - -PNG -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - png - -*Format Name* - Portable Network Graphic image format - -Situs -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - situs, sit - -*Format Name* - Format used by the Situs software package - -SPI -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - spi - -*Format Name* - Format used by the Spider software package - -TIFF -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -*Recognized File Extensions* - tif, tiff - -*Format Name* - Tagged Image File Format - diff --git a/modules/io/doc/image_formats.rst b/modules/io/doc/image_formats.rst new file mode 100644 index 0000000000000000000000000000000000000000..3219b231adc4b87a60659c175740c111680e4086 --- /dev/null +++ b/modules/io/doc/image_formats.rst @@ -0,0 +1,136 @@ +Supported Image File Formats +================================================================================ + +CCP4 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Format used by the ccp4 software package + +* Recognized file extensions: *ccp4, map* +* Recognized based on content: *yes* +* File import: *yes* +* File export: *yes* + + + +DAT +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Simple binary format for square images + +* Recognized file extensions: *dat, img* +* Recognized based on content: *no* +* File import: *yes* +* File export: *yes* + + +DF3 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +PovRay Density file format + +* Recognized file extensions: *df3* +* Recognized based on content: *no* +* File import: *no* +* File export: *yes* + +DM3 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Format used by Gatan Inc.'s Digital Micrograph software + +* Recognized file extensions: *dm3* +* Recognized based on content: *yes* +* File import: *yes* +* File export: *no* + +DX +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Format used by the OpenDX software package + +* Recognized file extensions: *dx* +* Recognized based on content: *no* +* File import: *yes* +* File export: *yes* + +IPL +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ditabis Micron Image Plate Scanner Format + +* Recognized file extensions: *ipl* +* Recognized based on content: *yes* +* File import: *yes* +* File export: *yes* + +JPK +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Format used by JPK Instruments AG's software (Customized Tiff format) + +* Recognized file extensions: *jpk* +* Recognized based on content: *no (jpk files without file extension are recognized as tif)* +* File import: *yes* +* File export: *yes* + +MRC +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Format used by the MRC software package + +* Recognized file extensions: *mrc* +* Recognized based on content: *yes* +* File import: *yes* +* File export: *yes* + +NanoScope +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Format used by software from Veeco + +* Recognized file extensions: *mod* +* Recognized based on content: *no* +* File import: *yes* +* File export: *yes* + +PNG +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Portable Network Graphic image format + +* Recognized file extensions: *png* +* Recognized based on content: *yes* +* File import: *yes* +* File export: *yes* + +Situs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Format used by the Situs software package + +* Recognized file extensions: *situs, sit* +* Recognized based on content: *no* +* File import: *yes* +* File export: *yes* + +Spider +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Format used by the Spider software package + +* Recognized file extensions: *spi* +* Recognized based on content: *no* +* File import: *yes* +* File export: *yes* + +TIFF +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Tagged Image File Format + +* Recognized file extensions: *tif, tiff* +* Recognized based on content: *yes* +* File import: *yes* +* File export: *yes* + diff --git a/modules/io/doc/io.rst b/modules/io/doc/io.rst index 41759d1987ef149bd53ed942fc21814b22ba43c0..ea47d5d6783f567e1d385e56db0a02f255df45e1 100644 --- a/modules/io/doc/io.rst +++ b/modules/io/doc/io.rst @@ -4,7 +4,9 @@ .. toctree:: :hidden: - formats + structure_formats + sequence_formats + image_formats mmcif profile @@ -49,7 +51,7 @@ on the file extension. # SDF file explicitly ent=io.LoadEntity('file', 'sdf') - For a list of file formats supported by :func:`LoadEntity`, see :doc:`formats`. + For a list of file formats supported by :func:`LoadEntity`, see :doc:`structure_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 @@ -145,7 +147,7 @@ Loading sequence or alignment files aln=io.LoadAlignment('algnm.aln',format="clustal") For a list of file formats supported by :func:`LoadSequence` see - :doc:`formats`. + :doc:`sequence_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 @@ -158,13 +160,13 @@ Loading sequence or alignment files 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`. + :func:`LoadSequenceList` see :doc:`sequence_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`. + :func:`LoadAlignment` see :doc:`sequence_formats`. Saving Sequence Data ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -185,7 +187,7 @@ Saving Sequence Data io.SaveAlignment(aln,'algnm.aln',format="clustal") For a list of file formats supported by :func:`SaveSequence` see - :doc:`formats`. + :doc:`sequence_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 @@ -198,7 +200,7 @@ Saving Sequence Data 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`. + :func:`SaveSequenceList` see :doc:`sequence_formats`. .. function:: SaveAlignment(aln, filename, format='auto') @@ -206,7 +208,79 @@ Saving Sequence Data :func:`SaveSequence`. For a list of file formats supported by :func:`SaveAlignment` see - :doc:`formats`. + :doc:`sequence_formats`. + + +.. _img-io: + +Density Maps +-------------------------------------------------------------------------------- + +Loading Density Maps +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: LoadImage(filename) +.. function:: LoadImage(filename, format) + + Load density map from disk. If no format is given, the function guesses the + filetype based on the extension of the file. If the extension is unknown or not present the + filetype will be guessed based on the content of the file if possible. + + :param filename: The filename + :type filename: string + :param format: The file format + + :raises: :exc:`~ost.io.IOUnknownFormatException` if the format supplied + is not recognized or the file format can not be detected based on the + file extension and content + + :exc:`~ost.io.IOException` if the import fails due to an erroneous or + inexistent file + + .. code-block:: python + + # recognizes mrc file by file extension + ent=io.LoadImage('file.mrc') + + # It is always possible to explicitely set the image format + # DAT file explicitly + ent=io.LoadImage('file', Dat()) + + For a list of file formats supported by :func:`LoadImage`, see :doc:`image_formats`. + + + + +Saving Density Maps +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: SaveImage(image,filename) +.. function:: SaveImage(image,filename, format) + + + Save density map to disk. If no format is set, the function guesses the + filetype based on the file extension. + + :param image: The density map to be saved + :type image: :class:`~ost.img.IMageHandle` + :param filename: The filename + :type filename: string + :param format: The file format + + :raises: :exc:`~ost.io.IOUnknownFormatException` if the file format can not be detected based on the + file extension + + For a list of file formats supported by :func:`SaveImage`, see :doc:`image_formats`. + + +.. code-block:: python + # load density map + image=io.LoadImage('density_map.ccp4') + # save density map + io.SaveImage(image, 'new_map.map', CCP4()) + + + .. testsetup:: io diff --git a/modules/io/doc/sequence_formats.rst b/modules/io/doc/sequence_formats.rst new file mode 100644 index 0000000000000000000000000000000000000000..63f01ffc9189be292ec376a7e124a6faa7fb5cfc --- /dev/null +++ b/modules/io/doc/sequence_formats.rst @@ -0,0 +1,31 @@ +Supported Sequence File Formats +================================================================================ + +FASTA +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Recognized File Extensions* + fasta, fna, fas, fa, fsa + +*Format Name* + fasta + +ClustalW +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Recognized File Extensions* + aln + +*Format Name* + clustal + +Promod +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Recognized File Extensions* + ali + +*Format Name* + promod + + diff --git a/modules/io/doc/structure_formats.rst b/modules/io/doc/structure_formats.rst new file mode 100644 index 0000000000000000000000000000000000000000..eebc0cec0e1c4ab065ff1e7d188e7013803c3cfd --- /dev/null +++ b/modules/io/doc/structure_formats.rst @@ -0,0 +1,41 @@ +Supported 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 + +PDB - Brookhaven PDB File +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Fine grained control over PDB file import is available via the +: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 + +*Format Name* + pdb + +PQR +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Recognized File Extensions* + pqr + +*Format Name* + pqr + +SDF - Structured Data File +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Recognized File Extensions* + sdf +