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.
-
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.
-
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
-
static