*! version 1.2.1 04 May 2018
help for nepsuseversion 1.2.1 (04 May 2018)

Warning: nepsuse is deprecated; please consider migrating your syntax to use its successor, neps.

See help neps for details on this more powerful command.

Title

nepsuse -- Conveniently open a NEPS Scientific Use File (SUF) dataset

Table of contents

Syntax
Description
Options
Remarks
Examples
Authors
Also see

Syntax

Load NEPS Scientific Use File dataset

nepsuse NEPS dataset name [, options]

Load subset of NEPS Scientific Use File dataset

nepsuse [varlist] [if] [in] using NEPS dataset name [, options]

Pre-record option preferences for all further nepsuse invocations in this Stata session:

nepsuse [varlist] [if] [in] [using NEPS dataset name] [, options] setup

Display previously recorded option preferences (if any), and version information, then exit:

nepsuse

Main
directory(dirname) directory name of the file to open

cohort(shortcode) NEPS Starting Cohort short code (e.g. SC6)

version(version number) NEPS SUF dataset version (e.g, 6.0.1)

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

language(language code) language to open the dataset in (e.g. en)

Advanced
setup set manually speficied options as global macros for further use in the Stata session

other all options for Stata's use are allowed and will be passed to use itself

Description

nepsuse is a wrapper for Stata's regular command use.
It eases access to datasets from NEPS Scientific Use Files (SUFs) from within Stata by automatically concatenating the file name of the target file.
This enables NEPS users to only code

. nepsuse "pTarget"

where Stata's default use would need

. use "/any/directory/name/SC6_pTarget_D_6-0-1.dta"

All parts of the file path needed by use, besides the pure NEPS file title (e.g. pTarget in the above illustration) can either be specified manually as options,
or defined as global macros (i.e. ${NEPSuse_optionname}). nepsuse will take care of file path concatenation.

Options

Main

directory(dirname) is optional; if specified, dirname will be used to concatenate the file path (instead of the current working directory).

Will be automatically filled if the global macro ${NEPSuse_directory} is defined.

cohort(shortcode) is mandatory; shortcode is a NEPS Starting Cohort short code.

Will be automatically filled if the global macro ${NEPSuse_cohort} is defined; in this case, the option can be omitted.

version(version number) is mandatory; version number is a version number of a NEPS Scientific Use file.

Will be automatically filled if the global macro ${NEPSuse_version} is defined; in this case, the option can be omitted.

level(anonymisation level) is mandatory; 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.

Will be automatically filled if the global macro ${NEPSuse_level} is defined; in this case, the option can be omitted.

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

Will be automatically filled if the global macro ${NEPSuse_language} is defined.

Advanced

setup if specified, nepsuse will save all manually specified options as global macros in the Stata session.

On further invocations of nepsuse, these pre-saved options will automatically be read, eliminating the need to re-specify each option in the session.

This is a shorthand for manually defining the global macros at the beginning of a session, and re-using them afterwards.

When this option is used, invoking nepsuse without a file name specification is

other options will silently be passed to Stata's use itself.
Please refer to the corresponding help file for a list of allowed options.

Remarks

While nepsuse eases opening NEPS SUF dataset files, entering all parameters manually upon each and any occasion of opening a file might be cumbersome.
Thus, nepsuse features a way for automatically reading each option from a global macro named ${NEPSuse_optionname}.
This enables the user to only define, say, the NEPS Starting Cohort in question once.

This means that invoking

. nepsuse "pTarget" , cohort("SC6") ...

. nepsuse "spEmp" , cohort("SC6") ...

is identical to writing

. global NEPSuse_cohort "SC6"

. nepsuse "pTarget" , ...

. nepsuse "spEmp" , ...

This is helpful for do-files that have to open several datasets, so that nepsuse's parameters can be defined once at the beginning of the do-file.

Upon user request, the option setup has been implemented as a variant of the latter example above. It enables a work flow where the options are manually set once, and a global macro is automatically recorded for further use:

. nepsuse "pTarget" , cohort("SC6") setup ...

. nepsuse "spEmp" , ...

When nepsuse is invoked without arguments, it will display version information and information about all previously recorded option preferences, and exit.

Note that if both a global macro ${NEPSuse_optionname} and a manual option optionname() statement are used, the manual option always takes precedence.

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 (University of Kassel), one of our active and committed NEPS data users, for his valuable bug hunt and suggestions on how to further improve nepsuse.

His feedback led to version 1.2, which fixes several issues in special use cases, and adds the option setup to the command.

Examples

Open the spEmp file of NEPS Starting Cohort 6, version 6.0.1, in its download version:

. nepsuse "spEmp" , cohort(SC6) version(6.0.1) level(D)

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

. nepsuse using "pTarget" if wave==4 , cohort(SC6) version(6.0.1) level(D) clear

Open the Methods dataset from the same SUF, but only data from wave 4 and variables ID_t wave inty intm intd, and activate its label language en:

. nepsuse ID_t wave inty intm intd using "Methods" if wave==4 , cohort(SC6) version(6.0.1) level(D) language(en) clear

Shorten all three examples above by pre-defining parameters as global macros, and invoking nepsuse afterwards:

. global NEPSuse_cohort SC6

. global NEPSuse_version 6.0.1

. global NEPSuse_level D

. nepsuse "spEmp"

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

. nepsuse using "pTarget" if wave==4 , clear

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

. nepsuse ID_t wave inty intm intd using "Methods" if wave==4 , language(en) clear

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

Same as above, but with using the option setup to pre-save the global macros:

. nepsuse , setup cohort(SC6) version(6.0.1) level(D)

. nepsuse "spEmp"

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

. nepsuse using "pTarget" if wave==4 , clear

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

. nepsuse ID_t wave inty intm intd using "Methods" if wave==4 , language(en) clear

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

Authors

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

Also see

neps, NEPStools, use, label language