Draft: Add support for mixed effects.

formulaic/materializers/base.py

@@ -352,29 +352,37 @@ def _get_scoped_terms(self, terms, ensure_full_rank=True):
                 term_span = self._get_scoped_terms_spanned_by_evaled_factors(
                     evaled_factors
                 ).difference(spanned)
-                scoped_terms = self._simplify_scoped_terms(term_span)
                 spanned.update(term_span)
-            else:
-                scoped_terms = [
-                    ScopedTerm(
-                        factors=(
-                            ScopedFactor(evaled_factor, reduced=False)
-                            for evaled_factor in evaled_factors
-                            if evaled_factor.metadata.kind is not Factor.Kind.CONSTANT
-                        ),
-                        scale=functools.reduce(
-                            operator.mul,
-                            [
-                                evaled_factor.values
-                                for evaled_factor in evaled_factors
-                                if evaled_factor.metadata.kind.value
-                                is Factor.Kind.CONSTANT
-                            ],
-                            1,
-                        ),
-                    )
-                ]
-            yield term, scoped_terms
+
+                if not term.preserve_rank:
+                    yield term, self._simplify_scoped_terms(term_span)
+                    continue
+            yield term, [self._get_scoped_term_for_evaled_factors(evaled_factors)]
+
+    @classmethod
+    def _get_scoped_term_for_evaled_factors(
+        self, evaled_factors: List[EvaluatedFactor]
+    ) -> ScopedTerm:
+        """
+        Convert evaluated factors directly into a `ScopedTerm`. Useful for when
+        you want to preserve the factors of a evaluated factor.
+        """
+        return ScopedTerm(
+            factors=(
+                ScopedFactor(evaled_factor, reduced=False)
+                for evaled_factor in evaled_factors
+                if evaled_factor.metadata.kind is not Factor.Kind.CONSTANT
+            ),
+            scale=functools.reduce(
+                operator.mul,
+                [
+                    evaled_factor.values
+                    for evaled_factor in evaled_factors
+                    if evaled_factor.metadata.kind.value is Factor.Kind.CONSTANT
+                ],
+                1,
+            ),
+        )
 
     @classmethod
     def _get_scoped_terms_spanned_by_evaled_factors(

formulaic/parser/parser.py

@@ -12,6 +12,7 @@
     OperatorResolver,
     Structured,
     Term,
+    TermGroup,
     Token,
 )
 from .utils import (
@@ -101,7 +102,7 @@ def get_tokens(self, formula: str) -> Iterable[Token]:
                 ),
                 *insert_tokens_after(
                     tokens[rhs_index:],
-                    r"\|",
+                    r"\|+",
                     [token_one],
                     kind=Token.Kind.OPERATOR,
                     join_operator="+",
@@ -193,6 +194,40 @@ def power(arg: Set[Term], power: Set[Term]) -> Set[Term]:
                 ),
                 structural=True,
             ),
+            Operator(
+                "|",
+                arity=2,
+                precedence=50,
+                associativity="left",
+                to_terms=lambda terms, groups: (
+                    Structured(
+                        group={
+                            TermGroup(term, group)
+                            for term, group in itertools.product(
+                                terms, groups.difference({"1"})
+                            )
+                        },
+                    )
+                ),
+                accepts_context=lambda context: context and context[-1] == "(",
+            ),
+            Operator(
+                "||",
+                arity=2,
+                precedence=50,
+                associativity="left",
+                to_terms=lambda terms, groups: (
+                    Structured(
+                        group_independent={
+                            TermGroup(term, group, joiner="||")
+                            for term, group in itertools.product(
+                                terms, groups.difference({"1"})
+                            )
+                        },
+                    )
+                ),
+                accepts_context=lambda context: context and context[-1] == "(",
+            ),
             Operator(
                 "+",
                 arity=2,

formulaic/parser/types/__init__.py

@@ -4,7 +4,7 @@
 from .operator import Operator
 from .operator_resolver import OperatorResolver
 from .structured import Structured
-from .term import Term
+from .term import Term, TermGroup
 from .token import Token
 
 
@@ -16,5 +16,6 @@
     "OperatorResolver",
     "Structured",
     "Term",
+    "TermGroup",
     "Token",
 ]

formulaic/parser/types/term.py

@@ -13,10 +13,14 @@ class Term:
 
     Attributes:
         factors: The set of factors to be multipled to form the term.
+        preserve_rank: Whether to preserve the term structure even when
+            `ensure_full_rank` is specified. Other terms without this set may
+            still be affected by the presence of this term.
     """
 
-    def __init__(self, factors: Iterable["Factor"]):
+    def __init__(self, factors: Iterable["Factor"], preserve_rank: bool = False):
         self.factors = tuple(sorted(set(factors)))
+        self.preserve_rank = preserve_rank
         self._factor_exprs = tuple(factor.expr for factor in self.factors)
         self._hash = hash(repr(self))
 
@@ -48,3 +52,23 @@ def __lt__(self, other):
 
     def __repr__(self):
         return ":".join(self._factor_exprs)
+
+
+class TermGroup(Term):
+    """
+    Represents a group randomized term a formula.
+
+    Attributes:
+        term:
+        group:
+        joiner:
+    """
+
+    def __init__(self, term, group, joiner="|"):
+        self.term = term
+        self.group = group
+        self.joiner = joiner
+        super().__init__(factors=[*term.factors, *group.factors], preserve_rank=True)
+
+    def __repr__(self):
+        return repr(self.term) + self.joiner + repr(self.group)