The config module (pystata.config)¶

This module includes features that are part of StataNow.

This module is used to configure the system and display current system information and settings.

Method Summary

`init`(edition[, splash])	Initialize Stata’s environment within Python.
`is_stata_initialized`()	Check whether Stata has been initialized.
`status`()	Display current system information and settings.
`set_graph_format`(gformat[, perm])	Set the file format used to export and display graphs.
`set_graph_size`([width, height, perm])	Set the graph size for images to be exported and displayed.
`set_graph_show`(show[, perm])	Set whether the graphs generated by Stata are to be exported and displayed.
`set_command_show`(show[, perm])StataNow	Specify whether to echo the commands in the output.
`set_autocompletion`(flag[, perm])StataNow	Set whether to enable the autocompletion feature within an IPython environment.
`set_streaming_output`(flag[, perm])StataNow	Set whether to display Stata’s output while Stata is executing.
`set_output_file`(filename[, replace])	Write Stata output to a text file.
`close_output_file`()	Stop writing Stata output to a text file.

Method Detail

pystata.config.init(edition, splash=True)¶

Initialize Stata’s environment within Python.

Parameters

edition (str) – The Stata edition to be used. It can be one of mp, se, or be.
splash (bool, optional) –
Suppress displaying the splash message after Stata is successfully initialized. Default is True. When set to False, the splash will be suppressed.

New in version 0.1.1.

pystata.config.is_stata_initialized()¶

Check whether Stata has been initialized.

Returns: True if Stata has been successfully initialized.
Return type: bool

pystata.config.status()¶: Display current system information and settings.

pystata.config.set_graph_format(gformat, perm=False)¶

Set the file format used to export and display graphs. By default, graphs generated by Stata are exported and displayed as SVG files.

The supported formats are svg, png, and pdf. If svg or png is specified, the graph is embedded. If pdf is specified, the graph is exported to a PDF file in the current working directory with a numeric name, such as 0.pdf, 1.pdf, 2.pdf, etc. This is useful when you try to export a notebook to a PDF via LaTex and you want the graph to be embedded.

Parameters

gformat (str) – The graph format. It can be svg, png, or pdf.
perm (bool, optional) – When set to True, in addition to making the change right now, the setting will be remembered and become the default setting when you invoke Stata. Default is False.

pystata.config.set_graph_size(width=None, height=None, perm=False)¶

Set the graph size for images to be exported and displayed. By default, the graphs generated by Stata are exported using a dimension of 7.5 inches for the width by 4.5 inches for the height. Either the width or height must be specified, and both may be specified. If only one is specified, the other one is calculated from the aspect ratio.

The width or height can be specified as a floating-point number, a string with a floating-point number and its unit, or default. The supported units are inches (in), pixels (px), or centimeters (cm). If no unit is specified, in is assumed. For example, width = 3 sets the width to 3 inches, which is the same as specifying width = 3in. And width = 300px sets the width to 300 pixels.

Parameters

width (float or str) – The graph width.
height (float or str) – The graph height.
perm (bool, optional) – When set to True, in addition to making the change right now, the setting will be remembered and become the default setting when you invoke Stata. Default is False.

pystata.config.set_graph_show(show, perm=False)¶

Set whether the graphs generated by Stata are to be exported and displayed. By default, the graphs are exported and displayed in the output. If show is set to False, graphs will not be exported and displayed.

Parameters

show (bool) – Export and display Stata-generated graphs in the output.
perm (bool, optional) – When set to True, in addition to making the change right now, the setting will be remembered and become the default setting when you invoke Stata. Default is False.

pystata.config.set_command_show(show, perm=False)¶

Specify whether to echo the commands in the output. By default, when a single-line Stata command is specified in run(), or with the %stata magic command or %%stata magic command, only the output is displayed; when a block of Stata commands is specified in run() or with the %%stata magic command, each command and its output are displayed in sequence. If show is set to True, the commands will be displayed in the output. If show is set to False, the commands will not be displayed in the output. This feature is part of StataNow.

New in version 0.1.2.

Parameters

show (bool or default (str)) – Specify whether to echo the commands in the output.
perm (bool, optional) – When set to True, in addition to making the change right now, the setting will be remembered and become the default setting when you invoke Stata. Default is False.

pystata.config.set_autocompletion(flag, perm=False)¶

Set whether to enable the autocompletion feature within an IPython environment. This feature is part of StataNow.

New in version 0.1.2.

Parameters

flag (str) – Specify whether to enable the autocompletion feature when typing Stata’s variable names from the current dataset, macro names, r() results, e() results, and s() results. on, the default, specifies to autocomplete those names when you press the Tab key. off specifies that the autocompletion feature be disabled.
perm (bool, optional) – When set to True, in addition to making the change right now, the setting will be remembered and become the default setting when you invoke Stata. Default is False.

pystata.config.set_streaming_output(flag, perm=False)¶

Set whether to display Stata’s output while Stata is executing. This feature is part of StataNow.

New in version 0.1.2.

Parameters

flag (str) – Specify whether to display Stata’s output while Stata is executing. on, the default, specifies that the output be displayed simultaneously while Stata is executing the commands. off specifies that Stata’s output be displayed after Stata finishes execution.
perm (bool, optional) – When set to True, in addition to making the change right now, the setting will be remembered and become the default setting when you invoke Stata. Default is False.

pystata.config.set_output_file(filename, replace=False)¶

Write Stata output to a text file. By default, Stata output is printed on the screen. The file extension may be .txt or .log. You must supply a file extension if you want one because none is assumed.

Parameters

filename (str) – Name of the text file.
replace (bool, optional) – Replace the output file if it exists. Default is False.

pystata.config.close_output_file()¶: Stop writing Stata output to a text file. This function should be used after having used set_output_file(). If it returns without an error, any Stata output that follows will instead be printed on the screen.

Examples¶

In the following, we provide a few quick examples illustrating how to use this module. The example code was run in a command-line Python environment.

Before running the following code, you need to configure the pystata package within Python so that it can be found and imported by Python. The Configuration section contains details on different ways you can configure this package; below, we will be using the first method listed there. In the first method, the configuration module stata_setup, which is available in the Python Package Index (PyPI), is provided to locate the pystata package to initialize Stata.

>>> # initialize Stata
>>> import stata_setup
>>> stata_setup.config("C:/Program Files/Stata18", "mp")

  ___  ____  ____  ____  ____ ®
 /__    /   ____/   /   ____/      StataNow 18.5
___/   /   /___/   /   /___/       MP—Parallel Edition

 Statistics and Data Science       Copyright 1985-2023 StataCorp LLC
                                   StataCorp
                                   4905 Lakeway Drive
                                   College Station, Texas 77845 USA
                                   800-STATA-PC        https://www.stata.com
                                   979-696-4600        [email protected]

Stata license: 10-user 4-core network perpetual
Serial number: 1
  Licensed to: Stata Developer
               StataCorp LLC

Notes:
      1. Unicode is supported; see help unicode_advice.
      2. More than 2 billion observations are allowed; see help obs_advice.
      3. Maximum number of variables is set to 5,000 but can be increased;
          see help set_maxvar.
>>>
>>> from pystata import config
>>> config.status()
    System information
      Python version         3.7.5
      Stata version          Stata 18.5 (MP)
      Stata library path     C:\Program Files\Stata18\mp-64.dll
      Stata initialized      True
      sfi initialized        True

    Settings
      graphic display        True
      graphic size           width = default, height = default
      graphic format         svg
      command display        default
      autocompletion         on
      streaming output       on
>>>
>>> # write Stata output to a log file
>>> config.set_output_file(filename='output.log', replace=True)
>>> from pystata import stata
>>> stata.run('''
...    sysuse auto
...    summarize mpg price
...
...    regress mpg price i.foreign
... ''')
>>> # close the log
>>> config.close_output_file()
>>> # set the graph size
>>> config.set_graph_size(width='5in')
>>> config.set_graph_size(height='4in')
>>> config.set_graph_size(width='600px', height='400px')
>>> config.set_graph_size(width='12cm')
>>> # reset the graph width to the default
>>> config.set_graph_size(width='default')
>>> # set the graph size permanently
>>> config.set_graph_size(width='600px', height='400px', perm=True)
>>> # do not show commands in the output
>>> config.set_command_show('off')