### Install Formulaic with Benchmarking Dependencies Source: https://github.com/matthewwardrop/formulaic/blob/main/benchmarks/README.md Use this command to install Formulaic along with the necessary dependencies for running the benchmarks. ```bash pip install formulaic[benchmarks] ``` -------------------------------- ### Example Model Matrix Output with Clustering Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Illustrates the resulting model matrix when columns are clustered by numerical factors. ```text Intercept a a:A[T.b] a:A[T.c] b A[T.b]:b A[T.c]:b 0 1.0 1 0 0 4 0 0 1 1.0 2 2 0 5 5 0 2 1.0 3 0 3 6 0 6 ``` -------------------------------- ### Install Formulaic from PyPI Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/installation.md Use this command to install the latest stable release of Formulaic from the Python Package Index. Ensure pip is up-to-date for best results. ```bash $ pip install formulaic ``` -------------------------------- ### Run Formulaic Benchmarks Source: https://github.com/matthewwardrop/formulaic/blob/main/benchmarks/README.md Execute the benchmark script from the Formulaic repository to compare performance. Ensure R and its 'Matrix' dependency are installed if R benchmarks are desired. ```bash python /benchmarks/benchmark.py ``` -------------------------------- ### Cubic Spline Interpolation Setup Source: https://github.com/matthewwardrop/formulaic/blob/main/tests/transforms/data/cublic_spine_r_test_data.txt Configures cubic spline interpolation with specified knot points and absorption conditions. Ensure the number of knots matches the provided array. ```python spline_type=cs nb_knots=4 knots=np.array([-2500, -150, 300, 1500.0000000000000000, ]) absorb_cons=FALSE output=np.array([-0.0051418610449036764379, -0.0051207276560822079237, -0.0051517581620670691717, -0.0051036969019558836927, -0.0051724091286762859804, -0.0050616345732373531699, -0.0052108015793779615538, -0.0049476511776847470828, -0.00525764719160080711, -0.0045887810243909702562, -0.0051780211262217532009, -0.0032118234048454639452, -0.0042344880890217376918, 0.0033309098171163710467, -0.0002048781708894489937, 0.036873131791193267115, 0.0053670164361401782871, 0.19556964857406355929, 0.00027785197169554257113, 0.82912284340298503249, 0.65949448911253716332, 0.6654093842010145865, 0.65653556733089935005, 0.66984284447353759084, 0.64987461295218140744, 0.67980900603329297294, 0.63487206047522759533, 0.70218091452751663084, 0.60105778412747068451, 0.75218902517658670082, 0.52490094418674082544, 0.86229539201840321727, 0.35569403068909899446, 1.0895778496922625678, 0.014595118281322956924, 1.4713138143490975818, -0.3821845778229204238, 1.7530984807387750557, -0.019785804601727036839, 0.46986487896086814864, 0.35950128095327349431, 0.35338118891054576265, 0.36256112212690350116, 0.34879091185540550546, 0.36944502095300485456, 0.3384628569483467686, 0.38492806794448852781, 0.31523169436694697954, 0.41971361558839714867, 0.26307215994266325287, 0.49746707294522052312, 0.14713121281897215131, 0.66691371985704051006, -0.097089653687300894735, 0.9873402560545572193, -0.53105535871660392022, 1.2102463767433073727, -0.99135819513191647534, 0.044702741392222536398, -0.3124421698702265493, -0.013853909020907106964, -0.013669845455478047552, -0.013944931295735877447, -0.013530059426987159701, -0.014147224776509979491, -0.013210228408402318115, -0.014589326840338213628, -0.012464957716778975183, -0.015513752524267036478, -0.010672404094858929657, -0.017189996005739616169, -0.0062147814325298833885, -0.018373262457117778973, 0.004180894177922047858, -0.0017304961649907309174, 0.022868412576313085216, 0.16657118464347281384, 0.042690065819077735454, 0.97480521123780894399, 0.013454447506373390722, ]).reshape((20, 4, ), order="F") ``` -------------------------------- ### Create and Fit Scikit-Learn Pipeline with FormulaicTransformer Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/integration.ipynb This example demonstrates creating a scikit-learn `Pipeline` that uses the `FormulaicTransformer` with a formula 'x1 + x2 + x3', followed by a `LinearRegression` model. The pipeline is then fitted with sample pandas DataFrame and Series. ```python pipe = Pipeline( [("formula", FormulaicTransformer("x1 + x2 + x3")), ("model", LinearRegression())] ) pipe_fit = pipe.fit( pandas.DataFrame({"x1": [1, 2, 3], "x2": [2, 3.4, 6], "x3": [7, 3, 1]}), y=pandas.Series([1, 3, 5]), ) pipe_fit ``` -------------------------------- ### Custom Contrast Matrix Calculation Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/contrasts.ipynb Define custom coding matrices using `CustomContrasts` or `contr.custom`. This example demonstrates calculating a coding matrix for specific contrast definitions (B-A, C-B, D-A) using NumPy. ```python import numpy Z = numpy.array( [ [1, 0, 0, 0], # A [-1, 1, 0, 0], # B - A [0, -1, 1, 0], # C - B [-1, 0, 0, 1], # D - A ] ) coding = numpy.linalg.inv(Z)[:, 1:] coding ``` -------------------------------- ### Install Formulaic in Editable Mode Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/installation.md Install Formulaic in editable mode after cloning the repository. This allows your local changes to be immediately reflected in your Python sessions. Requires pip version 21.3 or higher. ```bash $ pip install -e ``` -------------------------------- ### Custom Categorical Encoding with C() and Polynomial Contrasts Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/contrasts.ipynb Apply custom contrast codings, such as polynomial contrasts, and specify categorical levels and their order using the C() transform. This example demonstrates polynomial coding with specified levels. ```python model_matrix("C(values, contr.poly, levels=[10, 20, 30])", df) ``` -------------------------------- ### Implement Custom Stateful Transform with Formulaic Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/transforms.ipynb Implement a custom stateful transform using the `@stateful_transform` decorator. This example demonstrates a custom `center` function that stores the calculated mean in its state for reuse. ```python import numpy from formulaic.transforms import stateful_transform @stateful_transform def center(data, _state=None, _metadata=None, _spec=None): print("state", _state) print("metadata", _metadata) print("spec", _spec) if "mean" not in _state: _state["mean"] = numpy.mean(data) return data - _state["mean"] state = {} center(pandas.Series([1, 2, 3]), _state=state) ``` -------------------------------- ### Cubic Spline with 7 Knots Source: https://github.com/matthewwardrop/formulaic/blob/main/tests/transforms/data/cublic_spine_r_test_data.txt Example of generating a cubic spline with 7 knots. The output is a NumPy array reshaped to (20, 4) in Fortran order. ```python spline_type=cr nb_knots=7 knots=None absorb_cons=FALSE output=np.array([-2.9605259404128104445e-07, 4.3004543792069181325e-07, -4.6506508782294522313e-07, 1.2225175036037286749e-06, -4.8490441759023038782e-07, 2.7062259965304665474e-06, 2.8104230735656565092e-07, -5.4449455566502238182e-06, 1.7542735683802410547e-06, -0.00011038827024139799939, 2.8120883750482203265e-06, -0.00053376130083573273665, -7.6784755538918750706e-07, 0.00061879177472234751789, -9.2078635815506674409e-06, 0.029574116402683980898, -1.6901017048743381161e-05, 0.21556638245963724576, 0, 1, 0.00010456869825724268133, -0.00015189629322606839636, 0.00016426557921581520349, -0.00043180524853199072667, 0.00017127302630398999017, -0.000955865732450367038, -9.9266916848531769006e-05, 0.0019305664182940607265, -0.00061962673904836988552, 0.042415216868389754579, -0.00099325736940550032363, 0.27732557133728741317, 0.00027121133522598855859, 1.1504608369631013076, 0.0032523082987030572759, 2.7821404636666882126, 0.0059696060348119403538, 4.1098324719022825136, 0, 0, -0.031642380707528651451, 0.046727930564370717681, -0.049706595580857972083, 0.14260551573254778845, -0.051827041873556585483, 0.44422176162356585838, 0.030038067097830360025, 1.2696071710389067455, 0.18749841492049976188, 2.6526069738107440621, 0.30055865997270758694, 3.4401400654673524038, -0.082068271523342908869, -0.89294447099362916909, -0.98414515128277502143, -10.707999025460104292, -1.8063966557448927208, -19.65451295888456329, 0, 0, 0.9404055233767310007, 1.0229997547271381109, 0.84839014691027592185, 0.9942253298077886603, 0.55270681506501917468, 0.71325376394101502875, -0.27008001161472772189, -0.36441609214674652861, -1.6858466263672904351, -2.2746949537899268101, -2.7024004611201863923, -3.6463202499480562579, 0.73789700429246496416, 0.99563659340566201816, 8.8487029815652924469, 11.939460983544531558, 16.241778413219694954, 21.914859168852931504, 0, 0, 0.091452250263845791256, -0.069826465452058242289, 0.20181123367547218472, -0.13689085681302756714, 0.50012121362724204499, -0.15708533369949770342, 1.2380919977577322655, 0.093217876961678852732, 2.4558884227495125785, 0.58186847095202909319, 3.1248015911458146832, 0.93273112726773044212, -0.80684053529361110524, -0.25468449792074498994, -9.6754590529148973843, -3.0541220021223365322, -17.759287695723489975, -5.6058354437652431201, 0, 0, -0.00032057317842933900735, 0.00025095691201626593508, -0.0006604553857512240455, 0.00049198690620599915858, -0.0011751018630891821651, 0.00056456602826813432217, 0.0020547291059278675364, -0.00033502584436379451204, 0.043190243671805170211, -0.002091240244288253107, 0.27856793393313283858, -0.0033522436217435750035, 1.1501216068412509763, 0.00091533825638770416853, 2.7780724886333088008, 0.010976540508122837117, 4.1023657110424904815, 0.02014742036749034293, 0, 0, 9.0759971803981566744e-07, -7.1050367876085636178e-07, 1.8698667331515860834e-06, -1.392902486538716717e-06, 3.3269224981118857968e-06, -1.5983868974364 ]).reshape((20, 4, ), order="F") ``` -------------------------------- ### Cubic Spline with 4 Knots Source: https://github.com/matthewwardrop/formulaic/blob/main/tests/transforms/data/cublic_spine_r_test_data.txt Example of generating a cubic spline with 4 knots. The output is a NumPy array reshaped to (20, 4) in Fortran order. ```python spline_type=cr nb_knots=4 knots=None absorb_cons=FALSE output=np.array([-1.693557754132211208e-05, -1.9836972061171899575e-05, -1.4954358368392469422e-05, -2.088026100812221311e-05, -9.5355264085171175196e-06, -1.8699295604068575353e-05, 4.9022718833308546933e-06, 1.7974067511175931267e-05, 3.744122291002612696e-05, 0.0002988262983956019303, 0.00010718085083579747424, 0.001935560671294481172, 0.00024699248283329116715, 0.010566342124751632037, 0.00048044994314723433668, 0.053454984128479515748, 0.00065729103443297996496, 0.25076507420610638643, 0, 1, 0.35560680685948470314, 0.46359416252769836131, 0.30168882277557279581, 0.54466866236250932598, 0.18063664369405590948, 0.72711735964503432239, -0.089776348720933471514, 1.1356863997659447652, -0.68566908660007752641, 2.0361466894716735432, -1.9628257407671605428, 3.9650378336575471394, -4.523225924226894179, 7.8266636243390204086, -8.7985820993738865781, 14.246329329102128014, -12.037110654561336887, 18.944322912930825709, 0, 0, 0.6444562685323340645, 0.53647236902629924504, 0.69836999393477805498, 0.45539628464397530205, 0.81940601333710849641, 0.27293213874197075341, 1.0897461189737138731, -0.13572091900106228457, 1.6852766572444068949, -1.0365718798973906356, 2.9606222279687766097, -2.967335129700412466, 5.5120421008950604147, -6.8380635660933348774, 9.743925990387539926, -13.301405831788731149, 12.784702352769150124, -18.197306344378148424, 0, 0, -4.6139814277377641984e-05, -4.6694581936484837246e-05, -4.3862351982477081188e-05, -4.4066745476440737986e-05, -3.3121504755945730075e-05, -3.0799091401098394798e-05, 2.5327475336172373395e-05, 1.6545167606241587368e-05, 0.00035498813276064257764, 0.00012636412732133810903, 0.0020963319475481821674, 0.00036173537157081639762, 0.010936830849001568516, 0.00083359962956235762136, 0.054175659043200374843, 0.0016215185581219158321, 0.25175101075775591086, 0.0022183572412113072327, 1, 0, ]).reshape((20, 4, ), order="F") ``` -------------------------------- ### Create Cubic Spline with 7 Knots Source: https://github.com/matthewwardrop/formulaic/blob/main/tests/transforms/data/cublic_spine_r_test_data.txt Configures a cubic spline ('cs') with 7 knots. The `absorb_cons=TRUE` setting indicates that constraints are being integrated into the spline definition. This setup is typical for advanced spline modeling where boundary conditions are critical. ```python spline_type=cs nb_knots=7 knots=np.array([-1000, -500, -250, 0, 250, 500, 1000, ]) absorb_cons=TRUE ``` -------------------------------- ### Get AST from Formula String Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Use DefaultFormulaParser to get the Abstract Syntax Tree (AST) representation of a formula string. ```python DefaultFormulaParser().get_ast("y ~ a + b:c") ``` -------------------------------- ### Run Formulaic Benchmark Visualization Source: https://github.com/matthewwardrop/formulaic/blob/main/benchmarks/README.md Use this command to generate visualizations of the benchmark results. ```bash python /benchmarks/plot.py ``` -------------------------------- ### ModelSpec Initialization Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Demonstrates the initialization of a ModelSpec object with a formula and various parameters. ```python ModelSpec(formula=1 + a + b:c, materializer='pandas', materializer_params={}, ensure_full_rank=True, na_action=, output='numpy', cluster_by=, structure=[EncodedTermStructure(term=1, scoped_terms=[1], columns=['Intercept']), EncodedTermStructure(term=a, scoped_terms=[a], columns=['a']), EncodedTermStructure(term=b:c, scoped_terms=[b:c], columns=['b:c'])], transform_state={}, encoder_state={'a': (, {}), 'b': (, {}), 'c': (, {})}) ``` -------------------------------- ### Get Terms from Formula String Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Instantiate DefaultFormulaParser with include_intercept=False to obtain the terms required for a Formula object from a string. ```python terms = DefaultFormulaParser(include_intercept=False).get_terms("y ~ a + b:c") terms ``` -------------------------------- ### Instantiate Term with Factors Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Instantiate a Term by providing a list of Factor instances. The factors will be sorted to ensure a unique representation. ```python from formulaic.parser.types import Term Term(factors=[Factor("b"), Factor("a"), Factor("c")]) ``` -------------------------------- ### Get Column Names from Sparse Model Matrix Spec Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/quickstart.ipynb Since sparse matrices do not have column labels, retrieve column names from the `model_spec` attribute. ```python X.model_spec.column_names ``` -------------------------------- ### Instantiate Factor - Data Lookup Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Instantiate a Factor that will be looked up from the data context during materialization. This is the default evaluation method. ```python Factor("a") # a factor that will be looked up from the data context ``` -------------------------------- ### Center Data with Formulaic Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/transforms.ipynb Use the `center` transform to rescale data to have a mean of zero. This is a simpler form of scaling useful when only centering is required. ```python center(pandas.Series([1, 2, 3, 4, 5, 6, 7, 8])) ``` -------------------------------- ### Aliasing Categorical Features in Formulaic Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/contrasts.ipynb Alias categorical variables outside the formula for more manageable feature names. The `model_matrix` function automatically handles this aliasing. This example uses `TreatmentContrasts` with a specified base level. ```python my_letters = C(df.letters, TreatmentContrasts(base="b")) model_matrix("my_letters", df) ``` -------------------------------- ### Create Structured ModelSpecs Manually Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/model_specs.ipynb Demonstrates how to manually construct a ModelSpecs object with nested substructures. Each substructure can define its own model formula. ```python from formulaic import Formula, ModelSpecs ModelSpecs( ModelSpec("a"), substructure=ModelSpec("b"), another_substructure=ModelSpec("c") ) ``` -------------------------------- ### Modeling with Cyclic Cubic Splines Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/splines.ipynb Shows how to apply cyclic cubic splines using the `cc` transform for data that exhibits cyclical patterns. The `constraints='center'` option is used to center the basis functions. ```python x = numpy.linspace(0.0, 2 * numpy.pi, 100) data = pandas.DataFrame( { "x": x, } ).assign( y=lambda df: ( 2 + numpy.sin(x) - x * numpy.sin(2 * x) + 4 * numpy.sin(x / 7) + 0.1 * numpy.random.randn(100) ) ) # Generate a model matrix with a cyclic cubic spline coding in "x". y, X = model_matrix("y ~ 1 + cc(x, df=4, constraints='center')", data, output="numpy") ``` -------------------------------- ### Instantiate Factor - Literal Constant Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Instantiate a Factor representing a numerical constant. This factor will be evaluated as a literal value. ```python from formulaic.parser.types import Factor Factor( "1", eval_method="literal" ) # a factor that represents the numerical constant of 1 ``` -------------------------------- ### Instantiate Factor - Python Expression Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Instantiate a Factor that will be evaluated as a Python expression within the provided data context. Ensure the expression is valid Python. ```python Factor( "a + b", eval_method="python" # a factor that will return the sum of `a` and `b` ) ``` -------------------------------- ### Short-hand for Model Matrix Creation Source: https://github.com/matthewwardrop/formulaic/blob/main/README.md A more concise way to generate model matrices using the `model_matrix` function directly, bypassing the explicit `Formula` object creation. Requires 'formulaic' import. ```python from formulaic import model_matrix model_matrix('y ~ x + z', df) ``` -------------------------------- ### Categorical Variable Interaction with Intercept in Formulaic Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/migration.md Formulaic guarantees structurally full-rank model matrices, unlike R which can produce over- or under-specified matrices. For example, `1 + A:B` is handled correctly in Formulaic to avoid rank reduction issues. ```python 1 + A:B ``` -------------------------------- ### Cubic Spline Interpolation Configuration Source: https://github.com/matthewwardrop/formulaic/blob/main/tests/transforms/data/cublic_spine_r_test_data.txt Sets up cubic spline interpolation with 5 knots and specific boundary conditions. The 'absorb_cons' parameter is set to FALSE. ```python spline_type=cs nb_knots=5 knots=np.array([-400, -50, 10, 50, 100, ]) absorb_cons=FALSE ``` -------------------------------- ### Generate Sparse Model Matrix Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/quickstart.ipynb To generate sparse model matrices, set the `output` parameter to 'sparse'. This is memory-efficient for large datasets with many categorical features. ```python X = model_matrix("a + b + a:b", df, output="sparse") X ``` -------------------------------- ### Formula Ordering Conventions Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Demonstrates different ordering conventions ('degree', 'none', 'sort') for terms within a formula. The default is 'degree'. ```python { "degree": Formula("z + z:a + z:b:a + g"), "none": Formula("z + z:a + z:b:a + g", _ordering="none"), "sort": Formula("z + z:a + z:b:a + g", _ordering="sort"), } ``` -------------------------------- ### Tokenize Formula String in Python Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Demonstrates how to tokenize a formula string using `DefaultFormulaParser`. This process breaks down the string into distinct tokens, identifying their types (name, operator, value, python). ```python from formulaic.parser import DefaultFormulaParser [ f"{token.token} : {token.kind.value}" for token in ( DefaultFormulaParser(include_intercept=False).get_tokens( "y ~ 1 + b:log(c) | `d$in^df` + {e + f}" ) ) ] ``` ```text Result: ['y : name', '~ : operator', '1 : value', '+ : operator', 'b : name', ': : operator', 'log(c) : python', '| : operator', 'd$in^df : name', '+ : operator', 'e + f : python'] ``` -------------------------------- ### Interrogate ModelSpec for Metadata Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/model_specs.ipynb Demonstrates how to access various metadata attributes from a ModelSpec instance, including column names, terms, factors, and variables. Assumes a ModelSpec instance 'ms' is already available. ```python # We can now interrogate it for various column, factor, term, and variable related metadata { "column_names": ms.column_names, "column_indices": ms.column_indices, "terms": ms.terms, "term_indices": ms.term_indices, "term_slices": ms.term_slices, "term_factors": ms.term_factors, "term_variables": ms.term_variables, "factors": ms.factors, "factor_terms": ms.factor_terms, "factor_variables": ms.factor_variables, "factor_contrasts": ms.factor_contrasts, "variables": ms.variables, "variable_terms": ms.variable_terms, "variable_indices": ms.variable_indices, "variables_by_source": ms.variables_by_source, } ``` ```text Result: {'column_names': ('Intercept', 'center(a)', 'b[T.B]', 'b[T.C]'), 'column_indices': {'Intercept': 0, 'center(a)': 1, 'b[T.B]': 2, 'b[T.C]': 3}, 'terms': [1, center(a), b], 'term_indices': {1: [0], center(a): [1], b: [2, 3]}, 'term_slices': {1: slice(0, 1, None), center(a): slice(1, 2, None), b: slice(2, 4, None)}, 'term_factors': {1: {1}, center(a): {center(a)}, b: {b}}, 'term_variables': {1: set(), center(a): {'a', 'center'}, b: {'b'}}, 'factors': {1, b, center(a)}, 'factor_terms': {1: {1}, center(a): {center(a)}, b: {b}}, 'factor_variables': {b: {'b'}, 1: set(), center(a): {'a', 'center'}}, 'factor_contrasts': {b: ContrastsState(contrasts=TreatmentContrasts(base=UNSET), levels=['A', 'B', 'C'])}, 'variables': {'a', 'b', 'center'}, 'variable_terms': {'center': {center(a)}, 'a': {center(a)}, 'b': {b}}, 'variable_indices': {'center': [1], 'a': [1], 'b': [2, 3]}, 'variables_by_source': {'transforms': {'center'}, 'data': {'a', 'b'}}} ``` -------------------------------- ### Generate Treatment Contrast Coding Matrix Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/contrasts.ipynb Instantiate and use TreatmentContrasts to generate a coding matrix for categorical data. Specify the base level for the contrasts. ```python from formulaic.transforms.contrasts import C, TreatmentContrasts TreatmentContrasts(base="B").get_coding_matrix(["A", "B", "C", "D"]) ``` -------------------------------- ### Create Formula from Terms Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Construct a Formula object by passing the generated terms to its constructor. ```python Formula(terms) ``` -------------------------------- ### Formula Ordering Results Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb The resulting string representations show how different ordering conventions affect the display of terms and factors. ```text {'degree': 1 + z + g + z:a + z:b:a, 'none': 1 + z + z:a + z:b:a + g, 'sort': 1 + g + z + a:z + a:b:z} ``` -------------------------------- ### Generate Structured Model Matrix Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Create a structured model matrix by specifying a grouping variable in the Formula constructor. ```python Formula("a", group="b+c").get_model_matrix(data) ``` -------------------------------- ### Plotting Weighted Basis Splines and Fit Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/splines.ipynb Visualizes the basis splines weighted by their coefficients, raw observations, and the final fitted spline. Requires matplotlib and numpy for plotting. ```python plt.plot( data.x, X * coeffs, label=[name + " (weighted)" for name in X.model_spec.column_names], ) # Plot B-spline basis functions (colored curves) each multiplied by its coeff plt.scatter(data.x, data.y, marker="x", label="Raw observations") # Plot the fit spline itself (sum of the basis functions) plt.plot(data.x, numpy.dot(X, coeffs), color="k", linewidth=3, label="Fit spline") plt.legend(); ``` -------------------------------- ### Generate Treatment Contrast Coefficient Matrix Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/contrasts.ipynb Generate the coefficient matrix for treatment contrasts, which represents the differences between levels and the base level. This is useful for understanding the interpretation of coefficients in regression models. ```python TreatmentContrasts(base="B").get_coefficient_matrix(["A", "B", "C", "D"]) ``` -------------------------------- ### Modeling Non-linear Data with Polynomial Splines Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/splines.ipynb Demonstrates how to use the `poly` transform to model a non-linear relationship with orthogonal polynomial basis functions. This is useful for capturing polynomial trends in data. ```python import matplotlib.pyplot as plt import numpy import pandas from statsmodels.api import OLS from formulaic import model_matrix # Build some data, and hard-code "y" as a quartic function with some Gaussian noise. data = pandas.DataFrame( { "x": numpy.linspace(0.0, 1.0, 100), } ).assign( y=lambda df: ( df.x + 0.2 * df.x**2 - 0.7 * df.x**3 + 3 * df.x**4 + 0.1 * numpy.random.randn(100) ) ) # Generate a model matrix with a polynomial coding in "x". y, X = model_matrix("y ~ poly(x, degree=3)", data, output="numpy") # Fit coefficients for the intercept and polynomial basis coeffs = OLS(y[:, 0], X).fit().params # Plot the basis splines weighted by coefficients. plt.plot( data.x, X * coeffs, label=[name + " (weighted)" for name in X.model_spec.column_names], ) # Plot B-spline basis functions (colored curves) each multiplied by its coeff plt.scatter(data.x, data.y, marker="x", label="Raw observations") # Plot the fit spline itself (sum of the basis functions) plt.plot(data.x, numpy.dot(X, coeffs), color="k", linewidth=3, label="Fit spline") plt.legend(); ``` -------------------------------- ### Scale Data with Formulaic Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/transforms.ipynb Use the `scale` transform to rescale data to have a mean of zero and a standard deviation of 1. This is useful for standardizing features in statistical modeling. ```python from formulaic.transforms import center, scale scale(pandas.Series([1, 2, 3, 4, 5, 6, 7, 8])) ``` -------------------------------- ### Multi-Stage Formula Notation Operator Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/grammar.md The experimental multi-stage formula notation `[ . ~ . ]` is useful in contexts like IV regression and requires the `MULTISTAGE` feature flag. Supported only in Formulaic. ```python [ . ~ . ] ``` -------------------------------- ### Create ModelSpec from Formula Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/model_specs.ipynb Shows how to create a ModelSpec instance from a Formula object, automatically structuring the ModelSpecs based on the formula's left-hand side (lhs) and right-hand side (rhs). ```python ModelSpec.from_spec(Formula(lhs="y", rhs="a + b")) ``` -------------------------------- ### Create Model Matrix and Extract ModelSpec Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/model_specs.ipynb Generates a ModelMatrix from a formula and DataFrame, then extracts its associated ModelSpec. Requires pandas and formulaic. ```python from pandas import DataFrame from formulaic import model_matrix mm = model_matrix("center(a) + b", DataFrame({"a": [1, 2, 3], "b": ["A", "B", "C"]})) mm ``` ```text Result: Intercept center(a) b[T.B] b[T.C] 0 1.0 -1.0 0 0 1 1.0 0.0 1 0 2 1.0 1.0 0 1 ``` ```python # And extract the model spec from it ms = mm.model_spec ms ``` ```text Result: ModelSpec(formula=1 + center(a) + b, materializer='pandas', materializer_params={}, ensure_full_rank=True, na_action=, output='pandas', cluster_by=, structure=[EncodedTermStructure(term=1, scoped_terms=[1], columns=['Intercept']), EncodedTermStructure(term=center(a), scoped_terms=[center(a)], columns=['center(a)']), EncodedTermStructure(term=b, scoped_terms=[b-], columns=['b[T.B]', 'b[T.C]'])], transform_state={'center(a)': {'ddof': 1, 'center': np.float64(2.0), 'scale': None}}, encoder_state={'center(a)': (, {}), 'b': (, {'categories': ['A', 'B', 'C'], 'contrasts': ContrastsState(contrasts=TreatmentContrasts(base=UNSET), levels=['A', 'B', 'C'])})}) ``` -------------------------------- ### Display Model Matrix X Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/quickstart.ipynb Displays the generated model matrix X, showing the encoded categorical variables and interaction terms. ```python X ``` -------------------------------- ### Instantiate Unstructured Formula Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Instantiate an unstructured Formula object. This object serves as a container for Term instances that will be materialized into a model matrix. ```python from formulaic import Formula ``` -------------------------------- ### Construct Structured Formula Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Create a structured formula with nested substructures. Structured formulas are instances of `StructuredFormula`. ```python f = Formula( [ Term(factors=[Factor("root_col")]), ], my_substructure=[ Term(factors=[Factor("sub_col")]), ], nested=Formula( [ Term(factors=[Factor("nested_col")]), Term(factors=[Factor("another_nested_col")]), ], really_nested=[ Term(factors=[Factor("really_nested_col")]), ], ), ) f ``` -------------------------------- ### Use Custom Transform with Automatic Context Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/transforms.ipynb Demonstrates using a custom transform when the local context is automatically added to the execution context, typically when using the top-level `model_matrix` function. ```python # Local context is automatically added model_matrix("a + my_transform(a)", pandas.DataFrame({"a": [1, 2, 3]})) ``` -------------------------------- ### Scikit-Learn Pipeline Representation Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/integration.ipynb This shows the resulting representation of the scikit-learn pipeline after fitting, indicating the steps involved and their configurations. ```python Pipeline(steps=[('formula', FormulaicTransformer(formula=1 + x1 + x2 + x3)), ('model', LinearRegression())]) ``` -------------------------------- ### Use Custom Transform with Manual Context Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/transforms.ipynb Shows how to manually add a custom transform to the evaluation context when using `Formula.get_model_matrix`. This is necessary when the local context is not automatically included. ```python # Manually add `my_transform` to the context Formula("a + my_transform(a)").get_model_matrix( pandas.DataFrame({"a": [1, 2, 3]}), context={"my_transform": my_transform}, # could also use: context=locals() ) ``` -------------------------------- ### Cubic Spline with 7 Knots Source: https://github.com/matthewwardrop/formulaic/blob/main/tests/transforms/data/cublic_spine_r_test_data.txt Sets up a cubic spline ('cr') with 7 knots and activates boundary condition absorption. This configuration is suitable for more complex data interpolation needs. ```python spline_type=cr nb_knots=7 knots=np.array([-1000, -500, -250, 0, 250, 500, 1000, ]) absorb_cons=TRUE ``` -------------------------------- ### Ignore Nulls with NAAction.IGNORE Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/missing_data.ipynb Allows null values to remain in columns and propagate naturally. Use when your modeling toolkit can handle nulls. ```python model_matrix("c + C", df, na_action="ignore") ``` -------------------------------- ### Unstructured Formula Type and Content Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Verify that an unstructured formula is a `SimpleFormula` and inspect its constituent terms. ```python type(f), list(f) ``` -------------------------------- ### Clone Formulaic Source Code Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/installation.md Clone the Formulaic source code repository from GitHub to contribute to development. You can use either the SSH or HTTPS URL. ```bash $ git clone git@github.com:matthewwardrop/formulaic.git ``` -------------------------------- ### Custom Stateful Transform with Single Dispatch Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/transforms.ipynb Leverage single dispatch functionality for custom stateful transforms by registering type-specific implementations. Ensure the top-level function signature matches all registered implementations. ```python from formulaic.transforms import stateful_transform @stateful_transform def center(data, _state=None, _metadata=None, _spec=None): raise ValueError(f"No implementation for data of type {repr(type(data))}") @center.register(pandas.Series) def _(data, _state=None, _metadata=None, _spec=None): if "mean" not in _state: _state["mean"] = numpy.mean(data) return data - _state["mean"] ``` -------------------------------- ### Directly Construct ModelSpec Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/model_specs.ipynb Instantiate a `ModelSpec` directly with a formula and specific materialization options like output type and rank enforcement. This allows for fine-grained control over model specification. ```python from formulaic import ModelSpec ms = ModelSpec("a+b+c", output="numpy", ensure_full_rank=False) ms ``` -------------------------------- ### Modeling Non-linear Data with B-Splines Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/splines.ipynb Illustrates the use of the `bs` (basis_spline) transform to model non-linear relationships using B-spline basis functions. This is suitable for capturing more complex, piecewise polynomial trends. ```python # Generate a model matrix with a basis spline "x". y, X = model_matrix("y ~ bs(x, df=4, degree=3)", data, output="numpy") # Fit coefficients for the intercept and polynomial basis coeffs = OLS(y[:, 0], X).fit().params # Plot the basis splines weighted by coefficients. plt.plot( data.x, X * coeffs, label=[name + " (weighted)" for name in X.model_spec.column_names], ) # Plot B-spline basis functions (colored curves) each multiplied by its coeff plt.scatter(data.x, data.y, marker="x", label="Raw observations") # Plot the fit spline itself (sum of the basis functions) plt.plot(data.x, numpy.dot(X, coeffs), color="k", linewidth=3, label="Fit spline") plt.legend(); ``` -------------------------------- ### Generate Model Matrix from Direct ModelSpec Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/model_specs.ipynb Create a model matrix using a directly constructed `ModelSpec` instance and a pandas DataFrame. This demonstrates the process of materializing data based on a pre-configured `ModelSpec`. ```python import pandas mm = ms.get_model_matrix( pandas.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6], "c": [7, 8, 9]}) ) mm ``` -------------------------------- ### Create Formula Directly from String Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Instantiate a Formula object directly from a string, optionally overriding the default parser. ```python Formula("y ~ a + b:c", _parser=DefaultFormulaParser(include_intercept=False)) ``` -------------------------------- ### Create Model Matrix from DataFrame Source: https://github.com/matthewwardrop/formulaic/blob/main/README.md Use Formula to parse a formula string and generate model matrices (y and X) from a pandas DataFrame. Requires 'pandas' and 'formulaic' imports. ```python import pandas from formulaic import Formula df = pandas.DataFrame({ 'y': [0, 1, 2], 'x': ['A', 'B', 'C'], 'z': [0.3, 0.1, 0.2], }) y, X = Formula('y ~ x + z').get_model_matrix(df) ``` -------------------------------- ### Structured Formula Type Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Confirm that a structured formula is an instance of `StructuredFormula`. ```python type(f) ``` -------------------------------- ### Check ModelMatrix and NumPy Array Instance Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Verify if a generated model matrix, when output as a numpy array, is an instance of both ModelMatrix and numpy.ndarray. ```python import numpy from formulaic import ModelMatrix mm = Formula("a + b:c").get_model_matrix(data, output="numpy") isinstance(mm, ModelMatrix), isinstance(mm, numpy.ndarray) ``` -------------------------------- ### Create Model Matrix with Categorical Data Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/contrasts.ipynb Use this to generate a model matrix from a DataFrame containing categorical and numerical data. Formulaic automatically detects categorical columns based on their content or data type. ```python from pandas import Categorical, DataFrame from formulaic import model_matrix df = DataFrame( { "letters": ["a", "b", "c"], "numbers": Categorical([1, 2, 3]), "values": [20, 200, 30], } ) model_matrix("letters + numbers + values", df) ``` -------------------------------- ### Generate Model Matrix from Formula and Data Source: https://github.com/matthewwardrop/formulaic/blob/main/docsite/docs/guides/formulae.ipynb Use the get_model_matrix method of a Formula object, passing in a pandas DataFrame, to generate a model matrix. ```python import pandas data = pandas.DataFrame( {"a": [1, 2, 3], "b": [4, 5, 6], "c": [7, 8, 9], "A": ["a", "b", "c"]} ) Formula("a + b:c").get_model_matrix(data) ```