Customizable Reports

Hello, my name is Sarah Gremm, I am a software developer in the application team at Stegmann Systems GmbH. In this article I will present our emerging concept for future PLA-Reports to you and especially depict the advantages and the flexibility it offers to our customers.

Currently we are busily working on our new document package "Dose-response analysis", which focuses on interpolation on reference curves determined by regression. For sure there will appear another blog post when it comes to the release of the package. (Attention! Spoiler Alarm ????) At this point in time it's a greenfield for us to bring up new ideas and concepts, to get rid of old loads and improve traditions. Furthermore, I hope to reach some interested minds out there - so please do not shy away to comment, to criticize or to bring your own ideas and requests.    

Future PLA-Reports - First Step ...

If we overlook our greatest document type - the Quantitative Response Assay - for a moment, each of our yet published document packages comes along with one or at most two report types for each of its document types. This inflexibility leads to extensive extra work on both sides – all too often in form of custom report packages.

One or the other discussion has led us to two possible approaches, which could enable our clients to define their very own report layouts:

  1. User adjustments will be part of the document template itself. 
  2. User adjustments will be outsourced into a separate (secondary) document type, which is referenced by the individual documents.

    (We must not forget: We move within the scope of application development. This means that development must not require any changes to PLA. You see: Our limits are more or less narrow.)

1. User adjustments as part of the document template

Even now some of our document types bring the opportunity to change the appearance of the result graphics. By means of different characteristics (changeable via the “Settings”-Block) the generated plot can be modified during the calculation process.

The obvious (directly implementable) solution, enabling our customers to design their own reports, is to expand this settings block by an additional “Report”-Element. Here we will provide different predefined Blocks, each with a set of parameters, adapting the selected content to individual needs.

Allocating this function to the template designer we decided to hide the whole report settings block from other users via template protection settings. Creating a new document out of a given template the user typically does not encounter with this subject. The document inherits the definitions for the customizable report implicitly.

For demonstration purposes we selected two different blocks: First the regression output, with our detailed report parameter estimation table, plus data plot and regression plot and second the whole Single-dose sample result, with interpolation table, test summary, sample suitability test results and the appendant plot. A further refinement of the selection is quite conceivable! And let's face it, maybe even this rough selection or strong summary of content has led to the fact that the true benefit has not yet become so apparent in the first attempt. But no more about it, further on in context!

At this point, you don't even need to understand what is hidden behind the individual blocks. Let us rather concentrate on the report concept... Let's go!

Using the settings block of our document, we initially add the report settings with each content block once, in a predefined order and without any obvious parameter definitions. However, even if the parameter elements are not visibly created and no further settings are made by the user himself, useful settings are of course selected. As with our standard reports, the transformation specifies the parameter values. These ensure, that the user cannot really conduct blindfold modifications.  

The individual blocks are equally next to each other and should be completely variable in their order. Each block can be moved by drag and drop to any position in the report.

In order to allow maximum flexibility beyond this, we have decided to propose three different characteristics assignable to the particular report modules:

a. Scope

The selectable scope depends on the context of the current block. Results, which are only available for samples referencing a Multi-dose preparation scheme can be reported for the Standard sample or for all Multi-dose samples. On the contrary there are results, which only make sense for samples with a Single-dose preparation scheme. (The content is not so important here either. At this point, we only need to understand that the choices offered always depend on the context of the specific block.

b. Title

The attentive reader might have remarked the difference between the two screenshots above. So why did we implement two different formats for the “Title”-Element?  Let’s look in detail:

Our first proposal was an element “Title” which can contain an arbitrary number of the elements “String Value”, “Current Elementname” and “Current Elementtype” - of course in an arbitrary order. There are no limits for the design of an elementwise defined caption, which will be recomposed during the transformation. The ability for the user to simply click together the desired title provides a less error-prone execution, but at the same time leads to large paragraphs in the content structure within PLA. In progress of the development process a discussion came up: Why not directly embed the placeholders into the string itself?

* Note: In this approach {AssayElementName} and {AssayElementType} will be usable as placeholders for the current element. They will be replaced by the report transformation.

This option makes the title appear much leaner within PLA, but forces the user to pay careful attention to the syntax of the placeholders. Let’s put it this way: It’s a matter of taste!      

c. Decimal places

Last but not least!  We want to leave the decision of printed decimals to the customer. Technically decimal places are specified as integers. Each formatted number in the current block will be processed with this parameter.

The full measure of flexibility, however, arises only with the combination of different options. Creating the same block multiple times with different parameter assignments and arranging them in any order let the limits of the feasible move far…

Example: User adjustments transferred into the report layout

Scope Title Decimal places
Standard only (Format 1) 3
  String Value: Regression for
Current Elementtype [Standard]
StringValue: Sample:
Current Elementname [STD]
 
--> The regression block is only displayed for the standard sample! --> assembled to: Regression for Standard Sample: STD --> formatted values are rounded to 3 positions after the decimal point

Customizable report

Scope Title Decimal places
Single dose test samples only No titel 3
--> This block is generated for all test samples referring a single dose preparation scheme! --> In case there is no custom title defined, we fall back on the predefined title. PLA itself offers a preview of this default in the summary of the block:
Single Dose Sample Result: [Elementname]
--> formatted values are rounded to 3 positions after the decimal point

Report configuration withhin PLA

Customizable report

Scope Title Decimal places
Single dose control samples only (Format 2) 3
  Control: {AssayElementName}  
--> This block is generated for all control samples referring a single dose preparation scheme! --> Instead of adjoining several elements the user can work with placeholders in braces within one single string. --> formatted values are rounded to 5 positions after the decimal point. (Disregarding "5" is the default anyway. Eliminating the element won't effect the appearance of the report.)

That sounds tempting? Looks nice, but is that really practicable? What does the work of a "template designer" look like? How do you work with the documents in the end? We have to admit, we don't really know. A hidden settings block? A huge part of the document invisible? Perhaps questionable after all?

One or two doubts came over us, some time has passed, but the idea still tickled our feet...

2. User adjustments in an additional document type

Here, too, we initially worked with our new document type, from the Dose-response analysis package:

In principle, the structure of the report settings area could remain unchanged. Just not as a part of the document, but as a standalone one. Well known from established PLA document packages is the document reference. Instead of the definition itself, a reference field is provided in each document, which builds the link to our separate report definition document.

Having an empty and completely new document in front of you gives you the feeling of having much more opportunities. You don't hang under any node in the given structure, to which you now add even more content, but you can create your own structures. Perhaps this was what spurred our imagination and gave the whole project a new lease of life?

So what happens after we decide on our document type? ...well, I told you something about structures.

First, we decide how our report should be arranged. Apart from the title, there are three page formats available. If you take it exactly, there are only two, but the front page is always at the beginning and therefore gets a slightly exposed position. If we wanted to be small-minded now, we would add that the report title basically belongs to the front page, but here I come in: the Frontpage element can be deleted, but every report should have a title! 

a. Report title

We have provided three options for the output of the report title:

In PLA documents are usually identified by their name, since the document key only serves as a unique identifier within the same database. For this reason, our usual reports use the name of the document as the title, nevertheless we offer the key as a further option. However, the third selection offers the most exciting possibility here. To define an own title the user has to add the additional element "User defined report title".

This element allows you to enter any character string. Within the string the placeholders {Name} for the document name and {Key} for the document key can be used. In the example above, our report title would now read as follows: "My Report: DRA with Config - Document-167". The concept of placeholders has already been encountered above and they will play a special role in the further course of our discovery tour today. However, the element "User defined report title" is only considered if the User title option is set for the Report title and on the other hand (logically) only a title defined by the user is displayed if the element was created and edited for it. Otherwise, the system reverts to the name of the document as the default.

Let's finish our little digression here and get back to our page structures or rather the different content formats. And now, no more distractions, please!

You remember my little objection? If we're honest, there's only two of them! On the one hand we have the quite normal Content pages, where the Frontpage belongs to and on the other hand there is this somewhat more difficult to capture Content per assay element area. Let's start with the former:

b. Frontpage/ Content

The main difference between the two page formats is the rather obvious one. There can only be one Frontpage and this is always defined as the first page of the report. Whereas any number of Content pages can be defined, which can be arranged in any order (behind the Frontpage). This means that blocks containing metadata, for example, can also be appended to the end of the report. Although the Frontpage element can be deleted, this only makes sense if the report is to start immediately with the Content per assay element area. Otherwise, deleting the Frontpage would have no visible effect on the report.

Below the Frontpage element or a Content element, individual settings, entries and results can be created in blocks. In these areas, only data that affects the entire document is displayed. If you think of our usual reports, this is mainly meta data, such as calculation or signature information, as well as comments. In addition, however, content aspects can also be presented. For example, the General properties table or the Plate layout that is relevant to all elements of the assay. And to round the whole thing off, we have even provided some important results in summarized tables. Thus, for example, the suitability test results of all elements can be displayed side by side in a single table. 

Again: In principle, every element that can be created below the Frontpage element can also be created below the Content element. I have only inserted a few blocks here, which should serve as an example!

Consequently, no scope element is specified in these two areas! Therefore there are no placeholders within a title element in these areas. The user can enter a fixed string that serves as a heading for the respective block. If the element is deleted by the user, this block is output without any title. If the title element is simply not filled, the default title of the block is retained. This means that we store a predefined value for each block, which is used first.

The parameter definition "Decimal places" still has the same functionality as in our first approach described above. Each block that contains calculation results or number output can be formatted by the user with an integer that represents the number of decimal places.

In addition to the title, the user can add a Description element to each block. This element is never created automatically and there is no default available. If the element is not filled, no additional description is output. Any character string can be entered here in the Frontpage and Content areas. As the element name suggests, this option can be used to add descriptive content or remarks to a block.

c. Content per assay element

Dealing with the content per assay element area requires a minimum of background knowledge. As the name of this page format already suggests, the content defined here is output individually for each assay element. 

Stop, that's not quite true! Let's take a closer look:

The content per assay element definition comes along with an Assay element section element. Here you can define general settings for the individual paragraphs. So far, two properties have been defined here. The title of a result block works basically the same as the report title we have already covered. Here, too, we come back to the concept of our placeholders. In the case of assay element results, {Type} can be used for the element type and {Name} for the name of the respective element. The placeholders are then translated accordingly by the transformation. With Page per sample (yes/no), the user can decide for himself whether the result sections of the individual samples should follow one another directly or whether a new page should be started for each sample.

It is important to understand the main concept, then everything becomes very simple and the impossible hardly seems to exist anymore:

The transformation takes one assay element after the other by the hand and walks with it from top to bottom past the individual content blocks. This is where the background knowledge I just mentioned comes into play. Of course, the two only stay longer in the blocks that are generally interesting for the current assay element. And this criterion clearly depends on the classification of the element based on the referenced preparation scheme. (Only briefly: In the Dose-response analysis document type, assay elements are divided into two groups, those that reference a multi-dose preparation scheme and those that reference a single-dose preparation scheme. We also like to name the two groups Multi-dose samples and Single-dose samples.) But even if you don't know directly which block is available for which type of assay element, you can easily find out via the Group Scope element. 

As already described above in section 1.a, the scope for the respective sample types is divided into Standard only and All Multi-dose samples on the one hand and Single-dose samples, Single-dose test samples and Single-dose control samples on the other hand.

In addition, two further types will be introduced here: For blocks that are available for all sample types but concern individual sample results, you can choose between a Group Scope All samples, Multi-dose samples and Single-dose samples. No scope is specified for blocks that represent results of the entire assay and would not have any output differences in the result ranges of the individual samples. If such a block is selected below the element Content per assay element, it will only be output in the range of the Standard sample.

So while the transformation and the assay element so happily stroll past our block definitions, they collect those that are meant for them, along with their parameters, and ignore all the others.

Phew, that was a lot of input all at once. Take a deep breath, please. Let's let that work for a moment...

Can you imagine the immense flexibility and all the possibilities offered to us here?

And now we come to the last stop on our journey into the future, before we let the present catch up with us again:

In order to give the user not only maximum flexibility in terms of content, but also more freedom in layout questions, we have added some additional elements that are available for each of the areas. There are currently six different elements that can be used anywhere in the report:

  1. Headline: A heading is represented in particularly large and thickly printed writing. At the same time, it creates a paragraph by maintaining a greater distance from the preceding block. If a headline is inserted below Content per assay element, it will be considered by each element! Here, the placeholders {Type} and {Name} can be used just like with the usual block titles.
  2. Subtitle: A subtitle behaves basically the same as a heading, but is displayed in a slightly smaller format.
  3. Text: The text field can contain and display texts of any length. For fields placed below the content by assay element, the context of the respective assay element is taken into account for placeholders {Type} and {Name}.
  4. Horizontal rule: As the name of the element indicates, it represents a horizontal line. In this way, visual boundaries can be created and the report can be structured individually.
  5. Space: The space element creates an empty paragraph. Again, this is an element that makes it easy for the user to structure his report by allowing larger distances between two blocks.
  6. Pagebreak: Page breaks are automatically set between each page format. Within a page format, this only happens if too many blocks have been selected for a report page. In addition, the user can decide whether to start a new page in the Content per assay element area for each element. The Pagebreak element now allows to create a page break anywhere in the report.

One could now certainly highlight one or the other advantage or disadvantage for both of the approaches.

Before, however, WE prejudge everything...

It’s up to you adding your two cents worth, in one way or another!

And before, however YOU prejudge everything…

Please, don't worry: Everything is possible, nothing is necessary. If the user does not want to use the possibility to create his own report, our standard reports are of course still available.