Using the GFZ Report Generator tool

The Report Generator

Preparation of a data report for GFZ can be unwieldy. However, for a passive seismic network a significant proportion of the content of reports is pro forma, i.e., it is usually expected to show a station map, document the types of instrumentation 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, while meeting 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 with FDSN network code ZE.

The report is available as

Another example is

This approach 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.

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. GEOFON offers an online service for PIs and others to generate network reports.

Figure 1

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

Figure 2

A finished network report is published as PDF.

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 GEOFON 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 seismic metadata for the data set, we will generate the standard figures and tables necessary 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 shows the HTML version of the document with its overall structure and alread 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 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 data set.

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.

Figure 4

A blank report, awaiting author input.

Figure 5

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

Citation

A recommended citation string is provided on the report 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 data set, 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, after publication, reports on datasets are public, even if the underlying data is still under embargo.

Why prepare a data report anyway?

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.

RST guides

More about the software

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.