This is a complete reference for everything you get when you import patsy.
Construct two design matrices given a formula_like and data.
This function is identical to dmatrix(), except that it requires (and returns) two matrices instead of one. By convention, the first matrix is the “outcome” or “y” data, and the second is the “predictor” or “x” data.
it requires the formula to specify both a left-hand side outcome matrix and a right-hand side predictors matrix, which are return as a tuple.
See dmatrix() for details.
Construct a single design matrix given a formula_like and data.
| Parameters: |
|
|---|
The formula_like can take a variety of forms:
Regardless of the input, the return type is always either:
The actual contents of the design matrix is identical in both cases, and in both cases a DesignInfo will be available in a .design_info attribute on the return value. However, for return_type="dataframe", any pandas indexes on the input (either in data or directly passed through formula_like) will be preserved, which may be useful for e.g. time-series models.
Construct two design matrix builders incrementally from a large data set.
incr_dbuilders() is to incr_dbuilder() as dmatrices() is to dmatrix(). See incr_dbuilder() for details.
Construct a design matrix builder incrementally from a large data set.
| Parameters: |
|
|---|---|
| Returns: |
Tip: for data_iter_maker, write a generator like:
def iter_maker():
for data_chunk in my_data_store:
yield data_chunk
and pass iter_maker.
This is the main error type raised by Patsy functions.
In addition to the usual Python exception features, you can pass a second argument to this function specifying the origin of the error; this is included in any error message, and used to help the user locate errors arising from malformed formulas. This second argument should be an Origin object, or else an arbitrary object with a .origin attribute. (If it is neither of these things, then it will simply be ignored.)
For ordinary display to the user with default formatting, use str(exc). If you want to do something cleverer, you can use the .message and .origin attributes directly. (The latter may be None.)
Create simple balanced factorial designs for testing.
Given some factor names and the number of desired levels for each, generates a balanced factorial design in the form of a data dictionary. For example:
In [1]: balanced(a=2, b=3)
Out[1]:
{'a': ['a1', 'a1', 'a1', 'a2', 'a2', 'a2'],
'b': ['b1', 'b2', 'b3', 'b1', 'b2', 'b3']}
By default it produces exactly one instance of each combination of levels, but if you want multiple replicates this can be accomplished via the repeat argument:
In [1]: balanced(a=2, b=2, repeat=2)
Out[1]:
{'a': ['a1', 'a1', 'a2', 'a2', 'a1', 'a1', 'a2', 'a2'],
'b': ['b1', 'b2', 'b1', 'b2', 'b1', 'b2', 'b1', 'b2']}
Create simple categorical/numerical demo data.
Pass in a set of variable names, and this function will return a simple data set using those variable names.
Names whose first letter falls in the range “a” through “m” will be made categorical (with nlevels levels). Those that start with a “p” through “z” are numerical.
We attempt to produce a balanced design on the categorical variables, repeating as necessary to generate at least min_rows data points. Categorical variables are returned as a list of strings.
Numerical data is generated by sampling from a normal distribution. A fixed random seed is used, so that identical calls to demo_data() will produce identical results. Numerical data is returned in a numpy array.
Example:
A DesignInfo object holds metadata about a design matrix.
This is the main object that Patsy uses to pass information to statistical libraries. Usually encountered as the .design_info attribute on design matrices.
Here’s an example of the most common way to get a DesignInfo:
In [1]: mat = dmatrix("a + x", demo_data("a", "x", nlevels=3))
In [2]: di = mat.design_info
The names of each column, represented as a list of strings in the proper order. Guaranteed to exist.
In [1]: di.column_names
Out[1]: ['Intercept', 'a[T.a2]', 'a[T.a3]', 'x']
An OrderedDict mapping column names (as strings) to column indexes (as integers). Guaranteed to exist and to be sorted from low to high.
In [1]: di.column_name_indexes
Out[1]: OrderedDict([('Intercept', 0), ('a[T.a2]', 1), ('a[T.a3]', 2), ('x', 3)])
The names of each term, represented as a list of strings in the proper order. Guaranteed to exist. There is a one-to-many relationship between columns and terms – each term generates one or more columns.
In [1]: di.term_names
Out[1]: ['Intercept', 'a', 'x']
An OrderedDict mapping term names (as strings) to Python slice() objects indicating which columns correspond to each term. Guaranteed to exist. The slices are guaranteed to be sorted from left to right and to cover the whole range of columns with no overlaps or gaps.
In [1]: di.term_name_slices
Out[1]: OrderedDict([('Intercept', slice(0, 1, None)), ('a', slice(1, 3, None)), ('x', slice(3, 4, None))])
A list of Term objects representing each term. May be None, for example if a user passed in a plain preassembled design matrix rather than using the Patsy machinery.
In [1]: di.terms
Out[1]: [Term([]), Term([EvalFactor('a')]), Term([EvalFactor('x')])]
In [2]: [term.name() for term in di.terms]
Out[2]: ['Intercept', 'a', 'x']
An OrderedDict mapping Term objects to Python slice() objects indicating which columns correspond to which terms. Like terms, this may be None.
In [1]: di.term_slices
Out[1]: OrderedDict([(Term([]), slice(0, 1, None)), (Term([EvalFactor('a')]), slice(1, 3, None)), (Term([EvalFactor('x')]), slice(3, 4, None))])
A DesignMatrixBuilder object that can be used to generate more design matrices of this type (e.g. for prediction). May be None.
A number of convenience methods are also provided that take advantage of the above metadata:
Returns a human-readable string describing this design info.
Example:
In [1]: y, X = dmatrices("y ~ x1 + x2", demo_data("y", "x1", "x2"))
In [2]: y.design_info.describe()
Out[2]: 'y'
In [3]: X.design_info.describe()
Out[3]: '1 + x1 + x2'
Warning
There is no guarantee that the strings returned by this function can be parsed as formulas. They are best-effort descriptions intended for human users.
Construct a linear constraint in matrix form from a (possibly symbolic) description.
Possible inputs:
The string-based language has the standard arithmetic operators, / * + - and parentheses, plus “=” is used for equality and ”,” is used to AND together multiple constraint equations within a string. You can If no = appears in some expression, then that expression is assumed to be equal to zero. Division is always float-based, even if __future__.true_division isn’t in effect.
Returns a LinearConstraint object.
Examples:
di = DesignInfo(["x1", "x2", "x3"])
# Equivalent ways to write x1 == 0:
di.linear_constraint({"x1": 0}) # by name
di.linear_constraint({0: 0}) # by index
di.linear_constraint("x1 = 0") # string based
di.linear_constraint("x1") # can leave out "= 0"
di.linear_constraint("2 * x1 = (x1 + 2 * x1) / 3")
di.linear_constraint(([1, 0, 0], 0)) # constraint matrices
# Equivalent ways to write x1 == 0 and x3 == 10
di.linear_constraint({"x1": 0, "x3": 10})
di.linear_constraint({0: 0, 2: 10})
di.linear_constraint({0: 0, "x3": 10})
di.linear_constraint("x1 = 0, x3 = 10")
di.linear_constraint("x1, x3 = 10")
di.linear_constraint(["x1", "x3 = 0"]) # list of strings
di.linear_constraint("x1 = 0, x3 - 10 = x1")
di.linear_constraint([[1, 0, 0], [0, 0, 1]], [0, 10])
# You can also chain together equalities, just like Python:
di.linear_constraint("x1 = x2 = 3")
Locate a subset of design matrix columns, specified symbolically.
A patsy design matrix has two levels of structure: the individual columns (which are named), and the terms in the formula that generated those columns. This is a one-to-many relationship: a single term may span several columns. This method provides a user-friendly API for locating those columns.
(While we talk about columns here, this is probably most useful for indexing into other arrays that are derived from the design matrix, such as regression coefficients or covariance matrices.)
The columns_specifier argument can take a number of forms:
In all cases, a Python slice() object is returned, which can be used directly for indexing.
Example:
y, X = dmatrices("y ~ a", demo_data("y", "a", nlevels=3))
betas = np.linalg.lstsq(X, y)[0]
a_betas = betas[X.design_info.slice("a")]
(If you want to look up a single individual column by name, use design_info.column_name_indexes[name].)
Find or construct a DesignInfo appropriate for a given array_like.
If the input array_like already has a .design_info attribute, then it will be returned. Otherwise, a new DesignInfo object will be constructed, using names either taken from the array_like (e.g., for a pandas DataFrame with named columns), or constructed using default_column_prefix.
This is how dmatrix() (for example) creates a DesignInfo object if an arbitrary matrix is passed in.
| Parameters: |
|
|---|---|
| Returns: | a DesignInfo object |
A simple numpy array subclass that carries design matrix metadata.
A DesignInfo object containing metadata about this design matrix.
This class also defines a fancy __repr__ method with labeled columns. Otherwise it is identical to a regular numpy ndarray.
Warning
You should never check for this class using isinstance(). Limitations of the numpy API mean that it is impossible to prevent the creation of numpy arrays that have type DesignMatrix, but that are not actually design matrices (and such objects will behave like regular ndarrays in every way). Instead, check for the presence of a .design_info attribute – this will be present only on “real” DesignMatrix objects.
Create a DesignMatrix, or cast an existing matrix to a DesignMatrix.
A call like:
DesignMatrix(my_array)
will convert an arbitrary array_like object into a DesignMatrix.
The return from this function is guaranteed to be a two-dimensional ndarray with a real-valued floating point dtype, and a .design_info attribute which matches its shape. If the design_info argument is not given, then one is created via DesignInfo.from_array() using the given default_column_prefix.
Depending on the input array, it is possible this will pass through its input unchanged, or create a view.
Patsy comes with a number of stateful transforms built in:
A stateful transform that centers input data, i.e., subtracts the mean.
If input has multiple columns, centers each column separately.
Equivalent to standardize(x, rescale=False)
A stateful transform that standardizes input data, i.e. it subtracts the mean and divides by the sample standard deviation.
Either centering or rescaling or both can be disabled by use of keyword arguments. The ddof argument controls the delta degrees of freedom when computing the standard deviation (cf. numpy.std()). The default of ddof=0 produces the maximum likelihood estimate; use ddof=1 if you prefer the square root of the unbiased estimate of the variance.
If input has multiple columns, standardizes each column separately.
Note
This function computes the mean and standard deviation using a memory-efficient online algorithm, making it suitable for use with large incrementally processed data-sets.
An alias for standardize(), for R compatibility.
The C() function documented elsewhere is also a stateful transform.
Finally, this is not itself a stateful transform, but it’s useful if you want to define your own:
Create a stateful transform callable object from a class that fulfills the stateful transform protocol.
Converts some data into Categorical form. (It is also used called implicitly any time a formula contains a bare categorical factor.)
This is used in two cases:
To explicitly set the levels or override the default level ordering for categorical data, e.g.:
dmatrix("C(a, levels=["a2", "a1"])", balanced(a=2))
To override the default coding scheme for categorical data. The contrast argument can be any of:
In order to properly detect and remember the levels in your data, this is a stateful transform.
Treatment coding (also known as dummy coding).
This is the default coding.
For reduced-rank coding, one level is chosen as the “reference”, and its mean behaviour is represented by the intercept. Each column of the resulting matrix represents the difference between the mean of one level and this reference level.
For full-rank coding, classic “dummy” coding is used, and each column of the resulting matrix represents the mean of the corresponding level.
The reference level defaults to the first level, or can be specified explicitly.
# reduced rank
In [1]: dmatrix("C(a, Treatment)", balanced(a=3))
Out[1]:
DesignMatrix with shape (3, 3)
Intercept C(a, Treatment)[T.a2] C(a, Treatment)[T.a3]
1 0 0
1 1 0
1 0 1
Terms:
'Intercept' (column 0)
'C(a, Treatment)' (columns 1:3)
# full rank
In [2]: dmatrix("0 + C(a, Treatment)", balanced(a=3))
Out[2]:
DesignMatrix with shape (3, 3)
C(a, Treatment)[a1] C(a, Treatment)[a2] C(a, Treatment)[a3]
1 0 0
0 1 0
0 0 1
Terms:
'C(a, Treatment)' (columns 0:3)
# Setting a reference level
In [3]: dmatrix("C(a, Treatment(1))", balanced(a=3))
Out[3]:
DesignMatrix with shape (3, 3)
Intercept C(a, Treatment(1))[T.a1] C(a, Treatment(1))[T.a3]
1 1 0
1 0 0
1 0 1
Terms:
'Intercept' (column 0)
'C(a, Treatment(1))' (columns 1:3)
In [4]: dmatrix("C(a, Treatment('a2'))", balanced(a=3))
Out[4]:
DesignMatrix with shape (3, 3)
Intercept C(a, Treatment('a2'))[T.a1] C(a, Treatment('a2'))[T.a3]
1 1 0
1 0 0
1 0 1
Terms:
'Intercept' (column 0)
"C(a, Treatment('a2'))" (columns 1:3)
Equivalent to R contr.treatment. The R documentation suggests that using Treatment(reference=-1) will produce contrasts that are “equivalent to those produced by many (but not all) SAS procedures”.
Backward difference coding.
This coding scheme is useful for ordered factors, and compares the mean of each level with the preceding level. So you get the second level minus the first, the third level minus the second, etc.
For full-rank coding, a standard intercept term is added (which gives the mean value for the first level).
Examples:
# Reduced rank
In [1]: dmatrix("C(a, Diff)", balanced(a=3))
Out[1]:
DesignMatrix with shape (3, 3)
Intercept C(a, Diff)[D.a1] C(a, Diff)[D.a2]
1 -0.66667 -0.33333
1 0.33333 -0.33333
1 0.33333 0.66667
Terms:
'Intercept' (column 0)
'C(a, Diff)' (columns 1:3)
# Full rank
In [2]: dmatrix("0 + C(a, Diff)", balanced(a=3))
Out[2]:
DesignMatrix with shape (3, 3)
C(a, Diff)[D.a1] C(a, Diff)[D.a2] C(a, Diff)[D.a3]
1 -0.66667 -0.33333
1 0.33333 -0.33333
1 0.33333 0.66667
Terms:
'C(a, Diff)' (columns 0:3)
Orthogonal polynomial contrast coding.
This coding scheme treats the levels as ordered samples from an underlying continuous scale, whose effect takes an unknown functional form which is Taylor-decomposed into the sum of a linear, quadratic, etc. components.
For reduced-rank coding, you get a linear column, a quadratic column, etc., up to the number of levels provided.
For full-rank coding, the same scheme is used, except that the zero-order constant polynomial is also included. I.e., you get an intercept column included as part of your categorical term.
By default the levels are treated as equally spaced, but you can override this by providing a value for the scores argument.
Examples:
# Reduced rank
In [1]: dmatrix("C(a, Poly)", balanced(a=4))
Out[1]:
DesignMatrix with shape (4, 4)
Intercept C(a, Poly).Linear C(a, Poly).Quadratic C(a, Poly).Cubic
1 -0.67082 0.5 -0.22361
1 -0.22361 -0.5 0.67082
1 0.22361 -0.5 -0.67082
1 0.67082 0.5 0.22361
Terms:
'Intercept' (column 0)
'C(a, Poly)' (columns 1:4)
# Full rank
In [2]: dmatrix("0 + C(a, Poly)", balanced(a=3))
Out[2]:
DesignMatrix with shape (3, 3)
C(a, Poly).Constant C(a, Poly).Linear C(a, Poly).Quadratic
1 -0.70711 0.40825
1 -0.00000 -0.81650
1 0.70711 0.40825
Terms:
'C(a, Poly)' (columns 0:3)
# Explicit scores
In [3]: dmatrix("C(a, Poly([1, 2, 10]))", balanced(a=3))
Out[3]:
DesignMatrix with shape (3, 3)
Intercept C(a, Poly([1, 2, 10])).Linear C(a, Poly([1, 2, 10])).Quadratic
1 -0.47782 0.66208
1 -0.33447 -0.74485
1 0.81229 0.08276
Terms:
'Intercept' (column 0)
'C(a, Poly([1, 2, 10]))' (columns 1:3)
This is equivalent to R’s contr.poly. (But note that in R, reduced rank encodings are always dummy-coded, regardless of what contrast you have set.)
Deviation coding (also known as sum-to-zero coding).
Compares the mean of each level to the mean-of-means. (In a balanced design, compares the mean of each level to the overall mean.)
For full-rank coding, a standard intercept term is added.
One level must be omitted to avoid redundancy; by default this is the last level, but this can be adjusted via the omit argument.
Warning
There are multiple definitions of ‘deviation coding’ in use. Make sure this is the one you expect before trying to interpret your results!
Examples:
# Reduced rank
In [1]: dmatrix("C(a, Sum)", balanced(a=4))
Out[1]:
DesignMatrix with shape (4, 4)
Intercept C(a, Sum)[S.a1] C(a, Sum)[S.a2] C(a, Sum)[S.a3]
1 1 0 0
1 0 1 0
1 0 0 1
1 -1 -1 -1
Terms:
'Intercept' (column 0)
'C(a, Sum)' (columns 1:4)
# Full rank
In [2]: dmatrix("0 + C(a, Sum)", balanced(a=4))
Out[2]:
DesignMatrix with shape (4, 4)
C(a, Sum)[mean] C(a, Sum)[S.a1] C(a, Sum)[S.a2] C(a, Sum)[S.a3]
1 1 0 0
1 0 1 0
1 0 0 1
1 -1 -1 -1
Terms:
'C(a, Sum)' (columns 0:4)
# Omit a different level
In [3]: dmatrix("C(a, Sum(1))", balanced(a=3))
Out[3]:
DesignMatrix with shape (3, 3)
Intercept C(a, Sum(1))[S.a1] C(a, Sum(1))[S.a3]
1 1 0
1 -1 -1
1 0 1
Terms:
'Intercept' (column 0)
'C(a, Sum(1))' (columns 1:3)
In [4]: dmatrix("C(a, Sum('a1'))", balanced(a=3))
Out[4]:
DesignMatrix with shape (3, 3)
Intercept C(a, Sum('a1'))[S.a2] C(a, Sum('a1'))[S.a3]
1 -1 -1
1 1 0
1 0 1
Terms:
'Intercept' (column 0)
"C(a, Sum('a1'))" (columns 1:3)
This is equivalent to R’s contr.sum.
Helmert contrasts.
Compares the second level with the first, the third with the average of the first two, and so on.
For full-rank coding, a standard intercept term is added.
Warning
There are multiple definitions of ‘Helmert coding’ in use. Make sure this is the one you expect before trying to interpret your results!
Examples:
# Reduced rank
In [1]: dmatrix("C(a, Helmert)", balanced(a=4))
Out[1]:
DesignMatrix with shape (4, 4)
Intercept C(a, Helmert)[H.a2] C(a, Helmert)[H.a3] C(a, Helmert)[H.a4]
1 -1 -1 -1
1 1 -1 -1
1 0 2 -1
1 0 0 3
Terms:
'Intercept' (column 0)
'C(a, Helmert)' (columns 1:4)
# Full rank
In [2]: dmatrix("0 + C(a, Helmert)", balanced(a=4))
Out[2]:
DesignMatrix with shape (4, 4)
Columns:
['C(a, Helmert)[H.intercept]',
'C(a, Helmert)[H.a2]',
'C(a, Helmert)[H.a3]',
'C(a, Helmert)[H.a4]']
Terms:
'C(a, Helmert)' (columns 0:4)
(to view full data, use np.asarray(this_obj))
This is equivalent to R’s contr.helmert.
A simple container for a matrix used for coding categorical factors.
Attributes:
A 2d ndarray, where each column corresponds to one column of the resulting design matrix, and each row contains the entries for a single categorical variable level. Usually n-by-n for a full rank coding or n-by-(n-1) for a reduced rank coding, though other options are possible.
A list of strings to be appended to the factor name, to produce the final column names. E.g. for treatment coding the entries will look like "[T.level1]".
This is a simple class for holding categorical data, along with (possibly) a preferred contrast coding.
You should not normally need to use this class directly; it’s mostly used as a way for C() to pass information back to the formula evaluation machinery.
The interaction between a collection of factor objects.
This is one of the basic types used in representing formulas, and corresponds to an expression like "a:b:c" in a formula string. For details, see How formulas work and Model specification for experts and computers.
Terms are hashable and compare by value.
Attributes:
A tuple of factor objects.
This is a pre-instantiated zero-factors Term object representing the intercept, useful for making your code clearer. Do remember though tha this is not a singleton object, i.e., you should compare against it using ==, not is.
A simple factor class that simply looks up a named entry in the given data.
Useful for programatically constructing formulas, and as a simple example of the factor protocol. For details see Model specification for experts and computers.
Example:
dmatrix(ModelDesc([], [Term([LookupFactor("x")])]), {"x": [1, 2, 3]})
A factor class that executes arbitrary Python code and supports stateful transforms.
| Parameters: |
|
|---|
This is the standard factor class that is used when parsing formula strings and implements the standard stateful transform processing. See Stateful transforms and Model specification for experts and computers.
Two EvalFactor’s are considered equal (e.g., for purposes of redundancy detection) if they contain the same token stream and the same evaluation environment. Basically this means that the source code must be identical except for whitespace:
env = EvalEnvironment.capture()
assert EvalFactor("a + b", env) == EvalFactor("a+b", env)
assert EvalFactor("a + b", env) != EvalFactor("b + a", env)
A simple container representing the termlists parsed from a formula.
This is a simple container object which has exactly the same representational power as a formula string, but is a Python object instead. You can construct one by hand, and pass it to functions like dmatrix() or incr_dbuilder() that are expecting a formula string, but without having to do any messy string manipulation. For details see Model specification for experts and computers.
Attributes:
Two termlists representing the left- and right-hand sides of a formula, suitable for passing to design_matrix_builders().
Represents a Python execution environment.
Encapsulates a namespace for variable lookup and set of __future__ flags.
Expose the contents of a dict-like object to the encapsulated environment.
The given namespace will be checked last, after all existing namespace lookups have failed.
Capture an execution environment from the stack.
The optional argument depth specifies which stack frame to capture. depth=0 (the default) captures the stack frame of the function that calls capture(). depth=1 captures that functions caller, and so forth.
Example:
x = 1
this_env = EvalEnvironment.capture()
assert this_env["x"] == 1
def child_func():
return EvalEnvironment.capture(1)
this_env_from_child = child_func()
assert this_env_from_child["x"] == 1
Evaluate some Python code in the encapsulated environment.
| Parameters: |
|
|---|---|
| Returns: | The value of expr. |
A dict-like object that can be used to look up variables accessible from the encapsulated environment.
Construct several DesignMatrixBuilders from termlists.
This is one of Patsy’s fundamental functions, and together with build_design_matrices() forms the API to the core formula interpretation machinery.
| Parameters: |
|
|---|---|
| Returns: | A list of DesignMatrixBuilder objects, one for each termlist passed in. |
This function performs zero or more iterations over the data in order to sniff out any necessary information about factor types, set up stateful transforms, pick column names, etc.
See How formulas work for details.
This is an opaque class that represents Patsy’s knowledge about how to build a design matrix. You get these objects from design_matrix_builders(), and you pass them to build_design_matrices(). It has only one public attribute:
This attribute gives metadata about the matrices that this builder object can produce, in the form of a DesignInfo object.
Construct several design matrices from DesignMatrixBuilder objects.
This is one of Patsy’s fundamental functions, and together with design_matrix_builders() forms the API to the core formula interpretation machinery.
| Parameters: |
|
|---|
This function returns either a list of DesignMatrix objects (for return_type="matrix") or a list of pandas.DataFrame objects (for return_type="dataframe"). In the latter case, the DataFrames will preserve any (row) indexes that were present in the input, which may be useful for time-series models etc. In any case, all returned design matrices will have .design_info attributes containing the appropriate DesignInfo objects.
Unlike design_matrix_builders(), this function takes only a simple data argument, not any kind of iterator. That’s because this function doesn’t need a global view of the data – everything that depends on the whole data set is already encapsulated in the builders. If you are incrementally processing a large data set, simply call this function for each chunk.
A linear constraint in matrix form.
This object represents a linear constraint of the form Ax = b.
Usually you won’t be constructing these by hand, but instead get them as the return value from DesignInfo.linear_constraint().
A 2-dimensional ndarray with float dtype, representing A.
A 2-dimensional single-column ndarray with float dtype, representing b.
A list of strings giving the names of the variables being constrained. (Used only for consistency checking.)
This represents the origin of some object in some string.
For example, if we have an object x1_obj that was produced by parsing the x1 in the formula "y ~ x1:x2", then we conventionally keep track of that relationship by doing:
x1_obj.origin = Origin("y ~ x1:x2", 4, 6)
Then later if we run into a problem, we can do:
raise PatsyError("invalid factor", x1_obj)
and we’ll produce a nice error message like:
PatsyError: invalid factor
y ~ x1:x2
^^
Origins are compared by value, and hashable.
Produces a user-readable two line string indicating the origin of some code. Example:
y ~ x1:x2
^^
If optional argument ‘indent’ is given, then both lines will be indented by this much. The returned string does not have a trailing newline.
Class method for combining a set of Origins into one large Origin that spans them.
Example usage: if we wanted to represent the origin of the “x1:x2” term, we could do Origin.combine([x1_obj, x2_obj]).
Single argument is an iterable, and each element in the iterable should be either:
Returns either an Origin object, or None.
Extracts and returns the span of the original code represented by this Origin. Example: x1.