fiasto 0.1.6

High-performance modern Wilkinson's formula parsing for statistical models. Parses R-style formulas into structured JSON metadata supporting linear models, mixed effects, and complex statistical specifications.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

pub mod internal {
    pub mod parse;
    pub mod ast;
    pub mod data_structures;
    pub mod errors;
    pub mod lexer;
    pub mod meta_builder;
    pub mod parser;
    pub mod new;
    pub mod peek;
    pub mod next;
    pub mod matches;
    pub mod expect;
    pub mod parse_response;
    pub mod parse_formula;
    pub mod parse_rhs;
    pub mod parse_term;
    pub mod parse_arg_list;
    pub mod parse_arg;
    pub mod parse_family;
}

use internal::parse::{MetaBuilder, Parser, Term};
use serde_json::Value;

/// Parse a formula string and return the metadata as JSON
///
/// # Arguments
/// * `formula` - A string containing a formula in the format "y ~ x + poly(x, 2), family = gaussian"
/// `formula = "y ~ x + poly(x, 2) + poly(x1, 4) + log(x1) - 1, family = gaussian"`
/// ```text
/// {
///  "column_names": [
///    {
///      "id": 1,
///      "name": "y"
///    },
///    {
///      "id": 2,
///      "name": "x"
///    },
///    {
///      "id": 3,
///      "name": "x1"
///    }
///  ],
///  "fix_effects_columns": [
///    {
///      "column_name_struct_id": 2,
///      "name": "x"
///    },
///    {
///      "column_name_struct_id": 2,
///      "name": "poly(x, 2)"
///    },
///    {
///      "column_name_struct_id": 3,
///      "name": "poly(x1, 4)"
///    },
///    {
///      "column_name_struct_id": 3,
///      "name": "log(x1)"
///    }
///  ],
///  "formula": "y ~ x + poly(x, 2) + poly(x1, 4) + log(x1) - 1, family = gaussian",
///  "has_intercept": false,
///  "random_effects_columns": [],
///  "response_columns": [
///    {
///      "column_name_struct_id": 1,
///      "name": "y"
///    }
///  ],
///  "transformations": [
///    {
///      "column_name_struct_id": 2,
///      "name": "poly"
///    },
///    {
///      "column_name_struct_id": 3,
///      "name": "poly"
///    },
///    {
///      "column_name_struct_id": 3,
///      "name": "log"
///    }
///  ]
/// }
/// ```
/// # Returns
/// * `Result<Value, Box<dyn std::error::Error>>` - The formula metadata as JSON, or an error
///
/// # Example
/// ```
/// use fiasto::parse_formula;
///
/// let result = parse_formula("y ~ x + poly(x, 2), family = gaussian");
/// match result {
///     Ok(metadata) => println!("{}", serde_json::to_string_pretty(&metadata).unwrap()),
///     Err(e) => eprintln!("Error: {}", e),
/// }
/// ```
pub fn parse_formula(formula: &str) -> Result<Value, Box<dyn std::error::Error>> {
    let mut p = Parser::new(formula)?;
    let (response, terms, has_intercept, _family_opt) = p.parse_formula()?;

    let mut mb = MetaBuilder::new();
    mb.push_response(&response);
    for t in terms {
        match t {
            Term::Column(name) => mb.push_plain_term(&name),
            Term::Function { name, args } => mb.push_function_term(&name, &args),
        }
    }
    let meta = mb.build(formula, has_intercept);

    Ok(serde_json::to_value(meta)?)
}