*! version 1.2 18 June 2019
help for neps:version 1.2 (18 June 2019)

Title

neps: -- Prefix command to conveniently handle NEPS Scientific Use File (SUF) data

Table of contents

Syntax
Features of the neps: prefix command
(1) Filename concatenation
(2) Dataset localization
Options
Supporting commands
Remarks
Examples
Authors
Also see

Syntax

Run any Stata command with convenience features for working with NEPS Scientific Use Files (NEPS SUFs)

neps [, prefixoptions] : command

prefixoptions

options for filename concatenation
study(shortcode) NEPS sub-study short code (e.g. study(SC4))

version(version number) NEPS SUF dataset version (e.g. version(9.1.1))

level(anonymisation level) NEPS SUF access level
(i.e. one of level(S)=semantic data structure file, level(D)=download, level(R)=RemoteNEPS, level(O)=on-site)

directory(dirname) directory path to NEPS SUF datasets

options for dataset localization
language(language code) label language to use (e.g. language(en))

advanced options
setup record manually specified NEPS parameters as preferences for further use within the Stata session (shorthand for neps set)

replace replace already set parameters, if any (no effect unless option setup is specified)

The neps: prefix command is accompanied by supporting commands for setting up, displaying, and clearing NEPS preferences.

See section supporting commands for an overview,
or neps set and neps fileparse,
neps query,
and neps clear for details.

Features of the neps: prefix command

The neps: prefix command acts as a wrapper for literally any Stata command.
Before invoking the specified command, however, it will perform some convenience actions on the user's syntax in order to ease usability or use enhanced features of NEPS Scientific Use File datasets.
If none of these actions is required in order to execute the desired command, the neps: prefix command has no effect.

Currently, the performed convenience actions are:

(1) auto-concatenate the full file path to a NEPS dataset

(2) pre-set a file's label language to the desired language before loading it

With regards to actions (1) and (2), the neps: prefix command is considered the successor to the older, now deprecated, nepsuse command.

(1) Filename concatenation

NEPS Scientific Use File dataset filenames look something alike "SC4_pTarget_D_9-1-1.dta".

More generically put, they consist of four elements, separated by an underscore character, plus a file extension (".dta" for Stata files).

These elements are:

(1) a shorthand for the NEPS sub-study the file originates from (most common: one of the NEPS Starting Cohorts 1 through 6, e.g. "SC4")

(2) a basename indicating the file's contents (e.g. "pTarget")

(3) an indicator for the access level the file is available from (i.e. one of "S"=semantic data structure file, "D"=download, "R"=RemoteNEPS, "O"=on-site)

(4) a three-digit version number, separated by dashes (e.g. "9-1-1")

When data users need to use several files throughout a project,
it might be cumbersome to copy and paste the constant parts of the file names over and over again in order to use, describe, merge or append them.
They could, of course, replace these parts in their do-files with global macros. But, if done so, it is the global macros' names that have to be repeated in a syntax file.

The neps: prefix command is designed to enable users to remove this redundancy from their syntax files.
In order to do so, users can neps set the constant parameters once for the session, and only specify the basename [part (2) in the above example]
whenever they need to access files with any Stata command that is prefixed with neps:.
All other parts of the file name, and (if specified) the file's directory path, are automatically detected and inserted into the invoked Stata command's syntax.

(2) Dataset localization

NEPS Scientific Use File datasets ship with multi-lingual variable and value labels.
Whilst we think this is very helpful for both our international data users,
and even national users who want to publish non-german articles,
Stata's implementation of multi-lingual labels has some peculiarities.

The most grievous one is that multi-lingual labels only are read from a data file on opening it with use.
As soon as the data file is loaded with any other command,
for instance when it is the using-file in a merge or append procedure,
only labels in the active language are read.

A workaround to this behavior is to use each dataset in a project once,
then switch the active label language to the desired language,
(temporary) save the file and use this altered copy for any further data management.

This leads to long do-file code with much repetition that could be avoided or automated.
The neps: prefix command will automate the steps outlined above if the parameter <language> is specified.

Options

Filename concatenation

study(shortcode) is mandatory for filename concatenation; shortcode is a NEPS sub-study short code, most commonly one of the NEPS Starting Cohorts
(i.e. SC#, where # denominates the Starting Cohort number).

version(version number) is mandatory for filename concatenation; version number is a version number of a NEPS Scientific Use File.

Version numbers may be specified either with dashes or dots as separators (i.e. 9-1-1 vs 9.1.1).

level(anonymisation level) is mandatory for filename concatenation; anonymisation level is one of the capital letters S, D, R or O,
corresponding to the NEPS anonymisation levels semantic data structure file, download, RemoteNEPS and on-site.

directory(dirname) is optional; if specified, dirname will be used as path for filename concatenation.

If omitted, the current working directory is assumed to hold the dataset files.

If a directory path contains parts of the mandatory parameters above,
they can be incorporated as @-strings (see section remarks for details).

Dataset localization

language(lang) is optional; if specified, labels will be read in language lang.

If omitted, the active dataset label language will be read.

Advanced

setup if specified, neps: will record all manually specified options as preferences for further use in the Stata session.

This is done by automatically invoking neps set with the specified parameters.
Thus, the setup option is no more than a shorthand for manually invoking neps set at the beginning of a session.

replace will be silently passed through to neps set if the option setup is also specified.

Otherwise, it does not have an effect.

Supporting commands

neps set is a helper command to set up all parameters that the neps: prefix command might use.
See neps set.

neps query is a helper command to display all previously set up parameters that the neps: prefix command might use.
See neps query.

neps clear is a helper command to clear all previously set up parameters for the neps: prefix command.
See neps clear.

neps fileparse is a helper command to parse parameters that the neps: prefix command might use from a file name or directory path.
See neps fileparse.

Remarks

Note that manually specifying parameters as option to the neps: prefix command always takes precedence over recorded parameters from neps set.

When a directory path is read for file name concatenation,
either from a recorded preference or an option to the neps: prefix command itself,
it is allowed to contain signal words starting with the at-character @ in all-uppercase letters denoting the mandatory parameters for file name concatenation.
They will be automatically replaced by the content of each parameter.
This enables a permanent setting of a generic directory path via (sys)profile.do, if it is constant for all NEPS Scientific Use Files on a machine.

Thus, specifying a directory named after a specific NEPS Scientific Use File is simplified; there is no difference between specifying

. neps set directory "neps set directory Z:/SUF/Download/SC4/SC4_D_9-1-1/Stata14"

. neps : use "spEmp"

and

. neps set directory "neps set directory Z:/SUF/Download/@STUDY/@STUDY_@LEVEL_@VERSION/Stata14"

. neps : use "spEmp"

Note that the parameter @VERSION always represents the version number separated by dashes {e.g. 9-1-1).
It is equivalent to specifying @DASHEDVERSION.
The variant separated by dots is available as @DOTTEDVERSION.

For switching the language of an addressed dataset, the neps: prefix command opens the dataset in question,
changes its language to the desired one, temporarily saves the file,
and injects the temporary file name instead of the original one into the called Stata command.

This necessarily increases the time Stata needs to open the file.
Also, said procedure means that the file name that Stata sees on opening the file is only the temporary file path.
Thus, after useing a dataset that way, it is not reasonable to use save , replace (without a file name specification),
nor Stata's internal macro `c(filename)'.

If this situation occurs, neps: will issue a corresponding warning message to the user.

This command is part of the NEPStools bundle, written to assist with the NEPS dataset files.

The source code of the program is licensed under the GNU General Public License version 3 or later. The corresponding license text can be found on the internet at http://www.gnu.org/licenses/ or in gnugpl.

We like to thank Daniel Klein (INCHER-Kassel),
one of our active and committed NEPS data users,
for his valuable bug hunt and suggestions on how to further improve neps:'s predecessor, nepsuse.

His feedback led to the creation of neps:,
and some of the concepts used in the source code originate from a quite similar, unpublished command he created for his own and his colleagues' use, nepsfile.

Examples

Open the spEmp file of NEPS Starting Cohort 4, version 9.1.1, in its download version:

. neps , study(SC4) version(9.1.1) level(D): use "spEmp"

Open the pTargetCATI dataset from the same SUF, but only data from wave 4:

. neps , study(SC4) version(9.1.1) level(D) : use using "pTarget" if wave==4 , clear

Merge variables with interviewer characteristics from the TargetMethods dataset from the same SUF, in its label language en:

. neps , study(SC4) version(9.1.1) level(D) language(en) : merge 1:1 ID_t wave using "TargetMethods" , keepusing(tx8030?) keep(match master)

Shorten all three examples above by recording preferences with option setup:

. neps , study(SC4) version(9.1.1) level(D) setup : use "spEmp"

. * ... more commands go here ...

. neps : use using "pTargetCATI" if wave==4 , clear

. * ... more commands go here ...

. neps , language(en): merge 1:1 ID_t wave using "TargetMethods" , keepusing(tx8030?) keep(match master)

. * ... more commands go here ...

Same as above, but explicitly using neps set for recording parameters, and invoking neps: afterwards:

. neps set study SC4

. neps set version 9.1.1

. neps set level D

. neps : use "spEmp"

. * ... more commands go here ...

. neps : use using "pTargetCATI" if wave==4 , clear

. * ... more commands go here ...

. neps , language(en): merge 1:1 ID_t wave using "TargetMethods" , keepusing(tx8030?) keep(match master)

. * ... more commands go here ...

Authors

Daniel Bela (daniel.bela@lifbi.de), Leibniz Institute for Educational Trajectories (LIfBi), Germany.

Daniel Klein, INCHER-Kassel.

Also see

NEPStools