Thin Section Report User Guide and Technical Notes
Peter Blum, 7 July 2016

1. Introduction

Detailed observations on thin sections are entered in a DESClogik workbook typically named "###_microscopic" (where ### is the expedition number, i.e. 396-U1565A_microscopic). The workbook has typically multiple tabs, or worksheets, one for each set of related attributes (e.g., primary mineralogy, alteration, structures). In these worksheets, a thin section description is represented by one row, or by multiple rows if multiple domains are described. This workbook format is best suited to describe and analyze data from many thin sections. However, when reviewing all aspects of one single thin section, a form type summaries of all pertinent information on 1-3 report pages is often more convenient. We therefore created a tool set that allows trained staff members to define a form report layout based on the observation workbook, and rapid production of PDF form summaries for the thin sections.
The following is the thin section report protocol approved by JRSO management on 16 June 2015:

• Thin section describers provide digital records of their observations in the form of a DESClogik/Excel spreadsheet.
• Science party agrees on the subset of information from the spreadsheet to be presented in a TS form report. The agreed upon layout is configured by DESC support personnel using the TS Report Builder tool.
• The TS forms are generated as PDF files during the cruise, using the TS Report Writer tool, and are reviewed and finalized by the end of the editorial postcruise meeting. Scientists may be given access to TS Report Writer, or DESC support personnel may take care of generating the reports.
• After the editorial postcruise meeting, the final TS forms are merged into one PDF file per hole and loaded to the database as DESC assets by DESC support personnel, along with the observation workbooks from DESClogik. The final reports are then passed on to the Pubs representative for publication in the Proceedings. 
• DESC support personnel ensure that the final TS report definition for each expedition (JSON file) is backed up for future use.

This user guide is organized as a tutorial aimed mainly at the support personnel who construct the report layout and refine it iteratively based on the project scientists' feedback. It contains the following three chapters.

• Chapter 2 explains the data source workbook and its specific requirements.
• Chapter 3 explains the Thin Section Report Writer ("Writer") used to print batches of reports as defined by the Builder and using a matching data source workbook. Scientists can run this tool with minimal instructions or defer to JRSO personnel. The Writer is explained before the Builder because it is used iteratively while building a report definition.
• Chapter 4 explains the Thin Section Report Builder ("Builder") used to create the report layout with links to the data source workbook. The user is guided through every detail using an abstracted data source workbook. A real example definition and data source workbook are also provided. 2. Data source workbooks

2. Spreadsheet requirements

Workbook, worksheet and column names

The data source workbook must be identified in the Builder before report definition can begin so all report elements can refer to the correct workbook, worksheet and column names. If you change any of those names during the iterative development of the report definition, you may get error messages because the Builder cannot find the data source names ("orphan element" names in the Builder will be flagged yellow).
The source workbook must also be identified in the Writer, along with the report definition and a directory location for the reports, before it can be run. If the worksheet or column names used in the Builder don't exist in the selected data source file, the reports will not be written correctly or not at all.
It is therefore most helpful if the workbook file, worksheet and column names are firmly defined before you start defining a report, otherwise you will go through iterations of repairing the report definition in the Builder.

Identity source column

Each worksheet must have one column that will be flagged as the identity source column in the Builder (see below). For all practical purposes, this is the first column in each data source worksheet containing the sample names (see General concept and purpose section). The Writer then knows where to find the identifying sample name to assemble data from multiple worksheets.

Control tab (worksheet)

Each data source workbook needs to have one data source worksheet (tab) identified as the control tab. In this tab, each sample name (in the identity source column) must only occur once. The Writer then knows which samples to look for in the other data source worksheets (tabs), where sample names may be repeated in multiple rows (case of multiple description domains). A description interval, represented by the thin section sample in this case, can have multiple description domains, defined as areas or volumes within a sample or interval that cannot be strictly defined by clear boundaries but rather are characterized by a particular appearance such as color or texture.

Training data source workbook

Although these programs were written specifically to generate PDF thin section reports from Excel thin section description workbooks, they can be used to create PDF reports for any Excel workbook as long as the general concept and purpose apply. The training data source workbook used throughout this guide (look for file ts_report_training_data.xlsx) is an abstracted version of a thin section data workbook which should both simplify the learning process and demonstrate the generic applicability of the programs.
The training workbook as the following worksheets:

• worksheet1: used for the simple report, including images
• worksheet2: used to create a simple multi-worksheet
• worksheet3: used to demonstrate the multi-domain report trickery.
• image index: library of image ASMAN IDs that need to be copy-pasted into worksheet1, columns 2 and 3, depending on situation.

Double-click the icon below to get the training workbook and save it to your disk. You need to load it in the Builder and Writer applications.

3. TS Report Writer

Getting ready

The Writer is a Java program downloaded from a link found on JRSO web pages.

• In the SHIP Production environment, go to this link and download the app:
• http://web.ship.iodp.tamu.edu/tasapps/thsreport/jnlp/THSReport.jnlp
• In the SHORE Production environment, go to this link and download the app:
• http://web.iodp.tamu.edu/tasapps/thsreport/jnlp/THSReport.jnlp
• Follow your browser's instruction to install the application from the JNLP file.
• Click the Run button.
• Login as guest/guest (Fig. 3.1.).

Figure 3.1. Writer login window

Print a batch of reports for an existing report definition:

After login, you are presented with a list of all existing report version that have a report status of open (O) or locked (L) and a version status of active (A) or released (R) (see Fig. l.3.2; more on report and version status later).

Figure 3.2. Writer window after login.

To print a batch:

• Select the appropriate report definition.
• Here, select TRAINING_REPORT with the latest version number.
• Browse to the appropriate data source Excel workbook using the Find SpreadSheet button. This should be the workbook that was used for the report definition as far as worksheet names and column names are concerned. Data may have changed.
• Here, select the ts_report_training workbook from wherever you placed it.
• Using the Report Destination button, select a folder where the report files will be written to
• Click the Validate button and the program will check if all names used in the report definition also exist in the data source workbook (and a few other things). You will get an error messages if the validation fails and have to resolve the issue.
• If the validation succeeds, the Create Reports button becomes active – click it to print the reports.
• A progress bar and counter will inform you of the progress.

While building a report definition, you want to print reports iteratively whenever you want to check what your latest creation looks like:

• Switch from the Builder to the Writer application
• Click the Refresh Report Table button to add your latest saved version(s) to the list.
• Select the latest version.
• If you want to preserve the previous report versions, create and select a new folder and select it using the Report Destination button. However, more commonly you just want to overwrite the previous reports and you have to do nothing to achieve that.
• Click the Validate button, then the Create Reports button.

4. Thin Section Report Builder

4.1. How to use this chapter

This chapter is organized as a tutorial that a first-time user can work through from top to bottom to learn how to build thin section report definitions.
Section 4.2 introduces the Front Panel used to manage reports.
Section 4.3 builds a simple report from one data source sheet, using all available report layout elements (block, field, text, grid, table) and explaining them in detail,. Included here is the topic of printing thin section images using the field element.
Section 4.4 describes issues relevant when using multiple data source worksheets.
Section 4.5 describes best practices when using data sheets with multiple sample/interval domains (multiple rows in data source worksheets for a single report).

4.2. Getting ready

The Thin Section Report Builder is a browser-based application. The links are:

• SHIP: http://web.ship.iodp.tamu.edu/RDB/
• SHORE: http://web.iodp.tamu.edu/RDB/

When you launch the application, you first get the login screen (Fig. 4.2.1).

• Enter your credentials.
• Click the Login button.

Figure 4.2.1. Login window to Builder application.

Two types of user roles exist: Manager and Editor. Your account is given one or both by the system administrator and the type of authorization determines what you will see and be able to do. Most of the relatively few users are authorized for both roles.

4.3. Select or create a report to work with

Initial front panel

After you logged in, you initially see two of the four functional areas of the Front Panel (Fig. 4.3.1.).

• Top bar for user id and logout.
• Search area with multiple search options that combine to display a list of selected report versions.

Figure 4.3.1. Initial front panel.

First you want to view a list of reports to operate on, which requires you to understand the relatively powerful but not so intuitive search options. Then you'll use the other two functional areas:

• Report list area, displaying the search result and allowing user to select a version for action.
• Action button menus on left-hand side, with two menus for Editor and Manager roles.

Report search options

Combination searches

The combination of four search arguments (along with the user role authorization) determines the report versions a user can see in the report list area:

• (Part of) a Report Name AND
• Owner AND
• Report Status AND
• Version Status

Report status and Versions Status each always have one of four options selected and understanding these options and their combinations is critical (see below and Table 1). If you don't make any selection and click the Search button, the default display is all Open only reports and Active only versions from any owner, in reversed alphabetical order to display the more recent expeditions farther up on the list (Fig. 4.2.3).

Figure 4.3.2. Main screen listing selected reports.

So what exactly are all those report and version status options?

Report status options

• Open only: Lists only reports that the Editor role can edit (or clone or export).
• Locked only: Lists only reports that only an Editor who also is an owner can edit (or clone or export).
• Canceled only: Lists only reports that are canceled and only Manager role can see and potentially activate or purge. Editor role alone cannot see any version of the report.
• All report status: All open, locked and canceled reports are listed, limited only by the authorized user role.

Version status options

• Released only: Lists only report versions that Guest role can see in the Writer and use to print reports.
• Active only: Lists only report versions that Editor role can edit (or clone or export).
• Canceled only: Lists only report versions that only Manager role can see and potentially activate or release.
• All version status: All released, active and canceled versions are listed.

Table 1. Common applications of report and version status search combinations.

Editor menu

The Editor action menu is available if user is an authorized editor (Fig. 4.3.3., left-hand side).

• Edit report
• Clone Report: This is the most commonly used way of renaming or becoming owner of an existing report version.
• Create New Report: If you really want to start a new report from scratch.
• Export Definition: Option if you want to save an existing definition for use outside your environment for some reason. Exporting report definitions typically prints the JSON type definition into a new browser page.
• Copy-paste the content into a text editor and save as text.
• If necessary, add a file name extension "txt".
• Known issue:
• Many programs or operating systems do not understand the extension "JSON". If you don't get a new browser page with export
• In Firefox Preferences, Content/Pop-Ups, uncheck "Block pop-up windows
• Import Definition: Option if you want to use an existing external definition in your environment for some reason. Browse report definition file.

Manager menu

The Editor action menu is available if user is an authorized manager (Fig. 4.3.3., right-hand side).

• Version actions
• Release version: Guest can see report in TS Writer.
• Activate version: Bring a canceled version back for editing/use.
• Cancel version: Get the many past versions out of the editor's view.
• Report actions
• Lock report: all versions of a report are locked, i.e., can only be edited by owner.
• Open report: Bring locked reports back to open status.
• Cancel report: Get all versions of a report out of editor's view.
• Rename report: A little-used option to cloning a report version to create a new name.
• Owner change: A little-used option to cloning a report version to become owner.
• Purge report: Irreversibly delete canceled versions of a report:
• If report and all versions are canceled, purge will delete all and the report is gone.
• If report is not canceled, all canceled versions are deleted as long as one version is not canceled.

Figure 4.3.3. Manager and Editor action menus.

4.4. Building a simple report based on one source data worksheet

Getting started

Launch a new report

• On the main screen, click the Create New Report button from the Editor menu.
• Note that you could also select an existing report from the list and click the Clone Report button,
• Enter a name for the report.
• Don't sweat it, you can always change the name by cloning the report later!
• Click the OK button and the new report is added to the report version list on the Front Panel.
• Find your new report on the list, select it by checking the box left to it, and click the Edit button. You are now in the Report Edit window and ready to go (Fig. 4.4.1).

Figure 4.4.1. Report edit window.

Declare data source workbook and worksheets

Before you can add layout elements, you need to make sure the source data worksheets (tabs) are declared:

• On the Report Edit window, click the Browse… button to Select file to upload (Fig. 4.4.1).
• When loaded, the file name will be displayed underneath the Browse… button. Watch out: The report export from Desclogik is a .xlsx-file. For Thin section report writer to accept the file, you have to open the .xlsx file, change the file format to 'Excel 97-2003 workbook/.xls', just renaming the workbook extension won't do the trick.
• On the Report Edit window, click the Declare worksheets button to open the Declare Worksheets window (Fig. 4.4.2).
• On the Declare Worksheets window, a Data source worksheet item with default name "new TAB #" will be displayed and marked in yellow because it needs to be edited. Click the Add button to add as many items as you have worksheets to declare.
• In this section you only need one (the first) worksheet in the training workbook. However, eventually you'll use three so you may as well declare them now.
• Double click the first list item(s), or select it and click the Edit button.
• Select the Source worksheet name from the drop-down list of available worksheets in the source workbook.
• Using the training workbook, select "worksheet1" from the drop down list of all worksheets in the training workbook.
• Set the Identity source column to the column in the data sheet that has the identifying "sample" information (typically the row headers in the data, i.e., the first column).
• Using the training workbook, select the first column "w1samples" from the drop down list of all columns in the worksheet.
• Is this the report control worksheet? Only one worksheet can be the control worksheet and the answer is typically "YES" for the first worksheet, and "NO" for all other worksheets.
• In our training workbook, worksheet1 is the control tab.
• Repeat for all worksheets to declare.
• Using the breadcrumbs, return to the Report Edit window.
• Save your report using the Save to Database button at the top right..

Figure 4.4.2. Declare worksheets window.

Set a footer

The footer will appear on every report page, using a specified data column in the data source workbook (naturally the sample ID) and an automatic "Page # of #" extension.

• On the Report Edit window, click the Edit Footer Text button to open the Footer Edit window (Fig. 4.4.3).
• For the Data source worksheet, you want to select the report control worksheet.
• Using the training workbook, select "worksheet1".
• For the Data source column, select the identity source column.
• Using the training workbook, select "w1samples" the column containing the sample IDs.
• Save your report.

Now you are ready to design the report layout. You could try to print the reports now using instructions in Chapter 3, and find that everything works but you don't get any report because, we'll, you haven't defined any layout items yet.
Figure 4.4.3. Footer edit window.

Adding and configuring layout elements

Architecture of a report

The very high-level view of the architecture of the report definition (Fig. 4.4.4) may help the user grasp the hierarchical relationships of the configurable layout elements:

• Block
• Field
• Text
• Grid
• table.

Figure 4.4.4. Report definitions are structured hierarchical.

Block element

Blocks are containers for the other layout elements (field, text, grid and table). A new block can be placed below, or nested within an existing block, but you cannot place two blocks next to each other on a report page. A block is always placed below the top of an enclosing block, or below the last written item on the page (any layout element), by a top offset (points). Nested blocks can also be positioned by a left offset (points) from their enclosing blocks.
Blocks can have a border box drawn or not. If a border box is specified, the top border is drawn where the top offset was defined, and the first item within the block is written by a fixed amount below the top border (3 points). The bottom border is drawn by a fixed amount (3 points) from the last written item. Left and right borders are drawn with left and right offsets from the enclosing block, by the amount that is set for the left offset.
Drawing borders helps the reader understand the layout and data organization in a larger report. However, printing all borders in the case of nested blocks may result in too many lines. Find the right balance.
Known issue: if you DON'T draw all the borders (boxes) around all blocks, the PDF printing routine currently gets confused and draws borders incorrectly (doesn't know where to start/stop). The program needs to be amended to cover such cases.
At the start of creating a report you must create the first top-level block, all other layout elements must be within a block. Once you have your first block defined, you can add within the block nested blocks, fields, text, grids and tables, which will all be described below. You can also add more top-level blocks below the first block.
A block can display information from one source worksheet only. However, an enclosing block can display information from multiple worksheets if that information is placed within nested blocks. This is very important to understand and will be elaborated later. In this section we only need one block element.

• On the Report Edit window, add a new block by clicking the Add button. A new block entry with default name "new BLOCK #" will be added to the block list and flagged yellow because some parameters must be configured.
• Double click the new list entry, or select it and click the Edit button, to open the Block Edit window (Fig. 4.4.5).
• Enter a Block name (not printed), which is useful in your layout construction but does not appear in the report.
• Using our training report, name it "block1 title".
• Select the Data source worksheet. Each block must have one and only one associated data source worksheet to draw data from.
• For our training report, leave the default "worksheet1".
• Set the Border to "BOX" so you can see what you are doing.
• You can change that if at the end the report appears aesthetically too busy.
• If needed, change the default Left&right offset (points) of 5 (not now).
• If needed, change the default Top offset (points) of 5 (not now).

Now you are ready add fields, text, grids and tables to the block. Note: if you are trying to print the report at this stage you will still not get anything because empty blocks are intentionally programmed not to show.
Figure 4.4.5. Block edit window_Block Left & Right offset needs to be zero or wrapped text will spill over block border._

Field element

The Field element is used (A) to print single values from the data sheet, and (B) to print images stored in the IODP ASMAN asset management system and downloaded on your machine when you run the Writer program.
The important thing to understand about field (and text, see below) layout element is that its location is fixed relative to the enclosing block, i.e., it is not being dynamically stacked below other layout elements the way block, grid and table are. So if you are configuring multiple fields and leave the same default offsets (from enclosing block), they will print on top of each other.
You can place multiple field (and text) elements horizontally next to each other (something you cannot do with block, grid and table elements). However, you have no control in setting the width of the field (or text) element, and the content cannot wrap, which means your content may be cut off at the right margin of the page. All you can control is the top left position of each field (or text) and that, in conjunction with the expected length of the content string, is what you have to manage positioning.
For the two limitations described above, it is recommend that the field element is used sparingly to display general data values (case A), if at all. The grid element is often a better option. However, field is the only layout element that can display images (case B) and that is its principle purpose.

A. Print a simple single value from the data sheet (we use the sample name here)

• From the Report Edit window, double-click the "block1" item to enter Block Edit. (or select the item and click the Edit button).
• From the Select element to add list, select Field, then click the Add button.
• A field item with default name "new FIELD #" will be added to the Layout Elements list.
• Double-click the new Field item to open the Field Edit window (or select the item and click the Edit button).
• For the Data source column, select the attribute column from the source worksheet to be used.
• Remember, the attributes available in this list are from the worksheet associated with the enclosing block.
• Using the training workbook, select "w1samples" here.
• Set Left offset (points) to move the field content to the right relative to the enclosingBlock Left & Right offset needs to be zero or wrapped text will spill over block border block.
• For our training report, set it to 100 points so we can add a text label in front of it.
• Set the Top offset (points) to move the field content down page from top of block.
• For our training report, set it to 0 points.
• Set the Font size (points).
• Set it to 12 for our training report since this is our report title.
• Set the Font style.
• Set it to BOLD for our training report since this is out report title.
• Set the UseMe flag. This should typically be "YES" otherwise the content will not display and unless other content exists below, the entire block will not display.
• Set to "YES" for our training report.
• Set Border. For fields, this is typically set at NONE.
• In our training report, we don't want to draw a box around the title.
• Is this an ASMAN image column? This flag is critically important. If set to "YES", the image process is triggered (see part B).
• For our training report, the answer is "NO" here.
• Therefore, the Image width (40-500 points) is irrelevant here.

Figure 4.4.6. Block edit with first block getting a field layout element.

Figure 4.4.7. Field edit window.

B. Print images

Printing images has some extra requirements:

1. Images must reside in (or originate from) the JRSO asset management system, called ASMAN.
2. User must get the ASMAN IDs of the images and enter them in the data source workbook, where each image to appear in a report must have its own data column. In the DESClogik exported workbooks, we routinely use two columns in the first worksheet of the microscopic workbook for planar and cross-polarized image IDs.
3. When the reports are printed, the Writer must find the images in the database instance that the Writer is operating in, otherwise the reports are not printing. If you have no access to images you need to remove the ASMAN IDs from the data source worksheet to be able to print the other parts of the report.

Other than entering the ASMAN IDs into the data source worksheets, for which we don't have an efficient mechanism or tool other than manual entry at this time, the overall mechanism for printing the images is very effective, in particular when getting the ASAMN IDs on the ship from an ongoing expedition as these will also work in the shore production copies after the cruise. However, if you train in a more ephemeral project or database test instance, you have to be lucky to find some suitable images, and you may have to load some images using a utility program that provides you with the ASMAN ID. In Appendix 3 you find a description how this can be done using DESClogik.
In our training report, we'd like to display two whole thin section images taken with plane and cross-polarized light, respectively, below the title. Because of the positioning limitation of the field layout element described above, it is advisable that you place fields for images into their own block.

• Go back to the Report Edit window and add another top-level block as described in the Block element section.
• Double-click the new item to open the Block Edit window.
• For Block name (not printed), enter "block2 images", and leave the other block parameters the way they are.
• From Select element to add, choose Field and click the Add button.
• Double-click the "Field: new FIELD #" layout item to enter the Field Edit window and configure as follows:
• Data source column = w1image1"
• UseMe flag = "YES" (otherwise the image block will not show!)
• Is this an ASMAN image column = "YES"
• Image width (40-550 points) = 255 (this is an empirical number, about half the width of the total page width of ~510 points).
• Go back to the Block Edit window using the breadcrumbs and add another field for the second image. This time you need to make sure it is positioned optimally relative to the first image in Field Edit:
• Data source column = w1image2"
• Left offset (points) = 265 points to offset the second image to the right.
• UseMe flag = "YES"
• Is this an ASMAN image column = "YES"
• Image width (40-550 points) = 255 (same as first image).

Now it may be good practice to add another two fields underneath the two images, respectively, to print the ASMAN ID themselves as captions. To do that, follow above procedure with the following Field Edit configuration differences:

• Left offset (points) = 265 points to offset the second caption to the right.
• Top offset (points) = 175 points to offset both captions down.
• UseMe flag = "YES"
• Is this an ASMAN image column = "NO"

Text element

The text element is used to print strings of text, such as titles. The important thing to understand about this layout element is that its location is fixed relative to the enclosing block with a top and left offset, i.e., it is not being dynamically stacked below other layout elements, as block, grid and table are. So if you are configuring multiple text elements and leave the same default offsets (from enclosing block), they will print on top of each other.
You can place multiple text elements horizontally next to each other (something you cannot do with block, grid and table elements). However, you have no control in setting the width of the text element; the content will simply wrap at the right page margin.
Another feature to be aware of with text element is that if you create nothing else in a block, the block will not print. Text doesn't have a UseMe flag. This is by design so we can include blocks in layouts with titles (e.g., "Sediment petrography") and if no sediment data exist for that block then the block and title alone will not display.
The text element should be used sparingly – it is often more convenient to use a grid element instead.
Lets use a text element for the title of the report, displaying to the left of the field element we configured for the sample name:

• From the Report Edit window, double-click the "block1 title" item to enter Block Edit (or select the item and click the Edit button).
• From the Select element to add choices, select Text, then click the Add button.
• An item with default name "Text: new TEXT #" will be added to the layout items list.
• Double-click the new Text item to open the Text Edit window and configure as follows for our training report (Fig. 4.4.8.):
• Text to display = "SAMPLE NAME:"
• Left offset (points) = 5 (default).
• Top offset (points) = 0 (same as sample ID field).
• Font size (points) = 12 (same as sample ID field).
• Font style = NORMAL

Figure 4.4.8. Text edit window

This would be a good time to print your report using the Writer application, as described in Chapter 3, to check if everything looks fine. You should see something like the top two blocks in the full training report in Appendix 2.

Grid element

The grid element is used to create tables with fixed numbers of rows and columns, i.e., if one or more values triggers printing (with UseMe flag = "YES"), the entire grid prints (compare with Table, where printing of rows can be suppressed, see below). Grid cells can be filled with fixed text or they can be set to populate with the data in an attribute column in the source sheet.
The grid is a very convenient layout element even for cases where only one or two cells are used per grid element. The big advantage of using a grid vs. a field to display a text line is that the text in the grid wraps, whereas the text in the field runs over.
To set the general grid parameters:

• Add a new top-level block in Report Edit and double-click it to enter the Block Edit window. Configure the block for our training report as follows:
• Block name (not printed) = block3 data1
• Data source worksheet = worksheet1
• Border = BOX
• Then, from the Select element to add choices, select Grid and click the Add button. A new item named "Grid: new GRID #" will be added to the layout elements list.
• Double click the new grid layout item to open the Grid Edit window (Fig. 4.4.9). Configure the basic grid for our training report as follows:
• Grid name (not printed) = "grid1" (for display in layout element list).
• Left offset (points) =5 (default)
• Top offset (points) =5 (default)
• Justification {LEFT, CENTER, RIGHT} = LEFT (this will apply to all cells in the grid).
• Border {NONE, BOX, GRID} = GRID
• Set up the grid cells you want to use with the Add Column and the Add Row buttons.
• For our training report, create 4 columns and 3 rows.
• Set the width of each column approximately such that the total adds up to no more than ~500 points.
• Set all columns to 100 points. You can fine-tune the column width later.

Now you configure each grid cell:

• Double click a cell to open the cell configuration window.
• If you want to display a text string, such as a label for a data field, enter the text into the Text to display in cell field.
• For our training report, enter "Attribute 1 text:" through "Attribute 6 text" into the six cells of columns 1 and 3 (see Fig. 4.4.9.)
• For each cell, you could also change the Font size and Font style; we keep the default values for the training report.
• The UseMe flag has no effect on cells with text. If a grid has only text, nothing will appear. For that reason, the grid is not suitable to print things like block titles.
• Click the Save button after each cell configuration. Text will turn green.
• If you want to display data from the source data sheet associated with the enclosing block, select the Source column from the drop-down list.
• For our training report, select columns "w1attr1" through "w1attr6" for the six cells of columns 2 and 4.
• For each cell, you could also change the Font size and Font style; we keep the default values for the training report.
• Set the UseMe flag to "YES" for at least one cell otherwise nothing will print. The entire grid will be printed if at least one cell that has the flag set to "YES" has data. You can set the he flag to "NO" if a data value in that particular cell shall not trigger the printing of this grid. Since all cells have data in our training worksheet, setting one cell to "YES" will print the grid.
• Click the Save button after each cell configuration. Data cells will turn blue.
• Save and print your report to confirm you got what you expected.

Figure 4.4.9. Grid edit window

Table element

The table layout element is the most feature-rich element, used when a report table needs to summarize data from multiple sets of source columns. For example, a set of four descriptive attributes is repeated in sets of four columns for several mineral phases. The table will suppress printing of rows if no data exist in table columns designated to trigger printing of the row.
First, set some general parameters for the table:

• Go back to the Report Edit window and double click the "block 3 data1" element to enter the Block Edit window.
• In the Block Edit window, select Table from the Select element to add choice list and click the Add button. A new element "Table: new TABLE #" will be added.
• Double click the new layout element in the list to open the Table Edit window (Fig. 4.4.10). Configure the general table parameters for our training report as follows:
• Table name (not for display) = "table1" (used for the layout element listing in the Block Edit window).
• Border {GRID, NONE) = GRID.
• Left offset (points) = 5 (default), shifts left margin of table 5 points to the right of the enclosing block's left margin.
• Top offset (points) = 5 (default), shifts the table 5 points down relative to the top of the enclosing block or relative to the bottom of any layout element printed above the table.
• Internal font size (pts) = 10 (default); applies to all cells in the table except the column headers, which can have a different format (see below).
• Internal font style {NORMAL, BOLD, ITALIC"} = NORMAL; applies to all cells in the table except the column headers, which can have a different format (see below).

Figure 4.4.10. Table edit window.

Next, specify the columns for the report table whereby each report column represents a common attribute among sets of data source columns, such as the size of the minerals.

• Click the Add button to add columns.
• Add four columns for our training report.
• Double-click each added column in the list to open the Column Edit window (Fig. 4.4.11). Configure columns for our training report as follows:
• Header text = "Column N header text", where N = {0, 1, 2, 3} for the four columns.
• Width (points) = 100 for each column (can be adjusted later as needed).
• UseMe flag = "YES"
• Must be "YES" if a source data value for that column and sample shall trigger printing of the report table row.
• MUST be "NO" if values for that column and sample shall not trigger printing of the row.
• UseMe flag has no effect for cells with fixed text, such as Column 0 in our training report.
• Justification {CENTER, LEFT, RIGHT}: use different settings as you please.
• Header font size (pts) = 10 (default).
• Header font style {NORMAL, BOLD, ITALIC"} = BOLD.
• Go back to Table Edit window using breadcrumbs, and repeat column edit for each column.
• Save regularly using Save to Database button given the tedious work involved in configuring tables.

Figure 4.4.11. Column edit window.

Next, define the rows for the report table whereby each row represents a set of parameter values (e.g., abundance, size, shape), for one set of data source columns (e.g., a mineral phase).

• Click the Work on Rows button to open the Table Row Edit window.
• Click the Add button to add new rows to the list, which initially have and temporary name.
• Add nine rows for our training report.
• Double-click one added row at a time to display the cell configuration options for each row in each column (Fig. 4.4.12). Configure as follows for our training report:
• Row Name (not printed): enter "row1" through "row9". This is only to tag the elements in the row list in the Table Row Edit window. You can do it quickly using copy-paste and double clicking a new row element as soon as you have entered the name.
• Double click the row again to configure each cell. For each cell, you can either enter a fixed text (typically used for row headers, such as the mineral name), or you can select a data source column, from which the value will printed if the row is triggered for printing (see column configuration above) (used for most cells). For our training report:
• For column 0 in each row, enter a text labels "Report row N text", where N is the row number {1,……,9}
• For columns 1, 2, 3 in row1, select data source columns:
• w1attr11, w1attr12, w1attr13
• For columns 1, 2, 3 in row2, select data source columns:
• w1attr21, w1attr22, w1attr23
• …..
• For columns 1, 2, 3 in row9, select data source columns:
• w1attr91, w1attr92, w1attr93
• Save regularly using Save to Database button given the tedious work involved in configuring tables.

Figure 4.4.12. Row edit window.

Print your reports. They should look similar to the top three blocks in the one in Appendix 2.

4.5. Using data source workbook with multiple worksheets

Move on with a report clone

Once you get to this point, you should have built an initial report based on one data source sheet, and you may want to expand it rather than start from scratch. Although the Builder keeps versions of your report each time you save it, it is a good idea to clone your reports every now and then so you can give your expanded report a modified name and keep the last version of the current report as is, just in case….

• In the Front Panel, select the last version of the current report.
• In the Editor menu, click the Clone Report button and name your cloned report.
• In the main menu, select the cloned report and click the Edit Report button in the Editor menu.

Multiple blocks for multiple worksheets

Objective

Core description workbooks typically have multiple data source worksheets for sets of related attributes, say, for basic sample information (the control tab), sediments, volcanic rocks, plutonic rocks, metamorphic properties, structures, etc. If you incorporate data from all these worksheets in your report, you must be aware that one block can only incorporate data from one worksheet. However, by using nested blocks you can still essentially include data from multiple worksheets in a higher-level block.
Organizing your layout with blocks makes sense anyway (and we already used three top-level blocks in the simple report for that reason). Furthermore, we can exploit the nested blocks feature to print titles that that only show if data exist in the block, but disappear otherwise so the report is not cluttered with empty blocks and their titles (see below).

Declare worksheets

Before you can add new blocks, you need to make sure the data source worksheets to be used in the report are declared. We have done that already for the simple report, but check to be sure:

• On the Report Edit window, click the Declare Worksheets button to open the Declare Worksheets window.
• Proceed as described previously, except this time
• Source worksheet name = "worksheet2"
• Identity source column = "w2samples" (using the training workbook).
• Is this the report control worksheet? = "NO" (worksheet1 is the control worksheet).
• Using the breadcrumbs, return to the Report Edit window.

Add and configure new blocks with title for additional worksheets

First, establish two new blocks:

• On the Report Edit window, add two new blocks by clicking the Add button. Follow the procedure described above for blocks, except this time you set the parameters (using our training workbook) as follows for the first block:
• Block name (not printed) = "block4 data2".
• Data source worksheet = "worksheet2" (from choice list).
• And for the second block:
• Block name (not printed) = "block5 data3".
• Data source worksheet = "worksheet3" (from choice list).

Then you add a Text element to each of the two blocks that say something like:

• Text to display = "WORKSHEET 2 DATA"
• Text to display = "WORKSHEET 3 DATA"

Remember, the block and title will only print if actual data exist in the data source worksheet and if at least one Field, Grid or Table is configured to show the data in the block. Therefore, go ahead and:

• Create a grid and/or table in block 4 using any of the attributes found in worksheet2.
• Print the report and confirm that you can see the block with title "WORKSHEET 2 DATA", but not the block with title "WORKSHEET 3 DATA".

We will use the third data source worksheet in the next section.

4.6. Best practices for multiple sample/interval domains

Objective

Multiple sample/interval domains refers to the fact that in the DESC workbooks information from one sample may span multiple rows (often two or three) because the sample (i.e., thin section) or interval have multiple domains characterized by lithology, texture, structures, etc.
If you look at worksheet3 in our training data workbook, you find that all sample names with odd numbers have one domain, whereas sample names with even numbers have 2, 3, 4, and 5 domains. We will confirm here that we can produce the expected result in the report.

Mechanism

The Writer program processes the data source workbook by using all values in the Identity source column of the Report control worksheet as a guide to assemble data for samples in multiple source worksheets. It creates a new report for each row in the Report control worksheet. This is why the entries (sample name) in that column must be unique, whereas all other worksheets may contain multiple rows with the same sample name (for multiple domains) in the Identity source column. The Writer will repeat printing of all layout elements within an enclosing block for as many rows (domains) as exist for a control value (sample name).

The trickery

The single-most tricky part of creating an effective report with multi-domain samples is to use nested blocks correctly such that domain-specific information is repeated in domain blocks but the block title is not.

• In the Report Edit window (Fig. 4.6.1.), double click (or create, if it doesn't exist already) the "block5 data3" item to enter the Block Edit window and configure for our training workbook:
• Block name (not printed) = "block5 data3".
• Data source worksheet = "worksheet1" (change from worksheet 3!)).
• Border = "BOX"
• You should already have a Text element in that block that says something like "WORKSHEET 3 DATA". If not, add one.
• Now, add a nested domain block element under "block5 data3" that will contain all domain-specific elements and information, i.e., Grid and Table elements that repeat for each domain. Double click the "Block: new BLOCK #" element and don't be confused by the Block Edit window looking exactly the same as before – orient yourself relative to hierarchy with the breadcrumbs!). Configure as follows:
• Block name (not printed) = "domain_block_5_1"
• Data source worksheet = "worksheet3".
• Border = "BOX"
• Within this domain block, create all the other layout elements that you want to repeat for each domain.
• First add a grid that looks the same as the one created for the simple report (see above), except that the data source references selected from the drop down lists will be "w3attr1" through "w3attr6" for the six cells of columns 2 and 4.
• Then create a table that looks the same as the one created for the simple report (see above), except that in the cell configuration, the references to attribute columns (report columns 1, 2, 3) are for worksheet3, i.e.:
• w3attr11, w3attr12, w3attr13
• w3attr21, w3attr22, w3attr23
• …..
• w3attr91, w3attr92, w3attr93

Figure 4.6.1. Report edit window showing all five top-level blocks in training report.

Figure 4.6.2. Block edit window for top-level block, associated with worksheet 1, containing a text element for the title and a nested domain block (associated with worksheet 3, not shown here) for elements and data that repeat for each domain

3.6. Final report version archiving protocol

To ensure that one could reprint the reports in the future if so desired, the current proposal is that once the data source workbook and the report definition are complete (no later than 1 year postcruise), both are zipped up and loaded as DESC assets. This in addition to the regular DESC workbook uploads and the attempt to preserve the final report definitions in the Builder.

Appendix 1: Loading and referencing images

The TS Writer program retrieves thin section images from the ASMAN asset management system, using the ASMAN ID. Users have to retrieve the ASMAN IDs of the images to be printed and enter them in dedicated columns in the data source workbook, more specifically, in two column of the thin section report control worksheet (the first one), one for the plane polarized and one for the cross polarized images.
If routine production images are used, the ASMAN IDs can be found using the LORE data retrieval application. This works fine on shore, or on the ship once images for the current expedition have been loaded. Because training or testing sometimes needs to happen on the ship before routine production images are loaded, we loaded 18 training images to the ship database (Expedition TEST, Site TRAIN) during the Transit 362T. We agreed that Site TRAIN should be preserved in the future for this and other purposes.
The training images were uploaded using DESClogik. The process is described here in case it must be repeated in any of the database instances in the future.

• Launch DESClogik
• Open the template "DESC assets upload"
• In principle, any template can be used, but it may help to find things by template this way, if needed).
• Using the sample selector, select Exp TEST, Site TRAIN, Hole A and enter it in the first row.
• Double-click the last cell in the row (File data column) and add all images:
• Type = "Other"
• Category = "Igneous petrology"
• Comment = "Thin section training image"
• Copy the ASMAN IDs generated (these need to be entered in the data source worksheet).
• Upload (save) the records.
• Using DESC Reports, you should be able to view the image records (didn't work in http://web.ship.iodp.tamu.edu/LORE/ on 362T.

Appendix 2: Troubleshooting

Writer does not generate PDF files

If no error messages appear and everything else looks normal, check if the necessary "Use Me" flag was set. For example, if you create a simple table an a block with nothing else, and none of the table columns are set with "Use Me", no columns will be used, the table header will not be printed (as specified), and the block will not be printed because nothing is in it, i.e., you get nothing.

Archived Versions