SFIToolkit (sfi.SFIToolkit)

class sfi.SFIToolkit

This class provides a set of core tools for interacting with Stata.

Method Summary

abbrev(s[, n]) Return s abbreviated to n display columns.
display(s[, asis]) Output a string to the Stata Results window.
displayln(s[, asis]) Output a string to the Stata Results window and automatically add a line terminator at the end.
eclear() Clear Stata’s e() stored results.
error(rc) Output the standard Stata error message associated with return code rc to the Stata Results window.
errprint(s[, asis]) Output a string to the Stata Results window as an error.
errprintDebug(s[, asis]) Output a string to the Stata Results window as an error if set debug on is enabled.
errprintln(s[, asis]) Output a string to the Stata Results window and automatically add a line terminator at the end.
errprintlnDebug(s[, asis]) Output a string to the Stata Results window as an error if set debug on is enabled, and automatically add a line terminator at the end.
exit([rc]) Terminate execution and set the overall return code to rc.
formatValue(value, format) Format a value using a Stata format.
getCallerVersion() Get the version number of the calling program.
getRealOfString(s) Get the double representation of a string using Stata’s real() function.
getTempFile() Get a valid Stata temporary filename.
getTempName() Get a valid Stata temporary name.
getWorkingDir() Get the current Stata working directory.
isFmt(fmt) Test if a format is a valid Stata format.
isNumFmt(fmt) Test if a format is a valid Stata numeric format.
isStrFmt(fmt) Test if a format is a valid Stata string format.
isValidName(name) Check if a string is a valid Stata name.
isValidVariableName(name) Check if a string is a valid Stata variable name.
macroExpand(s) Return s with any quoted or dollar sign–prefixed macros expanded.
makeVarName(s[, retainCase]) Attempt to form a valid variable name from a string.
pollnow() Request that Stata poll its GUI immediately.
pollstd() Request that Stata poll its GUI at the standard interval.
rclear() Clear Stata’s r() stored results.
sclear() Clear Stata’s s() stored results.
stata(s[, echo]) Execute a Stata command.
strToName(s[, prefix]) Convert a string to a Stata name.

Method Detail

static abbrev(s, n=None)

Return s abbreviated to n display columns. Usually, this means it will be abbreviated to n characters, but if s contains characters requiring more than one display column, such as Chinese, Japanese, and Korean (CJK) characters, s will be abbreviated such that it does not exceed n display columns.

  • n is the abbreviation length and is assumed to contain integer values in the range 5, 6, …, 32.
  • If s contains a period, ., and n < 8, then the value n defaults to 8. Otherwise, if n < 5, then n defaults to 5.
  • If n is not specified, the entire string is returned.
Parameters:
  • s (str) – The string to abbreviate.
  • n (int, optional) – The abbreviation length.
Returns:

An abbreviated string.

Return type:

str

Raises:

ValueError – If n is out of range.

static display(s, asis=False)

Output a string to the Stata Results window. Before the string is printed, it is run through the Stata SMCL interpreter.

Parameters:
  • s (str) – The string to output.
  • asis (bool, optional) – When True, the string is printed without using the Stata SMCL interpreter. Default is False.
static displayln(s, asis=False)

Output a string to the Stata Results window and automatically add a line terminator at the end. Before the string is printed, it is run through the Stata SMCL interpreter.

Parameters:
  • s (str) – The string to output.
  • asis (bool, optional) – When True, the string is printed without using the Stata SMCL interpreter. Default is False.
static eclear()

Clear Stata’s e() stored results.

static error(rc)

Output the standard Stata error message associated with return code rc to the Stata Results window.

Parameters:rc (int) – The return code for the error.
Raises:ValueError – If rc is negative.
static errprint(s, asis=False)

Output a string to the Stata Results window as an error. Before the string is printed, it is run through the Stata SMCL interpreter.

Parameters:
  • s (str) – The string to output.
  • asis (bool, optional) – When True, the string is printed without using the Stata SMCL interpreter. Default is False.
static errprintDebug(s, asis=False)

Output a string to the Stata Results window as an error if set debug on is enabled.

Parameters:
  • s (str) – The string to output.
  • asis (bool, optional) – When True, the string is printed without using the Stata SMCL interpreter. Default is False.
Returns:

True if set debug on is enabled.

Return type:

bool

static errprintln(s, asis=False)

Output a string to the Stata Results window and automatically add a line terminator at the end. Before the string is printed, it is run through the Stata SMCL interpreter.

Parameters:
  • s (str) – The string to output.
  • asis (bool, optional) – When True, the string is printed without using the Stata SMCL interpreter. Default is False.
static errprintlnDebug(s, asis=False)

Output a string to the Stata Results window as an error if set debug on is enabled, and automatically add a line terminator at the end.

Parameters:
  • s (str) – The string to output.
  • asis (bool, optional) – When True, the string is printed without using the Stata SMCL interpreter. Default is False.
Returns:

True if set debug on is enabled.

Return type:

bool

static exit(rc=0)

Terminate execution and set the overall return code to rc. exit() with no argument is equivalent to exit(0).

Parameters:rc (int, optional) – The overall return code. Default is 0.
Raises:ValueError – If rc is negative.
static formatValue(value, format)

Format a value using a Stata format.

Parameters:
  • value (float) – The value to format.
  • format (str) – A valid Stata format.
Returns:

The formatted value in string form.

Return type:

str

Raises:

ValueError – If format is not a valid Stata numeric format.

static getCallerVersion()

Get the version number of the calling program. This function can be used to implement Stata version control.

Returns:The caller’s version number.
Return type:float
static getRealOfString(s)

Get the double representation of a string using Stata’s real() function.

Parameters:s (str) – The string to convert.
Returns:The numeric value. If the numeric value is a Stata missing value or the string cannot be converted to a numeric value, the Stata system missing value is returned.
Return type:float
static getTempFile()

Get a valid Stata temporary filename.

Returns:The filename, including its path.
Return type:str
static getTempName()

Get a valid Stata temporary name.

Returns:The tempname.
Return type:str
static getWorkingDir()

Get the current Stata working directory.

Returns:The path of the current working directory.
Return type:str
static isFmt(fmt)

Test if a format is a valid Stata format.

Parameters:fmt (str) – The format to test.
Returns:True if the format is a valid Stata format.
Return type:bool
static isNumFmt(fmt)

Test if a format is a valid Stata numeric format.

Parameters:fmt (str) – The format to test.
Returns:True if the format is a valid Stata numeric format.
Return type:bool
static isStrFmt(fmt)

Test if a format is a valid Stata string format.

Parameters:fmt (str) – The format to test.
Returns:True if the format is a valid Stata string format.
Return type:bool
static isValidName(name)

Check if a string is a valid Stata name.

Parameters:name (str) – Name to test.
Returns:True if the string represents a valid Stata name.
Return type:bool
static isValidVariableName(name)

Check if a string is a valid Stata variable name.

Parameters:name (str) – Name to test.
Returns:True if the string represents a valid Stata variable name.
Return type:bool
static macroExpand(s)

Return s with any quoted or dollar sign–prefixed macros expanded.

Parameters:s (str) – The string to expand.
Returns:A string with macros expanded.
Return type:str
static makeVarName(s, retainCase=False)

Attempt to form a valid variable name from a string.

Parameters:
  • s (str) – Source string.
  • retainCase (bool, optional) – Preserve the case or convert variable name to lowercase. If set to True, the case will not be converted to lowercase. Default is False.
Returns:

The new variable name. Returns an empty string if a valid name was not created.

Return type:

str

static pollnow()

Request that Stata poll its GUI immediately. Use this method inside a time-consuming task so that the Stata interface is responsive to user inputs. Generally, pollstd() should be used instead.

Raises:BreakError – This error is raised when the Break key is pressed in Stata.
static pollstd()

Request that Stata poll its GUI at the standard interval. Use this method inside a time-consuming task so that the Stata interface is responsive to user inputs.

Raises:BreakError – This error is raised when the Break key is pressed in Stata.
static rclear()

Clear Stata’s r() stored results.

static sclear()

Clear Stata’s s() stored results.

static stata(s, echo=False)

Execute a Stata command.

Parameters:
  • s (str) – The command to execute.
  • echo (bool, optional) – Echo the command. Default is False.
static strToName(s, prefix=False)

Convert a string to a Stata name. Each character in s that is not allowed in a Stata name is converted to an underscore character, _. If the first character in s is a numeric character and prefix is specified and True, then the result is prefixed with an underscore. The result is truncated to 32 characters.

Parameters:
  • s (str) – The string to convert.
  • prefix (bool, optional) – Prefix with an underscore. Default is False.
Returns:

A valid Stata name.

Return type:

str