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

Previous topic

Next topic

SFIToolkit (sfi.SFIToolkit)¶