report create

report create ?attribute value?...

report create dict

Report(?attribute,value?,...)

Report(dict)

Report(attribute=value,...)

Report.Create(?attribute,value?,...)

Report.Create(dict)

Report.Create(attribute=value,...)

Create a new report object. Additionally, an set of attributes of the object may be defined in the same statement. The settable attributes are the same as in the report set command.

The command returns the handle or reference of the new report object.

report delete

report delete ?rhandle?...

report delete all

r.delete()

Report.Delete(?rhandle/rref?,...)

Report.Delete(“all”)

Delete one of more report objects which are identified by their handles or references. The second variant deletes all currently defined report objects.

Example:

report delete {*}[report list]

This command is equivalent to report delete all .

report extract

report extract rhandle pdf_filename ?mode? ?outfilenamenbase?

r.extract(filename=,?mode=?,?outfilenamebase=?)

Extract the SQLITE database and the report style XML file from a PDF report.

The default mode is all, meaning that both the database and the formatting information is extracted, written to external files, and attached to the report object. Other supported modes are style (formatting only) and database (data only).

The final optional argument sets the base filename of the extracted SQLITE and XML style files. If it is not set, a file name is automatically generated.

The return value of the command depends on the extraction mode. In the all mode, is is a list of the respective filenames for the database and style file. In other modes, it is a single string with the specific filename.

report get

report get rhandle attribute

r.get(attribute)

r.attribute

r[attribute]

Query an attribute of a report object. The currently supported attributes are:

• address_city
  The city part of the author contact address.
• address_country
  The country part of the author contact address, following the ISO3166 standard.
• address_state
  The state part of the author contact address. Empty if not applicable.
• address_street
  The street address part of the author contact address. Includes floor, house number, etc.
• address_zip
  The ZIP code or other applicable postal code of the author contact address.
• affiliation
  The institution the author of the report works for.
• affiliationduns
  The DUNS registration ID of the affiliated institution. This is primarily useful for US government projects.
• affiliationurl
  The URL of the affiliated institution.
• author
  The author of the report, as free-form text.
• authorurl
  A URL with information on the author, or an empty string if unset.
• border
  The distance between the paper or HTML page and the first elements of a data box.
• boundingbox
  A list of the upper left x/y and lower right x/y coordinates of the current layout, with all scaling and offset computations applied. This is a read-only attribute.
• category
  A category string to be used if the report definition is stored in a repository.
• classuuid
  The base class UUID of this report.
• comment
  A free-form comment.
• date
  The date of the last change of the report.
• dbfields
  A nested list of the columns defined for the embedded structure and reaction database. Each field is reported as a list of the property or pseudo-property name of the field, the true database column name, a bitset set of any database field attributes set on the field (from the bit set of none , index , unique , notnull , nocompute ), the name of the SQLITE database type used to encode the field, and the field length, which is zero if it is not defined.

If database fields have not yet been defined on the report object, querying or setting this attribute instantiates a standard set for a structure (but not reaction) database. Additionally, all properties currently associated with a data display field in the layout are automatically added, so that every visible data value can also be read from the database.

When setting this attribute, every field sublist must contain only between one and three elements. The last two items reported are automatically deduced from the type of data to be stored. If no explicit field name is specified, the field name is copied from the first argument. If no third element is supplied, the database column has no auxiliary SQL attributes, i.e. it is not indexed, may contain multiple entries of the same value, can be NULL , and an attempt will be made to compute its value when a structure or reaction record is written and the ensemble or reaction does not currently hold a value for the property or pseudo-property of the database column.

• dbfilename
  The name of the SQLITE database file with the structure- and data-searchable content associated with this report object. It can also be set, though usually its name is auto-generated. Initially, an empty return value indicates that no file name has been set.
• doi
  A digital object identifier for the report, if defined.
• email
  An email contact address of the author.
• eolchars
  The end-of-line character to use in ASCII -formatted output, such as the HTML report style. The default value is the platform style (Windows, Mac or Unix/Linux). It can be set to any string. Additionally, the magic values win (or crlf), mac (or cr ) and linux (or unix , or lf ) are recognized.
• footer
  The center-aligned page footer text, which can contain placeholders. The default is an empty string.
• handle
  The Tcl handle in string format
• header
  The center-aligned page header text, which can contain placeholders. The default is an empty string.
• htmlfilename
  The name of the file with the HTML -formatted rendering of the report content. Usually, this is automatically set. The initial value is an empty string, which results in an automatically generated name if a HTML file is written.
• infourl
  A URL with information on the report, or an empty string if unset.
• keywords
  A list of keywords associated with the report
• leftfooter
  The left-aligned page footer text, which can contain placeholders. The default is an empty string.
• leftheader
  The left-aligned page header text, which can contain placeholders. The default is an empty string.
• versionuuid
  The instance UUID associated with this report
• license
  The license class associated with this report. Setting the license to a standard type updates the associated URL with a standard location.
• licenseurl
  A URL with details about the report license.
• literature
  This is a free-form string for a literature reference describing the meaning and/or algorithm behind the report.
• maxpages
  The maximum number of pages to write, in PDF or HTML format. If the current data set is too large to fit into this number of pages, the rest is silently omitted. A negative value, which is the default, allows an unlimited number of pages. In any case, the maximum page count of a PDF report is 9999 pages. This is due to a limitation in the PDF rendering library.
• maxrecs
  The maximum number of records to write, which is the same as the number of top-level data boxes. The actual size of the dataset or structure file used as data source for the report may be larger, if a filtering mechanism, such as selection processing, is set. Records in excess of the maximum are silently omitted. A negative value, which is the default, allows an unlimited number of records.
• name
  The primary name of the report.
• orcid
  The ORCID code of the author of the report (see www.orcid.org).
• orientation
  The page orientation, which can either be portrait (the default) or landscape .
• ownerpassword
  The owner password for generated PDF files. An empty string, which is the default, indicates that no password is set. For HTML output, this attribute is ignored.
• paper
  The size of paper, such as A4, A3 or letter, which is used to format the output as PDF or HTML . This parameter has an effect even on HTML output, since the code contains page breaks for nice printing. The default is the toolkit default paper, which itself is usually A4 or letter.
• path
  The repository path for displaying hierarchical repository trees. This attribute is independent of any file system paths.
• pdffilename
  The name of the file with the PDF -formatted rendering of the report content. Usually, this is automatically set. The initial value is an empty string, which results in an automatically generated name if a PDF file is written.
• phone
  A contact phone number of the author.
• references
  Cross references of the report. This is a nested list of class UUID s and reference type tags.
• regid
  For registered reports, the registration ID. Unregistered modules report zero.
• rightfooter
  The right-aligned page footer text, which can contain placeholders. The default is an empty string.
• rightheader
  The right-aligned page header text, which can contain placeholders. The default is an empty string.
• scale
  A scaling factor to convert the 72-DPI internal coordinates to print coordinates. The default scale is 1.0. If set, the magic value # auto is also recognized, which sets the scaling factor so that the configured number of horizontal and vertical blocks with the current style file just fit onto the configured paper type. Please refer also to the interacting xblocks and yblocks attributes. Automatic setting of this attribute is only possible if a style file has been read, because it requires the box layout data.
• spacing
  The number of pixels between top-level data boxes if more than one is stacked in x or y direction. The default spacing is 1.
• styledata
  The contents of the current style file, in original XML formatting. This data can be set either directly as a string, or indirectly via the stylefilename attribute. If set directly, the stylefilename attribute is reset.
• stylefilename
  The name of the XML file with report render style information. Its initial value is an empty string. If this attribute is set, the file contents are parsed and stored internally. The file contest are then available as in the styledata attribute.
• title
  The title of the report as a free-form string. In HTML reports, it is used as page title. In PDF , it is part of the document metadata.
• userpassword
  The user password for PDF documents. By default, it is an empty string, which means that no password is set. For HTML output, the attribute is ignored.
• version
  A version string
• versionuuid
  The version UUID associated with this report version.
• xblocks
  The number of top-level data boxes to arrange in horizontal direction on a document page. When it is set, the magic words # auto is recognized, which computes the maximum number of boxes which can be placed without overspill on the page using the current border, spacing and scaled top-level box size. Please refer also to the interacting scale attribute. Automatic setting of this attribute is only possible if a style file has been read, because it requires the box layout data.
• yblocks
  The number of top-level data boxes to arrange in vertical direction on a document page. When it is set, the magic words # auto is recognized, which computes the maximum number of boxes which can be placed without overspill on the page using the current border, spacing and scaled top-level box size. Please refer also to the interacting scale attribute. Automatic setting of this attribute is only possible if a style file has been read, because it requires the box layout data.

report list

report list ?pattern?

Report.List(?pattern=?)

Return the handles of all currently defined report objects. The handles may optionally be filtered by a standard Tcl string match condition.

report read

report read rhandle pdf/db/html_filename ?dataset?

r.read(filename=,?target=?)

Read data for a report from a PDF file with an embedded database, a SQLITE database with the property structure (typically extracted from a report PDF ) or a HTML file generated by the report command with embedded data.

If an existing destination dataset is specified, all read structure or reaction objects are put into that dataset. A new dataset is automatically created if the argument is omitted, specified as an empty string (including None for Python ), or as the magic name #new.

The return value is the handle or reference of the dataset holding the extracted chemistry objects.

report ref

Report.Ref(identifier)

Python -only method to get a reference of the report object from its handle.

report set

report set rhandle ?attribute value?...

report set rhandle dict

r.set(?attribute,value?,...)

r.set(dict)

r.attribute = value

r[attribute] = value

Set attributes of the report object. The attributes are explained in the section on the report get command.

Example:

report set $rhandle stylefile „mystyle.xml“ paper A4 xblocks 2 yblocks #auto \	scale #auto

This is a typical page set-up operation. The PDF or HTML form of the report will contain 2 top-level boxes arranged horizontally, a suitable (as computed from the aspect ratio of the paper) number of vertically stacked blocks, and everything scaled so that either the horizontal or vertical extent of the block stacks, plus the border, just fit onto the selected paper, without overspill.

report subcommands

report subcommands

dir(Report)

Return a list of all subcommands of report objects. The command does not have any parameters.

report write

report write rhandle ?filename? ?source? ?flagdict?

report write rhandle ?filename? ?source? ?flagname flagvalue?...

r.write(?filename=?,?source=?,?flags=?)

Write a report file from the existing report definition and a structure data source.

The file name specifies an output data file. Its type is initially inferred by the filename suffix - .pdf for PDF files, . htm or .html for HTML files, and .db or . sqlite for a raw SQLITE database. The file name can be omitted if the pdffilename attribute is set, and the output format should be PDF , or another format is set in the flags argument and the corresponding format-specific filename attribute is set. If an explicit format is specified in the flags argument, the automatic format selection from the filename is overridden. The filename can also be a directory. In that case, an automatically generated file name based on the report instance UUID is constructed and the file written to that directory. The magic output file names stdout and stderr are also recognized.

The structure data source can either be the handle or reference of a dataset with structure or reaction objects, or the handle (reference) of an open molfile structure or reaction file. If no structure object data source is specified, but there is a current SQLITE database file associated with the report object, data is read from that database.

The output flags can be from the following set:

• format The desired output format. It can be pdf , html ( htm ) or db ( sqlite ).
• maxrecs The maximum number of structure objects or structure input file records to process.
• page A page or page range. Pages outside the range for which data exists are omitted.
• reusedb A boolean flag indicating whether an existing SQLITE database file should be re-used.
• selection The method to pick structures or reactions for inclusion in the report. It can be ignore (all dataset items or file records are reported), filter (only items passing a filter are included in the report) or highlight (only items where the highlight attribute is set are included).

The return value of the command is the output file name, which may have been auto-generated.