*! version Oktober 26, 2017 @ 12:04:00

Title

psid -- Create and retrieve PSID data

Syntax

psid install
[ wavelist ]
[ using ]
[ ,
install_options
]

psid install
using
[ , cnef
install_options
]

psid use ||
newstub varspecs
using
[,
options use_options
]

psid add ||
newstub varspecs
[using]
[,
options
]

psid long

psid vardoc
varname
[ ,
vardoc_options
]

Main
dofile(filename, ...) Document retrival in a do-file

ftype(cnef|wealth) Access simplified syntax

keepnotes Keep notes of orig. varnames

lower Varnames of PSID files are lower case

waves(wavelist) Waves to be retrived

Use options
design(designtype) Design; default: design(balanced)

clear Replace data in memory

Install options
to(dirname) dta-directory; default: to(.)

cnef Install CNEF instead of PSID

replace Rebuild dta-files already installed

upgrade Download new CNEF delivery from the Internet

lower Make varnames in dta-files lower case

clean Erase downloaded CNEF zip-file after installation

replacelong Overwrites existing CNEF_long data

replacesingle Overwrites existing single year CNEF data

longonly Do not creat single year CNEF data

Vardoc options
addvaluelabel(lblname) Retrieve value labels from the Internet

show Show description in presence of option addvaluelabel

using points to the PSID-directory for psid use
and psid add. It defaults to the directory specified in
psid use for psid add. For psid install,
using specifies the directory holding the downloaded zip-files of
PSID data. It defaults to the working directory. using is
compulsory for psid install with option cnef; see the psid.
newstub and varspecs are described in detail below.

Description

psid is an interface to the "Panel Study of Income
Dynamics" (PSID) and to the American branch of the "Cross National
Equivalence File" (CNEF). It performs the following tasks:

command task

psid install Create Stata datasets from the zip-files
downloadable at http://simba.isr.umich.edu/Zips/ZipMain.aspx without any user
intervention.

psid use Load items from several waves of the PSID or CNEF into memory

psid add Merges items from several waves of the PSID/CNEF to a
PSID/CNEF file in memory

psid long Make data long (and keep the labels)

psid vardoc Displays "official" Online variable description in a browser window

The order in the table above reflects the order of typical use
and the order of the descriptions in this help file.

psid use and psid add are new versions of
psiduse and psidadd that have been available on SSC for years.
These older programs are bundled with the present program for
compatibility reasons. However, psiduse is no longer maintained
and should not be used for new projects.

Syntax of psid install

psid install
[ wavelist ]
using
[ ,
install_options
]

Install options
to(dirname) dta-directory; default: to(.)

cnef Install CNEF instead of PSID

replace Rebuild dta-files already installed

upgrade Download new CNEF delivery from the Internet

lower Make varnames in dta-files lower case

clean Erase downloaded CNEF zip-file after installation

replacelong Overwrites existing CNEF_long data

replacesingle Overwrites existing single year CNEF data

longonly Do not create single year CNEF data

Description of psid install

psid install is used to install the various datasets of
the PSID or the CNEF to the specified directory. While the
installation is fully automatic for the CNEF, some pre-requites must
be met for the PSID. The following first describes the procedure for
PSID.

psid install without the option cnef creates Stata
datasets of the PSID and stores them into a specified directory. This
sounds somewhat easier than it is, because the PSID data base is
spread into numerous files, which are distributed as ASCII text files
bundled together with batch jobs to create datasets in various
formats. By and large there is one zip-file for each year since 1968,
and some further files of interest. psid install, as it stands,
works for the files downloadable for registered PSID users from the
PSID's main interview download site, and for selected
supplemental files.
Note that researchers need to register on psid.org to download the zip
files.

type filenames

Main interview data

Family fam1968.zip, fam1969.zip ... famCCYY.zip

Cross-year individual indCCYY.zip

Parent identification pidYY.zip

Marriage history mh85_YY.zip, and

Childbirth and adaption history cah85_YY.zip

Supplemental files

Wealth wlth1984.zip, wlth1989.zip, ..., wlth2007.zip

Aside but very important: You need to install the cross year
individual file (indCCYY.dta), to be able to use the other programs of
psidtools

The idea of psid install is that the user downloads the
zip-files and lets psid install do the rest. For an example
consider a user who downloaded some (or all) PSID zip-files into the
directory "c:/data/downloads". In this case, the command

. psid install using c:/data/downloads

would ...

o unpack the downloaded PSID zip-files,

o make some necessary edits in the unpacked Stata do-files,

o run the do-files that create the Stata datasets,

o change the variable labels of the Stata datasets to have the first
letter capitalized, and all other letters converted to lowercase,

o compress the created Stata data sets,

o save the Stata file into the current working directory, and

o erase all files generated on the fly.

The usage of the program in the above example is reasonable for
those who wish to install the Stata datasets of the PSID the first
time. However, more experienced users of the PSID can customize the
installation of PSID datasets by specifing a wavelist of years
that should be installed (see below) and/or by specifying the
directory into which the Stata datasets are installed; see option
to(). It is also possible to downcase the names of the variables
in the Stata datasets using the option lower.

By default, psid install creates Stata datasets for all
PSID zip-files found in the using directory unless a specific dataset
has been already installed. Datasets that have been already installed
are ignored. Due to this functionality, installing the datasets for a
new data delivery will only install the new files, while leaving the
old files untouched; however see option replace, below.

It is also possible to specify a wavelist, i.e, a
numlist of waves to be added. For example, the command

. psid install 1974(1)1980 using c:/data/downloads

only installs files for the years 1974 to 1980, regardless of
other PSID zip-files in the using directory.

psid install with the option cnef installs the CNEF
to be accessible for psid use and psid add. Users have to
downlaod a ZIP-file of the CNEF data on
http://cnef.ehe.osu.edu/cnef-data-files/. The downloaded file
must be specified in with using, Thus,

. psid install using c:/downloads/foo.zip, cnef

unpacks the downloaded file zoo.zip, and, installs CNEF file(s) in the
current working directory. using is required with option CNEF.

Options of psid install

to(dirname) specifies the name of the directory in which
the Stata datasets should be stored. If not specified, the current
working directory will be used; see help pwd.

replace is used to replace Stata datasets that have been
created by a previous run of the program with newly created
dataset. By default, psid install ignores datasets that have
been created already. If one wishes to update an existing Stata
dataset with, say, a corrected delivery, the option replace must
be used. Option replace with option cnef implies options
replacelong and replacesingle.

lower The "original" PSID data delivery do-files create
upper cased variable names. For Stata users upper cased variable names
are a bit clumsy, so it is reasonable to use the option lower to
downcase the variable names in all generated datasets. However, if the
PSID datasets are accessed through psid use and/or psid add
the usage of this option is not recommended. Option lower
cannot be used togehter with option cnef

upgrade can be only used with option cnef. By
default, psid install, cnef does not unpack a newly download zip-file if
if a CNEF delivery is already present in the
installation directory. With option upgrade that delivery
will be replaced by the newly downloaded one.

longonly Starting with the data delivery 2009, the CNEF is being delivered in
long format, i.e. the data of all waves are being stored in one single Stata dataset. However,
the PSID-Tools expect data stored in one dataset for each wave. psid intall, cnef thus creates
single year datasets by default. The creation of single year dataset can be turned off with
option longonly.

clean was used in older versions psid install, cnef. The option is still allowed but
does nothing.

replacelong was used in older versions psid install, cnef. The option is still allowed but
does nothing.

replacesingle can be only used with option cnef. By
default, psid install, cnef does not create a datasets for a single year, if the
dataset for that year already exists. With option replacesingle existing single year datasets
will be overwritten. Option replace implies replacesingle.

Syntax of psid use and psid add

psid use ||
newstub varspecs
using
[,
options use_options
]

psid add ||
newstub varspecs
[using]
[,
options
]

Main
dofile(filename, ...) Document retrival in a do-file

ftype(cnef|wealth) Access simplified syntax

keepnotes Keep notes of orig. varnames

lower Varnames of PSID files are lower case

waves(wavelist) Waves to be retrived

Use options
design(designtype) Design; default: design(balanced)

clear Replace data in memory

Description of psid use and psid add

To load data from the PSID, psid use and psid add
allow the user to copy-paste output of the PSID Data Center
into Stata. The pasted output will be processed by the commands to
create a Stata dataset that corresponds to the the pasted output. The
difference between psid use and psid add is that the
former creates a new dataset, while the latter merges variables to a
file already generated with psid use.

The way the commands work is best explained with an
example. Consider you have been using the PSID Data Center to search
the PSID data base for items concerning health. After founding a
candidate that might suit your needs you requested further information
to that that item by clicking on the respective button. This brought
up an extract of the codebook of the item which also lists the years
in which the item is available. This so called item correspondence list
looks as follows:

[84]V10877 [85]V11991 [86]V13417 [87]V14513 [88]V15993 [89]V17390 [90]V18721 [91]V20021 [92]V21321 [93]V23180 [94]ER3853 [95]ER6723 [96]ER8969 [97]ER11723 [99]ER15447 [01]ER19612 [03]ER23009 [05]ER26990 [07]ER38202 [09]ER44175 [11]ER49494

The item correspondence list shows the variable names of the
selected item in the various waves of the PSID. It resembles the format
of the varspecs
required by psid use and psid add, and can thus be copied
as is into those commands. Once you did this, you only need to add a
name for the item. This name must be typed behind "||" in front of the
item correspondence list. The psid use command to create a
longitudinal dataset with all variables of the example above will then
become

. psid use || health

[84]V10877 [85]V11991 [86]V13417 [87]V14513 [88]V15993 [89]V17390 [90]V18721 [91]V20021 [92]V21321 [93]V23180 [94]ER3853 [95]ER6723 [96]ER8969 [97]ER11723 [99]ER15447 [01]ER19612 [03]ER23009 [05]ER26990[07]ER38202 [09]ER44175
[11]ER49494

using ~/data/psid

whereby the variables will be renamed to health1984, health1984 ... health2011.

Aside but very important: You must have installed the cross year
individual file (indCCYY.dta), to be able apply psid use

In general, the programs psid use and psid add
create datasets with all the variables identified by the varspecs
renamed to names using a newstub-year convention. Several item
correspondence lists can be specified in one command, and the default
"balanced" panel design can be changed to various other designs; see
option design(). A simplified syntax for
variables from the Wealth files and the Cross National Equivalence
files is also available (see below).

psid use and psid add work for item correspondence
lists that contain variables from the following files:

type filenames

Main interview data

Family fam1968.dta, fam1969.dta ... famCCYY.dta

Cross-year individual indCCYY.dta

Parent identification pidYY.dta

Marriage history mh85_YY.dta, and

Childbirth and adaption history cah85_YY.dta

Supplemental files

Wealth wlth1984.dta, wlth1989.dta, ..., wlth2007.dta

Cross National Equivalence (CNEF) pequiv1968.dta, pequiv1969.dta, ..., pequivCCYY.dta

While this file list resembles the file list that can be
installed with psid install it is not required
that psid install has been actually used to install the
files. It is however necessary that the installed files follow the
file naming conventions shown above. It is also necessary that all
files (except the CNEF-files) are stored in the same directory,
i.e. the PSID directory. These requirements will be met automatically if
the PSID is installed with psid install.

Note that the Stata datasets for
the CNEF can be downloaded directly from the CNEF website. It is thus neither necessary nor possible to install these files with psid install.
Moreover, as the CNEF is not part of the "official" PSID, the CNEF
variables are not listed in the PSID Data Center. In order to access the CNEF variables psid use and psid add offer a simplified syntax, which will
be described below. As a consequence of the simplified
syntax it is however not allowed to list both, CNEF and PSID variables in one single
command. Instead, one should first psid use the PSID variables and
then psid adding the CNEF variables, or the other way around.

Finally note the following peculiarities of
varspecs:

o you must add a set of empty brackets in front of items
that appear only once in the database (i.e. variables that are
constant over time). This is always the case for variables of the
parent identification file, the childhood and adaption history file,
and the marriage history file, but also for some variables of the
cross year individual file.

o you must not specify any person of family identifiers in
the varspecs. These identifiers are retained automatically and
renamed using the convention of the CNEF. The renamed identifiers are
always the first variables of the created dataset.

Simplified Syntax (CNEF and Wealth files)

psid use and psid add require the user to specify
variables of the PSID database in the format of the output of the PSID
Data Center. This is fine for variables that are listed in the PSID
Data Center, but awfully complicated for variables not listed there
and unnecessary in case of file types with a harmonized variable
naming convention. psid use and psid add therefore offers a
simplified syntax for the CNEF files and the Wealth files. The
simplified syntax is mandatory for loading CNEF variables.

psid use ||
newstub varstub
using
, ftype(cnef|wlth) waves(numlist)
[options use_options
]

psid add ||
newstub varstub
[using]
, ftype(cnef|wlth) waves(numlist)
[ options use_options
]

The meanings of all terms are equal to the standard syntax. The
difference to the standard syntax is the use of varstub instead
of varspecs. In order to access the simplified syntax, the
specification of ftype() and waves() is required, which
implies that the standard and simplified syntax cannot be mixed in one
command.

The varstub is the part of the variable name that is
identical in all files of the CNEF and Wealth files, respectively. For
the CNEF the varstubs are the first 6 characters of the variable
names, i.e. the variable names without the year. For the Wealth files
the varstubs are the variable names without the first two digits,
i.e. the variable names with out the "S" and the number that
identifies the round of the data delivery.

The description of the simplified syntax sounds a bit more
complicated than it actually is. For example, to load the pre- and
post government incomes of all waves of the CNEF from, say, 1984 to 2007 one
would use

. psid use || pre i11102 || post i11104 using ~/data/cnef, ftype(cnef) waves(1984/2007)

Likewise, to load the imputed and actual value of vehicles of
all wealth files available between 1984 and 2007 one would use

. psid use || impvehic 13 || impvehicA 13A using ~/data/PSID, ftype(wlth) waves(1984/2007)

In order to extend or shorten the observation period one only
needs to change option wave(), whereby the missing years of
data collection are handled automatically.

Options for psid use/add

dofile(filename [, replace|append force]) specifies the
filename of a do-file that documents the retrival. This can be
helpful if you wish to sent your retrival to colleagues that do not
want to install this command, or to change settings that could not be
changed with the syntax of psid use and psid add. The
sub-options replace and append have the usual meaning,
i.e. the former overwrites an existing file and the latter appends
content to an existing file. The sub-option replace is
considered as pointless for psid add and therefore only possible
if specified with force.

ftype(cnef|wealth) is used to access variables from the
Cross National Equivalence Files or the Wealth files using the
simplified syntax described above. Option
wave() is mandatory if ftype() is specified.

keepnotes helps to keep track of the original variable
names. psid use and psid add automatically rename all
variables using the newstub-year convention. While this renaming
substantially eases the data management of the generated file, it
makes it harder to look up the underlying questions in the
questionnaire or other details in the PSID Data Center. With the option
keepnotes the original variable name is stored as
characteristic of the renamed variable and can be thus looked up with
char list; see help char.
The specification of this option is also a pre-requisite for using psid vardoc.

lower The "original" PSID data delivery do-files create
upper cased variable names. For Stata users, upper cased variable names
are a bit clumsy, so that the files might have been stored with all
variable names changed to lower case. psid use and
psid add expects variable names to be upper cased, but this can be
changed using the option lower. If psid install have been used
with option lower, you must specify the option for psid use and psid add, too.

waves(numlist) is used to specify a numlist for
the waves from which variables should be retrieved. The option is mandatory
if the simplified syntax is requested through
ftype(). For the standard syntax the
waves are implied by the varspecs, and any settings of
waves() will be therefore ignored.

Options for psid use

design(designtype) specifies the design of the panel data
to be created. design(balanced) is used to create a balanced
panel design, i.e. the data will contain only observations interviewed
in all requested waves. design(any) will keep all available
observations in the data set. design(#) with # being an integer
positive number creates data sets with households interviewed # times
or more.

It is important to understand the design of the files created
by psid use. The program always creates a design that uses
individual records. That is to say that the file being created has
observations for each head of the household and observations for the
partners of the heads of the household. An observation is counted as
being interviewed in as specific wave if the "sequence number" of that
wave is either between 1 and 20 or between 81 and 89. The sequence
variable is retained in the dataset in order to allow further
fine-tuning of the design.

It is also important to understand that the longitudinal design of a retrival is fixed by psid use. It is possible to add further waves to an existing dataset with psid add but this will not delete or add any observations to the dataset. It is thus not recommended to use psid add for adding variables of further waves to a dataset. Instead those requested variables should be listed among the varspecs of psid use already.

The numbers of observation of the dataset created by
psid use changes only if a user psid adds variables from one of the
three history files to a file that did not contain variable of any of
those files so far. This is because the history files are actually spell data, so that the unit of analysis changes from individuals to spells.

clear specifies that it is okay to replace the data in
memory, even though the current data have not been saved to disk.

Syntax of psid long

psid long

Description of psid long

psid long reshapes a dataset created by
psid use/psid add into the long data format
(see help reshape).
However, unlike standard reshape, variable labels of time
varying variables do not get lost. psid long also automatically creates
the varname stubs requested by reshape. Finally, it is neither necessary,
nor possible to specify any of the options requested by reshape.
psid long provides all necessary settings as defaults.

psid long selects the first variable label of an item
correspondance list as the variable label in the long data
set. Moreover it uses the individual identifier for the option
i() of reshape and wave as the variable name for the
PSID's time dimension. Finally it stores the item correspondance list
of as a characteristic in the dataset, if these information has been
retained by the option keepnotes of psid use and/or
psid add.

psid long is a convenience program which relives the PSID user
to think about the reshape process. It thus makes certain settings and
does not allow the user to change them. Users who want more flexibility
are requested to use reshape instead.

Syntax of psid vardoc

psid vardoc
varname
[ ,
vardoc_options
]

Vardoc options
addvaluelabel(lblname) Retrieve value labels from the Internet

show Show description in presence of option addvaluelabel

Description of psid vardoc

psid vardoc displays the official variable description of
the PSID Data Center in a browser window. The command is invoked by
specifying the name of the variable for which the discription should
be displayed. The command only works for datasets created
with psid use/psid add and the option keepnotes. The
command can be used in long datasets only if the long dataset was
created with psid long.

Note that the command loads the variable description from the
Internet. The command therefore only works if it is invoked on a
computer with connection to the Internet.

Options for psid vardoc

addvaluelabel(lblname) retrieves the value label
definition of a variable from the official description of the PSID
Data Center. This is helpful because PSID data is being delivered
without value labels. The option addvaluelabel(lblname) of
psid vardoc varname defines the value label
lblname according to the information found in the PSID data
center and attaches this value label to varname.

show The PSID Data Centers variable description will not
being displayed in a Browser-Window if option addvaluelabel is
present. The option show overwrites this behavior.

Examples

Create Stata dataset from zip file in the directory
"~/Downloaded" and store them into the directory "~/data/PSID":

. psid install using "~/Downloaded", to("~/data/PSID")

Add the wave 1985 to already installed PSID data.

. psid install 1985 using "~/Downloaded", to("~/data/PSID")

Create a longitudinal file with health status of the household head

. psid use || health [84]V10877 [85]V11991 [86]V13417 using ~/data/PSID

Constructing Longitudinal Records of the CNEF 1980-2007

. psid use || pregov i11101 || postgov i11102 using ~/data/PSID/cnef07, ftype(cnef) waves(1980/2007)

Include a variable that is constant across waves

. psid use || health [84]V10877 || age [84]ER30432 || deathyr []ER32050 using ~/data/PSID}

A more practical example for a longitudinal data set with several items from the PSID and the CNEF.

. psid use

|| shealth [84]V10877 [85]V11991 [86]V13417 [87]V14513

[88]V15993 [89]V17390 [90]V18721 [91]V20021 [92]V21321

[93]V23180 [94]ER3853 [95]ER6723 [96]ER8969 [97]ER11723

[99]ER15447 [01]ER19612 [03]ER23009 [05]ER26990

|| age [68]ER30004 [69]ER30023 [70]ER30046 [71]ER30070

[72]ER30094 [73]ER30120 [74]ER30141 [75]ER30163 [76]ER30191

[77]ER30220 [78]ER30249 [79]ER30286 [80]ER30316 [81]ER30346

[82]ER30376 [83]ER30402 [84]ER30432 [85]ER30466 [86]ER30501

[87]ER30538 [88]ER30573 [89]ER30609 [90]ER30645 [91]ER30692

[92]ER30736 [93]ER30809 [94]ER33104 [95]ER33204 [96]ER33304

[97]ER33404 [99]ER33504 [01]ER33604 [03]ER33704 [05]ER33804

|| disable [72]V2718 [73]V3244 [74]V3666 [75]V4145 [76]V4625

[77]V5560 [78]V6102 [79]V6710 [80]V7343 [81]V7974 [82]V8616

[83]V9290 [84]V10879 [85]V11993 [86]V13427 [87]V14515

[88]V15994 [89]V17391 [90]V18722 [91]V20022 [92]V21322

[93]V23181 [94]ER3854 [95]ER6724 [96]ER8970 [97]ER11724

[99]ER15449 [01]ER19614 [03]ER23014 [05]ER26995

using ~/data/PSID , clear design(10)}

. psid add || pregov i11101 || postgov i11102, cnef(~/data/PSID/cnef07)

Make the data of the previous retrival long

. psid long

Label the variable disable from the last retrival with a value label defined according to the variable descritpion of the PSID Data Center.

. psid vardoc disable, addvaluelabel(yesno)

Acknowledgements

I whish to thank the PSID Management Team for allowing me to use
the name psid for the program. Jan Paul Heisig, Martin Ehlert
and Anke Radenacker, my former colleagues at the Social Science
Research Center (WZB) have thoroughly tested a previous version of
this command. I owe them much. David Brady (WZB) encouraged me --
without even knowing -- to transform psiduse to psid use.
Josephine Matysiak, Adrian Rolf (University of Potsdam) and Lai
Xiongchuan (National University Singapore) volunteered as pre-alpha,
alpha, and beta tester. John Haisken-DeNew (Melbourne Institue of
Applied Economic and Social Research) gave me a first version of the
code for the do-file option. Thanks a lot to all of them.

Author

Ulrich Kohler, University of Potsdam, Germany

email: ukohler@uni-potsdam.de