*! version 0.9 01 March 2012
help for euseversion 0.9 (01 March 2012)

Title

euse -- extended use

Table of contents

Syntax
Description
Options
Main options
Options for ASCII import
Options for spreadsheet import
Other options
Remarks
Author
Also see

Syntax

euse [using] filename [, options]

Main
format(string) data format for file import

Options for ASCII import
case preserve variable name's case (ascii_tab, ascii_comma and ascii_semicolon formats only)

[no]names variable names are included on the first line of the file (ascii_tab, ascii_comma, ascii_semicolon
and ascii_custom formats only)

delimiter(char) use char as delimiter (ascii_custom format only)

Options for spreadsheet import
sheet("sheetname") Excel worksheet to load (xml_excel, ooxml and excel formats only)

sheetnum(n) Excel worksheet number to load (ooxml and excel formats only)

cells(upper-left:lower-right) Excel cell range to load (xml_excel format only)

cellrange([start][:end]) Excel cell range to load (ooxml and excel formats only)

firstrow treat first row of Excel data as variable names (xml_excel, ooxml and excel formats only)

allstring import all Excel data as strings (xml_excel, ooxml and excel formats only)

datestring import Excel dates as strings (xml_excel format only)

missing treat inconsistent Excel types as missing (xml_excel format only)

nocompress do not compress Excel data (xml_excel format only)

Other options
novallabels ignore accompanying formats.xpf file if it exists (sas format only)

clear replace data in memory without warning

verbose give verbose output

Description

euse is a wrapper for Stata's most common file import commands. Currently, it can replace the commands use, insheet, import excel,
import sasxport (formerly: fdause) and xmluse.

For ease of use, euse provides one single command to read various dataset formats. It determines which of Stata's import commands to use by the format option,
or, if not specified, by parsing the filename's file extension. Thereby, it can pass through various commonly used options to the appropriate file import routine.

Options

Main

format(format) file format to read the using file from.

If not specified, the appropriate format is guessed by the given file extension, if any. If this is not possible, stata format is used.

Supported formats are:

stata: Stata file format (typical extension: dta). This is equivalent to running the command use.

This is the default if no format is specified and the file extension is dta.

ascii_tab: ASCII format, tab-separated (typical extension: txt or dat). This is equivalent to running the command insheet.

This is the default if no format is specified and the file extension is dat.

ascii_comma: ASCII format, comma-separated (typical extension: txt or csv). This is equivalent to running the command insheet.

This is the default if no format is specified and the file extension is txt or csv.

ascii_semicolon: ASCII format, semicolon-separated (typical extension: txt or csv). This is equivalent to running the command insheet with option delimiter(;).

This is needed to seamlessly import a CSV file produced by Microsoft Excel. Note that it may be easier to use one of the formats ooxml, excel or xml_excel (whilst ooxml is recommended in this case).

ascii_custom: ASCII format, separated by custom character. This is equivalent to running the command insheet.

You need to specify the delimiter option for this format, or it will be changed to ascii_tab.

ooxml: Microsoft Excel spreadsheet format, version of Microsoft Office 2007 or newer (typical extension: xlsx) - also known as Office Open XML (OOXML).
This is equivalent to running the command import excel. This is the recommended option for importing spreadsheets.

This is the default if no format is specified and the file extension is xlsx, and will be overridden if the file extension is xls.

excel: Microsoft Excel spreadsheet format, version prior to Microsoft Office 2007 (typical extension: xls).
This is equivalent to running the command import excel.
This is not recommended unless you have to import from old Excel versions, in any other case please consider using the ooxml format.

It is the default if no format is specified and the file extension is xls, and will be overridden if the file extension is xlsx.

sas: SAS XPORT format (typical extension: xpt). This is equivalent to running the command import sasxport (in Stata 12 or newer) or fdause (older Stata versions).

This is the default if no format is specified and the file extension is xpt.

xml_stata: XML file format, Stata DTD (typical extension: xml). This is equivalent to running the command xmluse with option doctype(dta).

xml_excel: XML file format, Microsoft SpreadsheetML DTD (typical extension: xml). This is equivalent to running the command xmluse with option doctype(excel).

This is the default if no format is specified and the file extension is xml.

Options for ASCII import

case preserves the variable name's case.
This option is only valid with one of the formats ascii_tab, ascii_comma or ascii_semicolon,
and will be passed to the appropriate import command. See the corresponding help file for details:
insheet

[no]names variable names are included on the first line of the file.
This option is only valid with one of the formats ascii_tab, ascii_comma, ascii_semicolon or ascii_custom,
and will be passed to the appropriate import command. See the corresponding help file for details:
insheet

demiliter(char) use char as delimiter.
This option is only valid with the ascii_custom format, and mandatory for this format;
it will be passed to the appropriate import command. See the corresponding help file for details:
insheet

Options for spreadsheet import

sheet("sheetname") Excel worksheet to load.
This option is only valid with one of the formats xml_excel, ooxml or excel,
and will be passed to the appropriate import command. Refer to the corresponding help files for details:
import excel, xmluse

sheetnum(n) Excel worksheet number to load.
This option is only valid with one of the formats ooxml or excel.
If specified and n positive, the nths worksheet of the Excel file will be imported. This is achieved by first
running import excel, describe on the spreadsheet and implicitly setting the sheet option appropriately.

"cells(upper-left:lower-right)" Excel cell range to load.
This option is only valid with the xml_excel format,
and will be passed to the appropriate import command. Refer to the corresponding help file for details:
xmluse

"cellrange([start][:end])" Excel cell range to load.
This option is only valid with one of the formats ooxml or excel,
and will be passed to the appropriate import command. Refer to the corresponding help file for details:
import excel

firstrow specifies that the first row of data in the Excel worksheet consists of variable names.
This option is only valid with one of the formats xml_excel, ooxml or excel,
and will be passed to the appropriate import command. Refer to the corresponding help files for details:
import excel, xmluse

allstring forces Stata to import all Excel data as string data.
This option is only valid with one of the formats xml_excel, ooxml or excel,
and will be passed to the appropriate import command. Refer to the corresponding help files for details:
import excel, xmluse

datestring forces all Excel SpreadsheetML date formats to be imported as strings.
This option is only valid with the xml_excel format,
and will be passed to the appropriate import command. Refer to the corresponding help file for details:
xmluse

missing forces any inconsistent data types within SpreadsheetML columns to be imported as missing data.
This option is only valid with the xml_excel format,
and will be passed to the appropriate import command. Refer to the corresponding help file for details:
xmluse

nocompress specifies that data not be compressed after loading from an Excel SpreadsheetML file.
This option is only valid with the xml_excel format,
and will be passed to the appropriate import command. Refer to the corresponding help file for details:
xmluse

Other options

novallabels ignore accompanying formats.xpf file if it exists.
This option is only valid with the sas format,
and will be passed to the appropriate import command. Refer to the corresponding help file for details:
import sasxport (Stata 12 or newer) or fdause (older verions of Stata)

clear if the dataset currently in memory is not saved, replace it without warning. If not specified, an error message is triggered in such cases.

verbose drops verbose output during the process. Eventually needed for debugging.

Remarks

In order to use the export formats ooxml or excel, Stata 12 (or newer) is required. If this is not the case, Stata 10 is required.

It is recommended that even if you use Windows, you use forward slashes (/) rather than backward slashes (\) for specifying directory names.
Stata will understand and there will then be no clash with other meanings for the backward slash.

This command is part of the NEPmgmt bundle, written to help creating 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.

Author

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

Also see

Help: NEPSmgmt, esave, import, import excel, import sasxport, insheet, use, xmluse