*! version 0.1.3 16 May 2022

mpitb refsh -- creates or updates the reference sheet

Syntax

mpitb refsh using
filename , id(name) path(string)
[options]

* id(name) country ID in reference sheet

† path(path) path to cleaned micro data

† file(filename) filename of cleaned micro data

char(clist) data characteristics to collect

keep(keeplist) variables to keep

sid(name) ID for sub-national units within countries

clear replace only potentially existing reference sheet

newfiles search for new files and add to reference sheet

update(ctylist) update reference sheet

depind(dlist) collect information on deprivation indicators

gentvar(year) generate time variable

* required options; † one of these options is required.

Description

mpitb refsh creates or updates the reference sheet, a key feature of the
global MPI workflow. The reference sheet contains basic information about the
countries covered by the current project. The reference may be used (i) to control
estimation and other production routines efficiently, (ii) for merging external
data easily, (iii) reducing the amount of information that estimates are passed
through the estimation routine. See the workflow for more
details.

Essentially, mpitb refsh examines all micro datasets in the specified folder
and collects certain information (data characteristics or variables). Afterwards
mpitb refsh creates the reference sheet comprising this information for each
country.

Options

id(name) specifies the identifier of a particular dataset and is usually an
ISO country code. By default, name is assumed to be a variable name. If, however,
option char(clist) is set, name may be a data characteristic, too.
The reference sheet will contain at least one observation for each ID (or dataset).

path(path) specifies the path to the cleaned micro datasets. Note that path
has to be specified as folder/subfolder using slashes "/" and not backslashes "\".

file(filename) specifies the file of the cleaned micro dataset.
This option may not be combined with options path(path), update(clist)
or newfiles.

clear examines every dta file in the specified path for being included into
the reference sheet and replaces any potentially already existing reference sheet.
Usually, this option is the most convenient.

newfiles searches for new files in the specified path and adds them to the reference
sheet if encountered. The old entries for this country will be replaced. This option
is rarely used.

update(clist) updates the reference for selected countries. Usually clist
would be country codes and refer to values of the variable specified in id(name)
This option is rarely used.

sid(sid) specifies a secondary ID for subgroups within a country (or dataset),
which is usually the subnational region variable. Unlike most other subgroups,
coding and labels of regions tend to vary across countries. The reference sheet will
contain one observation for each region of a given country.

If mpitb refsh encounters a region variable containing only missing values,
it only adds a single entry for this country to the reference sheet, whereas a dataset
is entirely skipped if the specified variable is not found at all. This convention
allows to distinguish countries for which the survey does not allow subnational
disaggregation from countries which are not supposed to be included in particular
analysis.

keep(namelist) allows to specify variables in the micro dataset, which are kept
and stored in the reference sheet. These variables are assumed to be constant across
all observations in the micro dataset (and missing values will be ignored). This
option allows to pass further information from the micro data files to the reference
sheet (and from there to the results file). Use cases may be country codes, survey
names or years. Usually, using the option char is preferable, though.

char(clist) specifies a list of data characteristics (see char)
of the micro data, which will be retained and added as variables to the reference sheet.

depind(dlist) collects information on deprivation indicators, where dlist
is a list of all deprivation indicators supposed to be covered. If this option is set
the mpitb refsh adds the number of indicators found in each dataset and the
names of missing indicators.

gentvar(year) generates an integer time variable, which identifies the data
rounds for each country based on the variable (or characteristic) year.

Remarks

1. Data characteristics are convenient to store information with a dataset that does
not vary across observation as it may reduce file sizes significantly. If you wanted
your reference sheet to include a variable ccty holding an ISO country code,
you could store this information with the micro dataset itself as follows:

char _dta[ccty] "XYZ"

2. If some of your countries cannot be disaggregated by region, create the
region variable with missing values for all observations. mpitb refsheet
will include a single observation for the national level into the reference sheet.

Examples

1. Assume you have all micro data files stored in the folder cdta, which contains
data characteristics ccty, survey and year, and a variable region.
To create the reference sheet for this setup, you may issue

mpitb refsh using refsh.dta , clear char(ccty survey year) id(ccty) sid(region) path(cdta)