config

Utilities for loading Stata and nbstata

Before we can use pystata, we need to find the local Stata path (i.e., find_path) and then add pystata to sys.path (i.e., set_pystata_path) so it can be imported.

The get_config function handles nbstata configuration, more broadly.

from fastcore.test import test_eq, ExceptionExpected

pystata configuration

Auto-detect Stata directory and edition

---

source

find_dir_edition

 find_dir_edition (stata_path=None)

test_eq(find_dir_edition('C:/Program Files/Stata17/StataMP-64.exe'), ('C:/Program Files/Stata17', "mp"))
with ExceptionExpected(OSError):
    find_dir_edition('')

---

source

find_edition

 find_edition (stata_dir)

if _find_path('') == '': test_eq(find_edition(''), "be")
find_edition('C:\\Program Files\\Stata18')

'mp'

from nbstata.misc_utils import Timer

with Timer():
    print(find_dir_edition())

('C:\\Program Files\\Stata18', 'mp')
Elapsed time: 0.0004 seconds

Initialize pystata

---

source

set_pystata_path

 set_pystata_path (stata_dir=None)

with Timer():
    set_pystata_path()
    import pystata

Elapsed time: 0.0030 seconds

with ExceptionExpected(): import sfi

---

source

launch_stata

 launch_stata (stata_dir=None, edition=None, splash=True)

We modify stata_setup to make splash screen optional

with Timer():
    launch_stata(splash=False)
    pystata.config.status()

    System information
      Python version         3.11.10
      Stata version          Stata 18.0 (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
Elapsed time: 1.9647 seconds

sfi can only be imported after Stata is launched:

import sfi

Configure pystata graph output

https://www.stata.com/python/pystata18/config.html#pystata.config.set_graph_format

---

source

set_graph_format

 set_graph_format (gformat)

with Timer():
    set_graph_format('png')
pystata.config.status()

Elapsed time: 0.0000 seconds
    System information
      Python version         3.11.10
      Stata version          Stata 18.0 (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         png

_set_graph_size('2in', '4')
pystata.config.status()
_set_graph_size('default', 'default')

    System information
      Python version         3.11.10
      Stata version          Stata 18.0 (MP)
      Stata library path     C:\Program Files\Stata18\mp-64.dll
      Stata initialized      True
      sfi initialized        True

    Settings
      graphic display        True
      graphic size           width = 2.0in, height = 4in
      graphic format         png

nbstata configuration

The Config class handles the configuration file, after which pystata may be initialized with Config.init_stata. Config then also handles configuration changes made by the %set magic (that is, StataMagics.magic_set).

---

source

old_user_config_path

 old_user_config_path ()

---

source

xdg_user_config_path

 xdg_user_config_path ()

xdg_user_config_path()

Path('C:/Users/tjhuegerich/.config/nbstata/nbstata.conf')

old_user_config_path()

Path('C:/Users/tjhuegerich/.nbstata.conf')

---

source

Config

 Config ()

nbstata configuration

The below example reads in from a sample configuration file:

config = Config()
config.process_config_file()
config.env

{'stata_dir': 'C:\\Program Files\\Stata18',
 'edition': 'mp',
 'splash': 'False',
 'graph_format': 'png',
 'graph_width': 'default',
 'graph_height': 'default',
 'echo': 'None',
 'missing': '.',
 'browse_auto_height': 'True'}

Testing out error messages explaining invalid keys:

config.update({'splash': 'True'})

%set error(s):
    'splash' is only allowed in a configuration file.

config.update({'splash': 'True'}, init=True)

config.update({'not_a_key': 'True'})

%set error(s):
    'not_a_key' is not a valid setting.

The configuration file is read in prior to loading Stata (since it can contain a path to the desired Stata executable). But checking the validity of graph size configuration settings uses Stata, so that can’t be done in the same step in which the configuration file is read in. Thus, the following workaround is used: hold the read-in graph size settings until they are actually applied, reverting to previous valid settings if they don’t work:

---

source

Config.set_graph_size

 Config.set_graph_size (init=False)

If the configuration file has invalid width/height, the error message says “Graph size not changed” even though, under the hood, the pystata graph size configuration is changing from “default” to definite measures. This behavior ensures that using the %set magic to change just one of the size values, width or height, always exhibits the behavior described in the nbstata user guide rather than the (maintained aspect ratio) behavior described in the pystata docs.

config.display_status()
config.set_graph_size(init=True)
config.display_status()

    System information
      Python version         3.11.10
      Stata version          Stata 18.0 (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         png

      echo                   None
      missing                .
      browse_auto_height     True
      config file path       C:\Users\tjhuegerich\.config\nbstata\nbstata.conf
    System information
      Python version         3.11.10
      Stata version          Stata 18.0 (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         png

      echo                   None
      missing                .
      browse_auto_height     True
      config file path       C:\Users\tjhuegerich\.config\nbstata\nbstata.conf

config.update({'graph_width': '3'})
config.set_graph_size()

graph size was (default, default), is now (3, default).

config.display_status()
config.env

    System information
      Python version         3.11.10
      Stata version          Stata 18.0 (MP)
      Stata library path     C:\Program Files\Stata18\mp-64.dll
      Stata initialized      True
      sfi initialized        True

    Settings
      graphic display        True
      graphic size           width = 3in, height = default
      graphic format         png

      echo                   None
      missing                .
      browse_auto_height     True
      config file path       C:\Users\tjhuegerich\.config\nbstata\nbstata.conf

{'stata_dir': 'C:\\Program Files\\Stata18',
 'edition': 'mp',
 'splash': 'True',
 'graph_format': 'png',
 'graph_width': '3',
 'graph_height': 'default',
 'echo': 'None',
 'missing': '.',
 'browse_auto_height': 'True'}

config.update({'graph_height': '-3'})
config.set_graph_size()
config.env

Configuration error: graph height is invalid. Graph size not changed.

{'stata_dir': 'C:\\Program Files\\Stata18',
 'edition': 'mp',
 'splash': 'True',
 'graph_format': 'png',
 'graph_width': '3',
 'graph_height': 'default',
 'echo': 'None',
 'missing': '.',
 'browse_auto_height': 'True'}

---

source

Config.update_graph_config

 Config.update_graph_config (init=False)

config.update_graph_config()

---

source

Config.init_stata

 Config.init_stata ()