comparison docs/scripts/txt/SDFilesToHTML.txt @ 0:4816e4a8ae95 draft default tip

Uploaded

0:4816e4a8ae95

NAME
    SDFilesToHTML.pl - Generate HTML table file(s) from SDFile(s)

SYNOPSIS
    SDFilesToHTML.pl SDFiles(s)...

    SDFilesToHTML.pl [-a, --align left | center | right,[top | middle |
    bottom]] [-b, --border borderwidth] [--cellpadding padding]
    [--cellspacing spacing] [--cmpddatafield
    "fieldlabel,[label,position,alignment]"] [--datafields
    "fieldlabel,[fieldlabel]..." | Common | All] [--footer string] [-d,
    --displaylinks top | bottom | both] [--displaylinksinfo compound | table
    | both] [-h, --help] [--headeralign left | center | right,[top | middle
    | bottom]] [--headercolor "#RRGGBB"] [--highlight
    "fieldlabel,datatype,criterion,value,[fieldlabel,datatype,criterion,valu
    e,...]"] [--highlightcolor "#RRGGBB,#RRGGBB"] [--highlightstyle text |
    background] [-m, --mode plain | shade | highlight | shadedhighlight |
    structuresonly | shadedstructuresonly] [-n, --numcmpds number] [-o,
    --overwrite] [-r, --root rootname] [-s, --structure display | link]
    [--strlinkmode plain | shaded] [--strlinknavigation yes | no]
    [--strlinkshadecolor "#RRGGBB"] [--strlinktitle string]
    [--strlinktitledisplay yes | no] [--strlinktype href | button]
    [--strviewertype Chem3DActiveX | ChemDrawActiveX | ChemDrawPlugIn |
    Chime | JME | Jmol | MarvinView | ViewerActiveX] [--strviewerconfig
    codebase[,archive,code]] [--strviewerparams "name=value [name=value
    ...]"] [--strviewerembed direct | javascript] [--strviewerjsfile
    javascriptfilename] [--strtablesize "numrows,numcols"] [--stylesheet old
    | new | none] [--stylesheetname filename] [--shadecolor
    "#RRGGBB,#RRGGBB"] [-t, --title string] [--titledisplay yes | no] [-w,
    --workingdir dirname] SDFiles(s)...

DESCRIPTION
    Generate HTML file(s) from *SDFile(s)*. The HTML file(s) contain data
    tables and appropriate navigational links to view other tables;
    navigational links are also provided on compound HTML pages. These files
    can be generated for local viewing or deployment on a web server. A
    variety of options are provided to control style and appearance of
    tables. And for viewing structures, options are available to use any one
    of these viewers: Chem3DActiveX, ChemDrawActiveX, ChemDrawPlugIn, Chime,
    Jmol, JME, MarvinView, or ViewerActiveX. Jmol is the default structure
    viewer and it is also distributed along with this package; however, to
    use any other supported viewers, make sure it's available in your
    environment.

    Multiple *SDFile(s)* names are separated by space. The valid file
    extensions are *.sdf* and *.sd*. All other file names are ignored. All
    the SD files in a current directory can be specified either by **.sdf*
    or the current directory name.

OPTIONS
    -a, --align *left | center | right,[top | middle | bottom]*
        Horizontal and vertical alignment for table rows except for header
        row which is specified using --headeralign option. Possible
        horizontal alignment values: *left, center, or right*. Possible
        vertical alignment values: *top, middle, or bottom*.

        Default values: *left,middle*

    -b, --border *borderwidth*
        Table border width. Default value: 1 for *plain* and *highlight*
        mode; 0 for *shade* and *shadedhightlight* mode. Zero indicates no
        border.

    --cellpadding *padding*
        Table cell padding. Default value: *2*.

    --cellspacing *spacing*
        Table cell spacing. Default value: *1*.

    --cmpddatafield *fieldlabel,[label,position,alignment]*
        This value is mode specific. It indicates data field value to be
        displayed with the structure along with its label, position and
        alignment during *structuresonly | shadedstructuresonly* value of
        -m, --mode option. Possible values: feldlabel - valid data field
        label; label - yes or no; position - *top or bottom*; alignment -
        *left, center, or right*. Default: *none,no,bottom,center*. Example:

            MolWt,no,bottom,middle

        --cmpddatafield option value is also linked to compound summary
        page.

    --datafields *"fieldlabel,[fieldlabel]..." | Common | All*
        Data fields to display in HTML table(s). Possible values: list of
        comma separated data field labels, data fields common to all
        records, or all data fields. Default value: *All*. Examples:

            ALogP,MolWeight,EC50
            "MolWeight,PSA"

    --footer *string*
        Text string to be included at bottom of each HTML file. Default:
        none.

    -d --displaylinks *top | bottom | both*
        Specify where to display navigation links in each HTML file for
        accessing all other HTML files. Possible values: *top, bottom, or
        both*. Default: *both*. This option is only valid during multiple
        HTML files generation for an input file.

    --displaylinksinfo *compound | table | both*
        Control display of additional information along with navigational
        links: Showing compound n of m is displyed for compound and showing
        table n of m for table. Possible values: *compound | table | both*.
        Default: *both*. This option is only valid during multiple HTML
        files generation.

    -h, --help
        Print this help message.

    --headeralign *left | center | right,[top | middle | bottom*
        Horizontal and vertical alignment for table header rows. Possible
        horizontal alignment values: *left, center, or right*. Possible
        vertical alignment values: *top, middle, or bottom*.

        Default values: *center,middle*

    --headercolor *#RRGGBB*
        Color used to fill background of table header row containing column
        labels represented as a hexadecimal string. Default value: None for
        -m, --mode option value of *plain* and *#ccccff*, light blue, for
        others.

    --highlight
    *"fieldlabel,datatype,criterion,value,[fieldlabel,datatype,criterion,val
    ue,...]"*
        Highlighting methodology used to highlight various SDFile(s) data
        field values in HTML file(s). Same set of quartets values are
        applied to all SDFile(s).

        Input text contains these quartets:
        *fieldlabel,datatype,criterion,value,...*. Possible datatype values:
        *numeric or text*. Possible criterion values: *le, ge, or eq*.
        Examples:

            "MolWt,numeric,le,450"
            "MolWt,numeric,le,450,LogP,numeric,le,5"
            Name,text,eq,Aspirin

    --highlightcolor *"#RRGGBB,#RRGGBB"*
        Colors used to highlight column values during *highlight* and
        *shadedhightlight* mode represented as hexadecimal strings.

        For --highlighstyle option values of *text* and *background*, these
        colors represent text or background colors respectively. For a
        specific column, first color string is used for values which meet
        criterion indicated by --highlight option; the second color is used
        for rest of the values.

        Default values for *background* --highlightstyle:
        *"#0fff0f,#ff0f0f"*. And default values for *text* --highlightstyle:
        *"#0fbb0f,#ff0f0f"*. Hexadecimal strings for both --highlightstyle
        colors correspond to *reddish* and *greenish*.

    --highlightstyle *text | background*
        This value is mode specific. It indicates highlight style used to
        differentiate column values which meet a specified criterion in
        --highlight option. Possible values: *text or background*. Default:
        *background*.

    -m, --mode *plain | shade | highlight | shadedhighlight | structuresonly
    | shadedstructuresonly*
        Specify how to generate HTML table(s): plain tables with line
        borders, background of alternate rows filled with a specified color,
        column values highlighted using a specified criteria, combination of
        previous two styles, tables containing only structures, or tables
        containing only structures with filled background of alternate rows.

        Possible values: *plain, shade, highlight, shadedhighlight,
        structuresonly, or shadedstructuresonly*. Default: *shade*.

    -n, --numcmpds *number*
        Maximum number of compounds per table. Default value: *15* for
        tables with structures and *50* for tables with links to structures.
        Use 0 to put all compounds into one table. For SDFile(s) with more
        than maximum number of specified compounds, multiple HTML tables,
        with appropriate navigation links, are created.

    -o, --overwrite
        Overwrite existing files.

    -r, --root *rootname*
        New file or directory name is generated using the root: <root>.html
        or <root>-html. Default new file name: <InitialSDFileName>.html.
        Default directory name: <InitialSDFileName>-html.

        For SDFile(s) with more than maximum number of specified compounds
        per table, this directory tree is generated using <Name> where
        <Name> corresponds to <root> or <InitialSDFileName>: Top dir -
        <Name>-html; Sub dirs - html and mols. <Top dir> contains
        <Name>.html and <Name>.css files and <sub dir> html conatins various
        <Name>Lines<Start>To<End>.html files; <sub dir> mols is created as
        needed and contains MOL files.

        This option is ignored for multiple input files.

    -s, --structure *display | link*
        Structure display control: display structures in a table column or
        set up a link for each structure which opens up a new HTML page
        containing structure and other appropriate information. Possible
        values: *display or link*. Default value: *display*

    --strlinkmode *plain | shaded*
        Specify how to display compound HTML page: plain or background of
        data field field labels is filled with a specified color. Possible
        values: *plain or shad*. Default value: *plane*.

        Structure viewer background color is white. Use --strviewerparams
        option to change default behavior of structure viewers.

    --strlinknavigation *yes | no*
        Display navigation links to other compounds in compound HTML page.
        Possible values: *yes or no*. Default value: *yes*.

    --strlinkshadecolor *"#RRGGBB"*
        This value is --strlinkmode specific. For *shade* value of
        --strlinkmode option, it represents colors used to fill background
        of data field labels.

        Default value: *"#e0e9eb"* - it's a very light blue color.

    --strlinktitle *string*
        Title for compound HTML page. Default value: *Compound Summary*.

    --strlinktitledisplay *yes | no*
        Display title for compound HTML page. Possible values: *yes or no*.
        Default value: *no*.

    --strlinktype *href | button*
        Type of structure link. Possible values: *href or button*. Default:
        *href*.

    --strviewertype *Chem3DActiveX | ChemDrawActiveX | ChemDrawPlugIn |
    Chime | JME | Jmol | MarvinView | ViewerActiveX*
        Structure viewer supported for viewing structures. Possible values:
        *Chem3DActiveX, ChemDrawActiveX, ChemDrawPlugIn, Chime, JME, Jmol,
        MarvinView, or ViewerActiveX*. Default value: *Jmol*.

        Assuming you have access to one of these viewers on your machine,
        you are all set to use this script. Otherwise, visit one of these
        web sites to download and install your favorite viewer:

            accelrys.com: Viewer ActiveX 5.0
            cambridgesoft.com: Chem3DActiveX 8.0, ChemDrawActiveX 8.0,
                               ChemDrawPlugIn
            chemaxon.com: MarvinView applet
            mdli.com: Chime plug-in
            jmol.sourceforge.net: JmolApplet V10
            molinspiration.com: JME applet

        The default viewer, JmolApplet V10, is distributed with
        MayaChemTools package. Earlier versions of JmolApplet are not
        supported: due to applet security issues related to reading files,
        this script uses in-line loading of MOL files and this option
        doesn't exist in earlier version of JmolApplet.

    --strviewerconfig *codebase[,archive,code]*
        Configuration information for structure viewers. This option is only
        valid for structure viewers which are applets: Jmol, JME and
        MarvinView. For other viewer types available via --strviewertype
        option - MDL Chime, ChemDrawActiveX, ChemDrawPlugIn, and
        Chem3DActiveX - this value is ignored.

        Input text format: *codebase[,archive,code]*. For an applet viewer,
        *codebase* must be specified; *archive* and *code* values are
        optional. Here are default *archive* and *codebase* values for
        various applets: Jmol - JmolApplet, JmolApplet.jar; JME - JME,
        JME.jar; MarvinView: MView, marvin.jar

        For local deployment of HTML files, *codebase* must correspond to a
        complete path to the local directory containing appropriate
        *archive* file and the complete path is converted into appropriate
        relative path during generation of HTML files.

        By default, *codebase* value of <this script dir>/../lib/Jmol is
        used for *Jmol* applet viewer, and HTML file(s) are generated for
        local deployment; however, you can specify any supported applet
        viewer and generate HTML file(s) for deploying on a web server.

        For deploying the HTML file(s) on a web server, specify a valid
        *codebase* directory name relative to <WWWRootDir>. Example when JME
        archive file, JME.jar, is available in */jme* directory on the web
        server:

            /jme

        For local deployment of HTML file(s), specify a complete *codebase*
        directory name. Example when JmolApplet archive file,
        JmolApplet.jar, is present in <JMOLROOT> directory:

            <JMOLROOT>

        In addition to *codebase*, you can also specify *archive* file name.
        Example for web deployment:

            "/jme,JME.jar"
            "/jme"

        Example for local deployment:

            "<JMEROOT>,JME.jar"
            "<JMEROOT>"

    --strviewerparams *"name=value [name=value ...]"*
        Parameters name and value pairs for structure viewers. These name
        and value pairs are used to control the appearance and behavior of
        structure viewers in tables and compound HTML page during *link*
        value for -s --structure option.

        The parameter names, along with their values, are just passed to
        each structure viewer in appropriate format without checking their
        validity. Check documentation of appropriate structure viewers to
        figure out valid parameter names.

        Input text format: *name=value name=value ...* Example:

            "width=250 height=170"

        Default for all structure viewers: *width=250 height=170* for
        displaying structures in tables, and *strlinkwidth=500
        strlinkheight=295* for compound HTML page during *link* value for -s
        --structure option.

        Default background color for all structure viewers: same as
        --shadecolor value for displaying structures in tables and
        *strlinkbgcolor=#ffffff* for compound HTML page; however, explicit
        specification of background color in this option overrides default
        value. To use black background for structures in tables and compound
        HTML page, specify *bgcolor=#000000* and *strlinkbgcolor=#000000*
        respectively. Keep this in mind: Some structure viewers don't appear
        to support background color parameter.

        Additional structure viewer specific default values:

            Chem3DActiveX: "displaytype=Ball&Stick rotationbars=false
                            moviecontroller=false"
            ChemDrawActiveX: "ViewOnly=1 ShrinkToFit=1 ShowToolsWhenVisible=1"
            ChemDrawPlugIn: "type=chemical/x-mdl-molfile ViewOnly=1
                             ShrinkToFit=1 ShowToolsWhenVisible=1"
            Chime: "display2d=true"
            JME: "options=depict"
            Jmol: "progressbar=true progresscolor=#0000ff boxbgcolor=#000000
                   boxfgcolor=#ffffff script="select *; set frank off;
                   wireframe on; spacefill off""
            MarvinView: "navmode=zoom"
            ViewerActiveX:"Mouse=4 Convert2Dto3D=0"

        Try overriding default values or specify additional valid
        parameter/value pairs to get desired results. Example for using CPK
        rendering scheme with Jmol viewer:

            "script="select *; set frank off; wireframe off; spacefill on""

    --strviewerembed *direct | javascript*
        Specify how to embed structure viewers in HTML pages. Possible
        values: *direct* - use applet/object tags to emded structure viewer;
        *javascript* - use vendor supplied java scripts. Default value:
        direct.

        This option only applies to these vieweres: *Chem3DActiveX,
        ChemDrawActiveX, ChemDrawPlugIn, Jmol, and MarvinView*.

        For marvin.js to work correctly on your browser, you may need to set
        *marvin_jvm=builtin* or *marvin_jvm=plugin* using --strviewerparams
        option. Additionally, MarvinView - at least in my hands - also has
        problems during usage of JavaScript for local deployment; however,
        it does work via web server.

        As far as I can tell, Jmol.js supplied with Jmol10 release has these
        issues: jmolSetAppletColor doesn't support background color;
        jmolInitialize disables relative specification of codebase directroy
        which works okay. So, use Jmol.js supplied with MayaChemTools.

    --strviewerjsfile *java script file name*
        Name of vendor supplied java script file. Default values:
        Chem3DActiveX: *chem3d.js*; ChemDrawActiveX, and ChemDrawPlugIn:
        *chemdraw.js*; Jmol: *Jmol.js*, MarvinView: *marvin.js*.

        Directory location for these files is specified via *codebase* value
        of --strviewerconfig option.

    --strtablesize *"numrows,numcols"*
        This option is only valid for *structuresonly* and
        *shadedstructuresonly* modes. And it indicates maximum number of
        rows and columns per structure table. Default value:*6,4*.

    --stylesheet *old | new | none*
        Controls usage of stylesheet for newly generated HTML file(s).
        Possible values: *old, new, or none*. Default value: *new*.

        Stylesheet file contains various properties which control appearance
        of HTML pages: type, size, and color of fonts; background color; and
        so on.

        For *old* value, an existing stylesheet file specified by
        --stylesheetname option is used for each HTML file; no new
        stylesheet file is created. This option is quite handy for deploying
        HTML file(s) on a web server: assuming you specify a valid
        stylesheet file location relative to your WWWRoot, a reference to
        this stylesheet is added to each HTML file. For local deployment of
        HTML file(s), a complete path to a local stylesheet is fine as well.

        For *create* value, a new stylesheet is created and reference to
        this local stylesheet is added to each HTML file. Use option
        --stylesheetname to specify name.

        For *none* value, stylesheet usage is completely ignored.

    --stylesheetname *filename*
        Stylesheet file name to be used in conjunction with -s --stylesheet
        option. It is only valid for *old* value of -s --stylesheet option.
        Specify a valid stylesheet file location relative to your WWWRoot
        and a reference to this stylesheet is added to each HTML file.
        Example: *"/stylesheets/MyStyleSheet.css"*. Or a complete path name
        to a local stylesheet file.

        For *create* value of -s --stylesheet option, a new stylesheet file
        is created using -r --root option. And value of --stylesheetname is
        simply ignored.

    --shadecolor *"#RRGGBB,#RRGGBB"*
        Colors used to fill background of rows during *shade* and
        *shadedhightlight* mode represented as a pair of hexadecimal string;
        the first and second color values are used for odd and even number
        rows respectively.

        Default value: *"#ffffff,#e0e9eb"* - it's white and very light blue
        for odd and even number rows.

    -t, --title *string*
        Title for HTML table(s). Default value: *SDFileName*. This option is
        ignored for multiple input files. And -r --root option is used to
        generate appropriate titles.

    --titledisplay *yes | no*
        Display title for HTML table(s). Possible values: *yes or no*.
        Default value: *yes*.

    -w, --workingdir *dirname*
        Location of working directory. Default: current directory.

EXAMPLES
    HTML table file(s), containing structures, can be used in two different
    ways: browsing on a local machine or deployment via a web server. By
    default, HTML file(s) are created for viewing on a local machine using
    Jmol viewer through a browser; however, you can specify any supported
    applet viewer and generate HTML file(s) for deploying on a web server.

    First two sets of examples show generation of HTML file(s) using
    different applet viewers and a variety of options for local browsing;
    last set deals with web deployment.

    Local deployment: Usage of default JMol viewer distributed with
    MayaChemTools:

    To generate HTML tables with structure display using JMol viewer, rows
    background filled with white and light blue colors, navigation links on
    top and botton of each page, type:

        % SDFilesToHTML.pl -o Sample1.sdf

    To generate HTML tables with structure display using JMol viewer, rows
    background filled with white and light blue colors, navigation links on
    top and botton of each page, and only containing MolWeight and Mol_ID SD
    data fields, type:

        % SDFilesToHTML.pl --datafields "MolWeight,Mol_ID" -o Sample1.sdf

    To generate HTML tables with CPK structure display using JMol viewer,
    rows background filled with white and light blue colors, navigation
    links on top and botton of each page, type:

        % SDFilesToHTML.pl --strviewerparams "script=\"select *; set frank off;
          wireframe off; spacefill on\"" -o Sample1.sdf

    To generate HTML tables with structure display using JMol viewer and
    black background, rows background filled with light golden and greyish
    colors, navigation links on top and botton of each page, 10 rows in each
    table, greyish header row color, and cell spacing of 1, type:

        % SDFilesToHTML.pl -o -n 10 --headeralign "center" --headercolor
          "#a1a1a1" --shadecolor "#fafad2,#d1d1d1" --cellspacing 1
          --strviewerparams "bgcolor=#000000" Sample1.sdf

    To highlight molecular weight values using specified highlight criteria
    and fill in default background colors, type:

        % SDFilesToHTML.pl -n 10 --highlight "MolWeight,numeric,le,450"
          --highlightstyle background -m shadedhighlight -o Sample1.sdf

    To highlight molecular weight values using specified highlight criteria,
    color the text using default colors, and add a footer message in every
    page, type:

        % SDFilesToHTML.pl -n 4 --highlight "MolWeight,numeric,le,500"
          --highlightstyle text -m shadedhighlight -o
          --footer "Copyright (C) MayaChemTools" --cellspacing 1 Sample1.sdf

    To generate tables containing only structures, type:

        % SDFilesToHTML.pl -d both -m shadedstructuresonly --strtablesize "6,4"
          --cellspacing 1 -b 1 -o Sample1.sdf

    To generate tables containing only structures with molecular weight
    displayed above the structure, type:

        % SDFilesToHTML.pl -d both -m shadedstructuresonly --strtablesize "6,4"
          --cmpddatafield "MolWeight,no,top,center"  --cellspacing 1 -b 1
          -o Sample1.sdf

    To generate tables containing links to structures and highlight
    molecular weight data field values using specified highlight criteria ,
    type:

        % SDFilesToHTML.pl -n 4 --footer "Copyright (C) MayaChemTools"
          --highlight "MolWeight,numeric,le,450" --highlightstyle background
          -d both -m shadedhighlight  -s link --strlinktype button
          -o Sample1.sdf

    Local deployment: Usage of other structure viewers:

        % SDFilesToHTML.pl --strviewertype MarvinView --strviewerconfig
          "<Marvin dir path>" -o Sample1.sdf

        % SDFilesToHTML.pl -o -n 10 --headeralign "center" --headercolor
          "#a1a1a1" --shadecolor "#fafad2,#d1d1d1" --cellspacing 1
          --strviewerparams "bgcolor=#000000" --strviewertype Chime
          Sample1.sdf

        % SDFilesToHTML.pl -n 10 --highlight "MolWeight,numeric,le,450"
          --highlightstyle background -m shadedhighlight --strviewertype
          Chime -o Sample1.sdf

        % SDFilesToHTML.pl -d both -m shadedstructuresonly --strtablesize "6,4"
          --cellspacing 1 -b 1 -strviewertype JME -strviewerconfig "<JME dir
          path>" -o Sample1.sdf

    Web deployment: Usage of different structure viewers and options:

    For deploying HTML file(s) on a web server, specify a valid *codebase*
    directory name relative to <WWWRootDir>. In addition to *codebase*, you
    can also specify *archive* file name.

        % SDFilesToHTML.pl -m plain -s display --strviewertype Jmol
          -strviewerconfig "/jmol" -n 5 -d both -r PlainTable -t "Example
          using Jmol: Plain Table" -o Sample1.sdf

        % SDFilesToHTML.pl -n 5 -m shade  -s display -strviewertype JME
          -strviewerconfig "/jme,JME.jar" -r ShadeTable -t "Example using JME:
          Shaded Table" -o Sample.sdf

        % SDFilesToHTML.pl -n 5 --highlight "MolWeight,numeric,le,450"
          --highlightstyle background  -d both -m shadedhighlight  -s display
          -strviewertype MarvinView -strviewerconfig "/marvin" -r
          ShadedHightlightTable -t "Example using MarvinView: Shaded and
          Highlighted Table" -o Sample.sdf

        % SDFilesToHTML.pl -n 4 --highlight "MolWeight,numeric,le,450" -s link
          --strlinktype href --strviewertype ChemDrawPlugIn  --highlightstyle
          background -m shadedhighlight -t "Example using ChemDrawPlugIn:
          Shaded and Highlighted Table" -r ShadedHightlightTable -o Sample1.sdf

AUTHOR
    Manish Sud <[e-mail]>

SEE ALSO
    FilterSDFiles.pl, InfoSDFiles.pl, SplitSDFiles.pl,
    MergeTextFilesWithSD.pl

COPYRIGHT
    Copyright (C) 2015 Manish Sud. All rights reserved.

    This file is part of MayaChemTools.

    MayaChemTools is free software; you can redistribute it and/or modify it
    under the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation; either version 3 of the License, or (at
    your option) any later version.