3  Guidelines for the design of evaluation programmes

The FDZ staff, who check the output, rotate daily. In order to be able to check the output, it must be possible for the FDZ employees to understand the programmes without having knowledge of the project content. Therefore, sufficient commentary on the do-files is necessary. Examples for the structure of the do-files can be found in the FDZ templates on our website at.

The following general principles must be considered when generating analysis programmes, so that an analysis programme complies with the guidelines of the FDZ¹.

3.1 The master file

The master file must be designed as follows:

• All programmes used in the course of the project must be run from a master file. This file must always be named master.do. The master.do file in the FDZ templates illustrates its structure.
• Use the Stata globals $orig, $prog, $data and $log to access your files. These globals are automatically made available for you as well during remote execution via JoSuA as on-site use and remote desktop and refer to the correct storage location. The globals must not be overwritten.
• Do not use cd commands or relative path definitions.
• Never use the set max_memory command.
• Commands not permitted are censored by JoSuA. In these cases, you’ll see the line commented out with the tag *** CENSORED ***.
• The master file must contain all analyses programmes used during the project. It is important to add a short description of the contents of the respective routines in the master file after each programme start command. Do not use the nostop option.
• The evaluation programmes must be numbered in the order in which they run. If several users are working together on a project, their programmes may be distinguished by adding abbreviations to the file names, e.g. jd02_describe.do. This does not apply to the master.do.
• All files you generate (result files, analysis data sets, etc.) must be replicable based on your programmes and the original data.
• Programme steps that have already been executed and have not changed since the last submission in JoSuA must be commented out in the master.do. Data sets stored in the folders orig and data can be accessed using JoSuA. Do- and log-files are stored on separate servers though.
• For JoSuA, we recommend to set the linesize to 120 in Internal Use Mode, because that corresponds with the width of the output windows in JoSuA. Use the command set linesize.

3.2 Programme Files

• Result files (including graphs) must have the same file name as the programme with which they were generated. For example, jd02_describe.do will generate the result file jd02_describe.log. The graphs generated in jd05_graphs.do can be named e.g. jd05_graphs_02_boxplot1.gph and jd05_graphs_02_boxplot2.gph.
• The programmes must be documented in German or English language for the privacy review (see FDZ templates). Please take the following into account:
  • Open a log-file at the beginning of every do-file (before every other command and before the content-related description of the do-file)
  • write central information (e.g. author, data set used) at the beginning of each do-file (see also example in jd02_describe.do)
  • Use subheadings (such as “Preparation of the variable X” or “Establishment-level aggregation”)
  • Describe the content and function of loops and programme descriptions of tables into your loops (e.g. using the display command)
  • Create variable labels and (if appropriate) value labels for all important variables that were newly generated
  • Use meaningful variable names whenever possible
  • Briefly describe self-generated variables directly before frequency tables
  • Describe the content of each graph and complex table (see the examples in the FDZ templates)
• Result tables and graphs produced in Presentation / Publication Mode must be carefully documented (see also examples in jd02_describe.do and jd05_graphs.do):
  • Each table/graph must have a heading with a consecutive number within a do-file.
  • Each table/graph needs a description with the name and content of the designated variables, the relevant selection criteria and the purpose of the table/graph.
  • All other commands for results that are only relevant in Internal Use Mode, during on-site use or remote desktop access must be deleted or commented out.
• For the output of regression results, we recommend the following procedure (see examples in jd03_analyses.do):
  • Combine - if possible - several regressions in one table (e.g. with estimates table, estout, etc.). If possible, do not output these results twice! You can use “quietly” before the regression command for this purpose.
  • If you only need a subset of the regression coefficients for your publication, please only have these displayed; you can have more detailed results displayed in the Internal Use Mode for your review.
  • Please describe any special features that might be relevant for data protection review (fully interacting model, the dependent variable is dummy, etc.). The header of the regression table must clearly indicate which results are involved (if there are several).
  • We accept regression tables as TeX code, but only if it is easy to read; make sure that the columns have fixed widths.
• In principle, evaluation programmes (as well as ado-files sent in) must not contain any data or numbers of observations. External aggregated data sets must be sent in separately as Stata files. This does not apply to classifications and conversion tables (e.g., contribution assessment ceilings, DM-Euro translation, GDP deflators, CPIs, transcoding of industry codes, districts or employment agency districts). Please comment on which classifications and conversion factors you use in your programming. Please note our manuals on importing aggregated data sets in section 2.2.2.

3.3 Efficient Data Handling

• Use the storage space in your data directory sparingly. Once the maximum of 30 GB is exceeded, no more jobs can be processed (except deletion programmes, see jd07_cleanup.do) until the storage space is reduced.
• Temporary data sets should only be saved if necessary for subsequent analyses. Data sets need to be reproducible with your do-files at any time. Delete data sets that you generated in the meantime as soon as you no longer need them (see jd07_cleanup.do).
• Limit your data set to those variables and observations that you actually need for your analyses (see jd01_dataprep.do and jd04_mergebhp.do).
• When developing programmes, it might be helpful to test with a subsample (see jd00_subsample.do).
• Use the compress command at least before saving data sets.
• When generating new variables, please use the most economical format (e.g. generate byte or generate int).
• The available RAM memory is limited to 30 GB per person and project.

---

1. Furter information can be found in the manuals