Guidelines of the FDZ of the BA at the IAB as to the Use of Remote Data Access and On-site Use with JoSuA

Transcription

1 Guidelines of the FDZ of the BA at the IAB as to the Use of Remote Data Access and On-site Use with JoSuA Source: (Version 5.1; January 22nd, 2016) 1

2 Job Submission Application (JoSuA) at FDZ The FDZ uses the software application JoSuA which has been developed by the Institute for the Study of Labor, for Remote execution, Uploads of do-files before on site-use and Return of results after on site-use. Every user gets an account for JoSuA after a use agreement is concluded. Users upload their programs in JoSuA. The results are available in JoSuA as well. Users can upload one job each day. Please do not upload a new program before you have received your previous results for this project. The uploaded programs as well the results are located on a server which is not connected to the FDZ-guest network. Further details about the use of JoSuA are described in the text below. Further information on using JoSuA can be found in the manual: Source: (Version 5.1; January 22nd, 2016) 2

3 Data Usage Procedure (Quick Guide) 1. The FDZ provides project directories and the requested data 2. Evaluation programs must comply with FDZ specifications 3. Data usage 4. The FDZ reviews the result files for data security 5. Return of the reviewed results 6. Publication of results 7. Special arrangement for other software Structure of the Project Directories Each research project receives its own directory (fdzxxx) per FDZ dataset. Different datasets cannot be used together. Each project directory contains the following sub-directories: orig: This directory may only contain all the original data. Apart from the requested data, this may include submitted aggregated data, as the case may be (see Section Transfer of External Aggregated Datasets ). You will be granted read-only permission for this directory. data: This is where all the generated datasets should be stored. Please use this storage space sparingly. A maximum of 30 GB is allowed per directory. If you exceed this maximum, you will not be able to submit new jobs until you have reduced your storage space. prog: This folder contains all the evaluation programs (.do files,.ado files, etc.). By default, the FDZ offers analyses with Stata. If you need any other statistical programs for your evaluation purposes, please contact the FDZ. log: doc: This folder contains all the result files. Stata result files must be in ASCII text format and have the extension.log or.txt. Other formats (especially.smcl ) are not allowed. This folder is meant for PDF documents that were previously submitted via . Creating any other directories or sub-directories is not allowed. Source: (Version 5.1; January 22nd, 2016) 3

4 Organisation of the Evaluation Programs The Master File All programs used during the project must be run from a master file. This file is located in the prog folder and must always be named master.do. Its structure is illustrated in Example 1. Use the Stata global variables $orig, $prog, $data, $log, $doc to access your files. These variables are automatically made available for you during remote execution and on-site use and must not be overwritten. You cannot use cd commands. Never use the set max_memory command. Any previously submitted.ado files must be incorporated via the master file. The master file must contain all evaluation programs relevant during the project. It is important to add a short description of the contents of the respective routines in the master file after every program start command. The evaluation programs must be numbered in the order of running them. If several users are working separately on a project, their programs may be distinguished by adding abbreviations to the file names, e.g. (th01_persdat.do). All files generated by you (result files, analysis datasets, etc.) must be replicable based on your programs and the original data. Program steps that have already been executed and have not changed since the last submission must be commented out in the project history. Source: (Version 5.1; January 22nd, 2016) 4

5 Example 1: Contents of the master.do file * Master file of the project "Project name" * Users: T. Hill (th) and W. Miller (wm) version 13 clear set more off *set linesize 120 *set linesize 255 adopath ++ $prog // so the program will scroll down all the way // for Internal Use mode // for Publication/Presentation mode // storage location of the.ado files // (if needed) *do "$prog/th01_persdat.do" // preparation of individual-level data *do "$prog/th02_betrdat.do" // preparation of establishment data *do "$prog/th03_datxy.do" // merging *do "$prog/th04_analysea.do" // examination of Hypothesis 1 (...) *do "$prog/th05_analyseb.do" // examination of Hypothesis 2 (...) *do "$prog/wm01_datagen.do" // preparation of individual-level data do "$prog/wm02_analysex.do" // examination of Hypothesis 5 (...) do "$prog/wm03_analysey.do" // examination of Hypothesis 6 (...) * Output of a file list in a.log file capture log close log using "$log/dateiliste.log", replace dir $prog\* dir $log\* dir $data\* dir $orig\* log close.ado Files We do not provide.ado files. They cannot be downloaded online, either. If you want to use.ado files, you have to send them to the FDZ mailbox prior to your on-site use. Ado files are saved in the prog folder by the FDZ. If you want to use ado files with JoSuA you need to upload them in JoSuA. Please consider that the uploaded ado files in JoSuA are not available in your project folder for on-site use and the other way round. JoSuA and the FDZ-guest network are located on different servers which are not connected. Using the adopath++ command, the.ado files can then be incorporated into the master.do file and accessed there. Source: (Version 5.1; January 22nd, 2016) 5

6 Evaluation Programs Result files (including graphs) must have the same file name as the program with which they were generated. For example, 01_PersDat.do will generate the result file 01_PersDat.log. The programs must be documented for the privacy review (see Example 2). Please take the following into account: using interim headlines, such as Preparation of the variables X or Establishment-level aggregation, describing the content/function of loops, creating variable labels for all important variables that were newly formed, using descriptive variable names whenever possible, and quickly describing newly generated variables once again directly before descriptive statistics. Example 2: Content of a program for data evaluation * Write log file: capture log close log using "$log/th04_analysea.log", replace * Program file of the project "Project name" th04_analysea.do * Content: Examination of Hypothesis 1 * Aggregation level: industries by federal state * aggregation to th03_datxy.do * min. 20 establishments per data line * number of individuals per line is specified in Cases clear all * Load original data: use "$data/name of dataset", clear * Analyses [...] * Save generated data: save "$data/neuername", replace log close Source: (Version 5.1; January 22nd, 2016) 6

7 Documentation of Aggregation If the original micro data are aggregated (e.g. at establishment or region level, etc.), this must be described accordingly in the analysis program. If those aggregates are displayed later in the program, the underlying number of cases has to be computed: For each aggregated variable there has to be an additional variable which contains the number of valid cases (individuals and/or establishments) per aggregate (e.g. bysort aggregate: egen N_var1 = count(var1) ). If the aggregate is a ratio, the number of valid cases has to be computed for each subgroup of the aggregate (e.g. number of men in state X and number of women in state X in addition to the ratio of women in state X). All result files generated after an aggregation must contain the following information at the beginning: at which level the aggregation took place, during which step in the program the aggregation took place (also specify in master.do), the minimum number of individuals and establishments per data line (e.g.: cells containing <20 establishments were deleted), and name of the variable that contains the observation count per data line. If the corresponding references to the aggregation are missing from the beginning of the result file, it is possible that too much data gets deleted during the privacy review process. Taking account of the rule of data economy, please reduce the amount of aggregated tables to a minimum. Source: (Version 5.1; January 22nd, 2016) 7

8 Data Usage Test Data Before sending in your evaluation programs for remote data access, please test them by running master.do on the test data provided on the FDZ website. To this end, define $orig, $data, $prog, $log as appropriate for your test environment before running master.do. Do not write the global definitions in master.do but in the profile.do file. This file is automatically run by Stata. There is no need to access it via master.do. 1 After your tests have been successful, upload your programs in JoSuA in an unchanged state Preparation of On-site Use If you wish to have any prepared evaluation programs (or other files) at your disposal at the FDZ, you should upload them via JoSuA at least three business days prior to the first day of on-site use. Please consider the details in chapter 5 of the JoSuA-Manual ( Please write in the comment field of JoSuA that you need the do-files for on-site use. If you wish to have any (aggregate) data or ado-files at your disposal at the FDZ, you should send them to the FDZ mailbox (iab.fdz@iab.de) at least three business days prior to the first day of onsite use. Please state the date of your on-site use in the . We will confirm receipt of every order via . If you have not received acknowledgement of receipt two business days after sending your , please let us know. We cannot guarantee for files received or uploaded later than that to be available at the start of the on-site use. Please note that we have to specifically examine any transmitted external datasets for data protection reasons before we can make them available to you. Remote Data Access Please use JoSuA for remote data processing ( We do not modify the evaluation programs you upload in JoSuA. They must therefore be transmitted in fully operable condition. We always run your evaluation programs using the most recent Stata release available to us. Your uploaded do-files are downloadable in JoSuA. The FDZ does not forward do-files. Please do not send in a new program before you have received your previous results for this project. If you wish to use external (aggregate) data for your analyses via JoSuA, please send them to the FDZ mailbox (iab.fdz@iab.de). We will confirm the provision of the data via . If you have not received acknowledgement three business days after sending your , please let us know. 1 See also the Stata help: help profile. Source: (Version 5.1; January 22nd, 2016) 8

9 Data Economy Use the storage space in your data directory sparingly. Use the compress command when saving datasets. Delete datasets that were generated in the meantime as soon as you no longer need them (see Example 3). Example 3: Deletion program * Program file to delete data that is no longer needed * 07_delete.do * Write log file: capture log close log using "$log/07_delete.log", replace * Delete files: capture erase "$data\test1.dta" // erase "$data\test*" does NOT work capture erase "$data\test2.dta" [etc.] log close Source: (Version 5.1; January 22nd, 2016) 9

10 Privacy Guidelines The results generated during on-site use or remote data access are reviewed by the FDZ team for compliance with data privacy guidelines and transmitted to the users afterwards. If necessary, individual results will be deleted if they do not comply with our privacy regulations. Detailed information on the guidelines and examples can be found in the FDZ-Methodenreport (06/2012) by Hochfellner et al. (2012) 2. The user pledges not to perform reverse calculations to identify any deleted values. In the event of an infringement, the user will be excluded from any further data usage for up to two years. Moreover, the penalties specified in the contract of use may be applied. Information on any breach of the obligations named above will be passed on to other research data centres. Transfer of External Aggregated Datasets External variables on an aggregated level (e.g. unemployment rates by districts) may be merged to the data if they comply with the FDZ privacy guidelines. Aggregated values must refer to at least 3 observations. It is not possible to merge individual observations. The corresponding variables must be transferred to the FDZ together with a description of the dataset (including variable descriptions, the aggregation level, and a source citation, e.g. an URL). It is not allowed to transmit these datasets in a program file Documentation of the Number of Cases in an analysis During our data privacy review, all values that are based on less than 20 observations (individuals and/or establishments) will be deleted. In order to prevent reverse calculation of deleted values, other values often have to be deleted or rounded as well. Therefore, for all statistical variables or multivariate analyses, the number of cases they are based on must be specified. If the number of cases is missing, we will delete the corresponding results. When displaying means, the minimum, maximum, and standard deviation must also be specified. We need this information to examine the distribution for variables with only two values (such as dummies). When displaying a ratio, the number of valid cases in all subgroups also has to be displayed. When using weights in descriptive analyses, analogue unweighted results must always be specified as well. The weighted and the corresponding unweighted result tables must always be listed one directly below the other. Please also make sure you program your loops accordingly. 2 Hochfellner, Daniela; Müller, Dana; Schmucker, Alexandra; Roß, Elisabeth (2012): Data protection at the Research Data Centre. (FDZ-Methodenreport, 06/2012 (en)), Nuremberg, 25 p. Source: (Version 5.1; January 22nd, 2016) 10

11 Only concerning presentation/publication output in JoSuA: For the data privacy review process, a description of each variable used in a model must be included in front of each multivariate analysis. Only concerning linked employer employee data: Please report both the numbers of individuals and establishments in the descriptive tables. Permitted Output Formats of the Log Stata result files must have the extension.log or.txt. Only these result files will be sent. Results which were saved outside of the log files returned by Stata must be incorporated back into the log file (see Example 4). Example 4: Incorporation in log files * Incorporating results which were returned outside of the log files * Output content of a.csv file in the Stata window type $log/ergebnisse.csv * Output LaTeX code directly in Stata (example) esttab [ ], tex Graphs Stata graphs can sometimes be transformed back into the original data. To avoid this possibility we will only send you Stata graphs that are generated with the "asis" option (see example 5). The formats wmf, eps and png are also allowed. Please generate graphs only if it is not possible to create them on the basis of tables with e.g. Excel on your own. The number of generated graphs should be as low as possible as the effort of disclosure control on graphs is very high. Please provide evidence on how many observations every depicted value is based on. This is possible by displaying the observations either right in the graphs or in tables placed directly before or after the generation of the graphs. Source: (Version 5.1; January 22nd, 2016) 11

12 Example 5: Incorporation in log files * format of graphs graph...,... saving(filename, replace asis) * or graph save filename, replace asis Aggregated Datasets If you wish to receive aggregated datasets as result file, please consult with us about the procedure in advance. The generation of the aggregated data should take place during on-site use. After finishing the aggregated data, the data generating program has to be uploaded in JoSuA with the presentation/publication mode. Please write in the comment field that you want the aggregated data and the respective file name. The regulations for aggregated variables also apply to the documentation of the aggregated datasets. For each project, such a dataset can be forwarded only once. The FDZ will transmit these datasets via . Source: (Version 5.1; January 22nd, 2016) 12

13 Return of the Results On-Site Use After on-site use, the FDZ team will not return the results generated during on-site stay, instead you will start the programs with JoSuA again. Therefore, please make sure that master.do and the other program files are fully operable and upload them in JoSuA from the FDZ server. If you need your results for a presentation or publication, please let your programs run with the presentation/publication mode. If you just need your do-files, write STOP in your master before the do path of do-file commands. Please read the section Return of the reviewed result with JoSuA below to learn more about the further process. Your uploaded do-files are downloadable in JoSuA. The FDZ does not forward do-files. Remote Data Access You will only receive the reviewed result files generated via master.do. The timely return depends on server utilisation and the complexity of computation and review. Please consider this in your planning. Please read the section Return of the reviewed result below to learn more about the further process. Return of the reviewed results with JoSuA Internal use: Uploaded do-files start automatically. The results are available via on-screen display. The FDZ does not review these results, however an automatic check routine will be run. It is not allowed to copy, print, otherwise extract or use these results. Furthermore do not give/send these results to other persons who are not involved in the project. The use of these kinds of results in presentations or publications is an infringement of the data privacy agreement. Make sure to use the internal use mode until you need intermediate result or end results. Presentation/Publication: The FDZ will start your uploaded do-files and will review the results manually for data security. You can download the results in JoSuA and use them for presentations or publications. We do not modify the evaluation programs you uploadin JoSuA. They must therefore be transmitted in fully operable condition. Please upload only do-files that are relevant for the presentation or publication. All other results should be viewed via the onscreen internal use mode. It is not allowed to perform reverse calculations to identify any deleted values. Therefore the results of the internal use mode will not be available anymore after results of the publication/presentation mode are provided in JoSuA. Please do not upload a new program before you have received your previous results for this project. Source: (Version 5.1; January 22nd, 2016) 13

14 Please keep in mind that some Stata-commands are forbidden in general with the internal use mode to protect data privacy. Exceptions are not possible. But in case of relevant results, which cannot be produce with other Stata-commands, you have the possibility to use the presentation/publication mode. Publication of Results The data and documentation must be properly cited in publications according to the specifications on the FDZ website ( Please send a specimen copy to the FDZ. Source: (Version 5.1; January 22nd, 2016) 14

15 Special arrangement for other software By default, the FDZ offers analyses with Stata. If you need any other statistical programs for your evaluation purposes, please contact the FDZ. All analysis and data preparation which are possible in Stata should be executed in Stata. Furthermore write a command to select the other software in the do-file. Only Stata is possible with JoSuA. If you use other software packages you need to send the dofiles to iab.fdz@iab.de. Please consider the following details: In order to process your orders, we need you to state the project specifications in the subject line of every (see Example 6). Newly sent files will overwrite existing files if they have the same file name. Please already point out in the subject line under Other what must be taken into consideration when working with the programs (e.g. after on-site use at ). Please note that we will send orders back unprocessed if any relevant information is missing from the subject line or the format requirements have not been complied with. Please do not send in a new program before you have received your previous results for this project. Please do not use JoSuA in the publication/presentation mode in this period. Example 6: Subject line DAFE Project number Required memory Expected running time End date of contract Other fdz###, # GB, # hours/days, yyyy-mm-dd, [Other] yyyy-mm-dd = date in year-month-day format Examples: fdz041, 3 gb, 14 h, fdz041, 3 gb, 14 h, , after on-site use at fdz041, 3 gb, 14 h, , Matlab fdz041, 3 gb, 14 h, , after on-site use at , Matlab Source: (Version 5.1; January 22nd, 2016) 15