Using the GFZ Report Generator tool

Why prepare a data report?

A data report is the ideal place to go beyond the standard seismic metadata in describing your data. This greatly assists future users of the data and preserves important details. You can report on why and how decisions about station locations were made, geophysical context, issues arising during deployment or subsequent data processing, such as timing accuracy and more. It provides understandable basic information about a seismic network in a convenient way, e.g., by including station maps and tables.

For data sets acquired with GIPP instrumentation, documentation of the data with a report is obligatory. For other datasets archived at GEOFON, provision of a report is strongly encouraged.

The Report Generator Tool

Preparation of a data report for GFZ can be unwieldy. However, a significant proportion of the content of reports on passive seismic networks is standardised, i.e., it is usually expected to show a station map, document the types of instrumentation which were used, and show the noise statistics for the network stations.

The GFZ report generator is an online text editor meant to ease this process by (i) automatically generating the standardised figures and tables, (ii) creating a report template pre-filled with this standard content, and which meets the GFZ style requirements, and (iii) providing a browser-based GUI allowing addition of content to the report in an interactive environment. The report generator automatically generates both PDF and HTML outputs using Sphinx, a popular Python library. Because content is generated directly from the metadata and data stored at GEOFON it is also helpful for finding some classes of problems with the metadata.

An example of a completed network report is

which documents the data set archived at GFZ for a temporary data set with FDSN network code ZE.

The report is available as

Another example is

This tool requires writing your report using reStructuredText (RST). This is almost like plain (normal) text, but has an easy-to-read, what-you-see-is-what-you-get (WYSIWYG) plaintext markup syntax, allowing lists, links, tables, highlighting, and more. For inserting special items (figures, tables) or formatting (italic, bold, math symbols) a short RST help and links are provided within the template, so normally no reference to outside documentation is needed. Some guides to RST are linked to below. The web application features figures insertion via a simple button click and a simple revision/version control system, which allows moving back to previous document versions easily.

Finished report viewed as a web page

Figure 1

A finished network report can be viewed as an online web page.
Finished report as PDF

Figure 2

A finished network report is published as PDF.
GFZ STR landing page

Figure 3

GFZ's library hosts a landing page for the report as part of its STR series.

Preparing a report with GEOFON

The basic pre-requisite for initiating the process is that your data and metadata have been uploaded to GEOFON and are archived there. To create and publish a network report via the provided service, the workflow is:

  1. Write email to GEOFON. Include the network name and start year, and a list of user(s) email(s) authorized to edit the report, i.e. the authors of the report.
  2. Based on the archived data and metadata, we will generate the standard figures and tables for the report. This process might require a few days depending on the amount of network data.
  3. You will then be sent the URL of the editor page, which initially shows the HTML version of the document with its overall structure and already filled with some of the standard content. Now it is ready to be edited online by the authorized user or users (*). This needs to be completed with the necessary text. There is extensive documentation embedded into the template. The sections marked {AUTHOR INPUT} require your particular attention. You are free to add further sections and figures or modify the structure of the document as is deemed appropriate for your particular dataset. You can generate and inspect the HTML and PDF versions of the report on the fly as you are editing.
  4. When you are ready, contact us again. The document is then reviewed by GEOFON and Library staff.
  5. When all are satisified, a DOI is minted and the finished report is published. We will link from the landing page of the data set to the data report, e.g. to http://doi.org/10.14470/MR7567431421 for the SELASOMA dataset in the example.

Note that it is also possible to generate a preliminary report on a partial dataset, e.g., to help with checking the correctness of the metadata, or to provide project participants and partners with an easily accessible summary. In this case the process stops at Step 3, and Steps 4 and 5 are postponed until the end of the experiment and the completion of the final report.

The source document can be edited (i.e., filled with the necessary text or figures) online, i.e. from within a web application in the user browser. This means that several users can be involved in the process easily if care is taken: due to technical restrictions, users cannot work on the document simultaneously. When several users are involved, any user should remember to log out when finished.

View of an empty report

Figure 4

A blank report, awaiting author input.

Editing a network report

Figure 5

Editing a network report. Text is easily modified in the left half of the screen.

Citation

A recommended citation string for your report is provided on its landing page, e.g. https://doi.org/10.2312/gfz.b103-17061

Important: When you or other data users want to acknowledge use of a dataset, use the data citation, e.g.

Tilmann, Frederik; Yuan, Xiaohui; Rümpker, Georg; Rindraharisaona, Elisa (2012): SELASOMA Project, Madagascar 2012-2014. Deutsches GeoForschungsZentrum GFZ. Other/Seismic Network. doi:10.14470/mr7567431421.

Citation of the actual report is only needed if particular information from the report is used, not to simply acknowledge use of the data.

License

Reports published in the GFZ STR series are distributed with a CC-BY-4.0 license. Note that reports on datasets are made public, even if the underlying data remains under embargo.

RST guides

More about the software

The report generator is quite flexible and by the use of tailor-made templates can be adapted easily to other use cases, where part of a document is based on standardised figures and section structure. For example, the same software is used to generate GEOFON Annual Reports and seismic network reports, producing station probability density functions and data availability handled by GEOFON. The program GUI (graphical user interface) is a web page showing the report in HTML format. GEOFON offers an online service for PIs and others to generate network reports. For developers, or if changes to the generation of the template report are needed, the code is available on github. This should only be needed in exceptional cases, as any custom figures and text can be included in the RST after the template generator has run.

The report generator is described in detail at:

Zaccarelli, Riccardo (2019): gfzreport - a Python tool and online text editor for creating any kind of report meeting GFZ requirements in HTML and PDF format. GFZ Data Services. doi:10.5880/GFZ.2.6.2023.006