The config module (pystata.config)¶

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_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 5.5 inches for the width by 4 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_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/Stata17", "mp")

  ___  ____  ____  ____  ____ ®
 /__    /   ____/   /   ____/      17.0
___/   /   /___/   /   /___/       MP—Parallel Edition

 Statistics and Data Science       Copyright 1985-2021 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; see help set_maxvar.
>>>
>>> from pystata import config
>>> config.status()
    System information
      Python version         3.7.5
      Stata version          Stata 17.0 (MP)
      Stata library path     C:\Program Files\Stata17\mp-64.dll
      Stata initialized      True
      sfi initialized        True

    Settings
      graphic display        True
      graphic size           width = default, height = default
      graphic format         svg
>>>
>>> # 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)