StrLConnector (sfi.StrLConnector)¶
-
class
sfi.
StrLConnector
(*argv)¶ This class facilitates access to Stata’s strL datatype. The allowed values for the variable index var and the observation index obs are
-nvar <= var < nvar
and
-nobs <= obs < nobs
Here nvar is the number of variables defined in the dataset currently loaded in Stata or in the specified frame, which is returned by
getVarCount()
. nobs is the number of observations defined in the dataset currently loaded in Stata or in the specified frame, which is returned bygetObsTotal()
.Negative values for var and obs are allowed and are interpreted in the usual way for Python indexing. var can be specified either as the variable name or index. Note that passing the variable index will be more efficient because looking up the index for the specified variable name is avoided.
There are two ways to create a
StrLConnector
instance:StrLConnector(var, obs)
Creates a
StrLConnector
and connects it to a specific strL in the Stata dataset; seeData
.- var : int or str
Variable to access.
- obs : int
Observation to access.
A ValueError can be raised if
StrLConnector(frame, var, obs)
Creates a
StrLConnector
and connects it to a specific strL in the specifiedFrame
.- frame :
Frame
The
Frame
to reference.- var : int or str
Variable to access.
- obs : int
Observation to access.
A ValueError can be raised if
- frame :
Method Summary
close
()Close the connection and release any resources. getPosition
()Get the current access position. getSize
()Get the total number of bytes available in the strL. isBinary
()Determine if the attached strL has been marked as binary. reset
()Reset the access position to its initial value. setPosition
(pos)Set the access position. Attributes
obs
Return the observation number of the attached strL. pos
Return the current position. var
Return the variable index of the attached strL. Method Detail
-
close
()¶ Close the connection and release any resources.
-
getPosition
()¶ Get the current access position.
Returns: The position. Return type: int
-
getSize
()¶ Get the total number of bytes available in the strL.
Returns: The total number of bytes available. Return type: int
-
isBinary
()¶ Determine if the attached strL has been marked as binary.
Returns: True if the strL has been marked as binary. Return type: bool
-
obs
¶ Return the observation number of the attached strL.
-
pos
¶ Return the current position.
-
reset
()¶ Reset the access position to its initial value.
-
setPosition
(pos)¶ Set the access position.
Parameters: pos (int) – The new position.
-
var
¶ Return the variable index of the attached strL.
Examples¶
In this section, we will show you how to access Stata’s strL datatype in two ways:
- Write to strL variables in Python.
- Read from strL variables in Python.
We will use Stata to generate a PNG file for the purpose of this illustration. Then, we will use Python to store the PNG file into a dataset. Lastly, we will demonstrate how to read the PNG image from the dataset and store it into a new file. To begin, we generate a scatterplot and save it as sc1.png.
. sysuse auto, clear
. scatter mpg price
. graph export sc1.png, replace
. clear
In the Python script that follows, strlex1.py, we create a dataset with
one variable named mystrl with one observation. Next, we create an instance
of the StrLConnector
class sc, which is connected to the first
observation of strL. The next step is to allocate the proper size for the
data that we need to store in our strL. We do this by specifying the size
of our image file in the allocateStrL()
method. Then, we
use a loop to read the contents of the image file in 2,048 byte chunks, writing
each chunk to our strL in Stata.
from sfi import Data, StrLConnector, SFIToolkit
import sys
import os
#create a new dataset with one strL variable
#mystrl and one observation
Data.addVarStrL("mystrl")
Data.setObsTotal(1)
mpv = Data.getVarIndex("mystrl")
obs = 0
#create an instance of StrLConnector
sc = StrLConnector(mpv, obs)
filename = sys.argv[1]
flen = os.path.getsize(filename)
#allocate the strL variable
Data.allocateStrL(sc, flen, True)
#read the image file and store the contents
#in the strL variable
chunk_size = 2048
with open(filename, "rb") as fin:
b = fin.read(chunk_size)
while b:
Data.writeBytes(sc, b)
b = fin.read(chunk_size)
sc.close()
SFIToolkit.displayln(filename + " stored in dataset")
Now that we have shown how to add binary data from an image file and store it
into a strL, we can reverse the process by reading the data from a
strL and storing it on disk. In the Python script that follows,
strlex2.py, we create an instance of the StrLConnector
class
sc to connect to the previously stored strL data. Remember that we stored
sc1.png in our strL. We read the data in our strL using 2,048 byte
chunks with readBytes()
, writing each of those chunks into a new
image file named sc2.png.
from sfi import Data, StrLConnector, SFIToolkit
import sys
filename = sys.argv[1]
#create an instance of StrLConnector
#to connect to the strL variable
var = Data.getVarIndex("mystrl")
obs = 0
sc = StrLConnector(var, obs)
#read the image file from the strL variable and
#store the contents in a new image file
chunk_size = 2048
with open(filename, "wb") as fout:
b = Data.readBytes(sc, chunk_size)
while b:
fout.write(b)
b = Data.readBytes(sc, chunk_size)
sc.close()
SFIToolkit.displayln(filename + " retrieved from dataset")
Using Stata, we execute both Python scripts. Next, we checksum both the original image file and the file produced by reading the data from Stata, to confirm that they are equivalent.
. python script strlex1.py, args(sc1.png)
sc1.png stored in dataset
. python script strlex2.py, args(sc2.png)
sc2.png retrieved from dataset
. checksum sc1.png
Checksum for sc1.png = 1777154237, size = 37386
. checksum sc2.png
Checksum for sc2.png = 1777154237, size = 37386