pertpy 0.9.3__py3-none-any.whl → 0.9.5__py3-none-any.whl

pertpy/tools/_scgen/_scgen.py

@@ -18,12 +18,16 @@ from scvi.data.fields import CategoricalObsField, LayerField
 from scvi.model.base import BaseModelClass, JaxTrainingMixin
 from scvi.utils import setup_anndata_dsp
 
+from pertpy._doc import _doc_params, doc_common_plot_args
+
 from ._scgenvae import JaxSCGENVAE
 from ._utils import balancer, extractor
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
+    from matplotlib.pyplot import Figure
+
 font = {"family": "Arial", "size": 14}
 
 
@@ -377,9 +381,8 @@ class Scgen(JaxTrainingMixin, BaseModelClass):
         condition_key: str,
         axis_keys: dict[str, str],
         labels: dict[str, str],
-        save: str | bool | None = None,
+        *,
         gene_list: list[str] = None,
-        show: bool = False,
         top_100_genes: list[str] = None,
         verbose: bool = False,
         legend: bool = True,
@@ -387,6 +390,8 @@ class Scgen(JaxTrainingMixin, BaseModelClass):
         x_coeff: float = 0.30,
         y_coeff: float = 0.8,
         fontsize: float = 14,
+        show: bool = False,
+        save: str | bool | None = None,
         **kwargs,
     ) -> tuple[float, float] | float:
         """Plots mean matching for a set of specified genes.
@@ -397,21 +402,23 @@ class Scgen(JaxTrainingMixin, BaseModelClass):
                     corresponding to batch and cell type metadata, respectively.
             condition_key: The key for the condition
             axis_keys: Dictionary of `adata.obs` keys that are used by the axes of the plot. Has to be in the following form:
-                       `{"x": "Key for x-axis", "y": "Key for y-axis"}`.
-            labels: Dictionary of axes labels of the form `{"x": "x-axis-name", "y": "y-axis name"}`.
-            path_to_save: path to save the plot.
-            save: Specify if the plot should be saved or not.
+                       {`x`: `Key for x-axis`, `y`: `Key for y-axis`}.
+            labels: Dictionary of axes labels of the form {`x`: `x-axis-name`, `y`: `y-axis name`}.
             gene_list: list of gene names to be plotted.
-            show: if `True`: will show to the plot after saving it.
             top_100_genes: List of the top 100 differentially expressed genes. Specify if you want the top 100 DEGs to be assessed extra.
-            verbose: Specify if you want information to be printed while creating the plot.,
+            verbose: Specify if you want information to be printed while creating the plot.
             legend: Whether to plot a legend.
             title: Set if you want the plot to display a title.
             x_coeff: Offset to print the R^2 value in x-direction.
             y_coeff: Offset to print the R^2 value in y-direction.
             fontsize: Fontsize used for text in the plot.
+            show: if `True`, will show to the plot after saving it.
+            save: Specify if the plot should be saved or not.
             **kwargs:
 
+        Returns:
+            Returns R^2 value for all genes and R^2 value for top 100 DEGs if `top_100_genes` is not `None`.
+
         Examples:
             >>> import pertpy as pt
             >>> data = pt.dt.kang_2018()
@@ -498,6 +505,7 @@ class Scgen(JaxTrainingMixin, BaseModelClass):
                 r"$\mathrm{R^2_{\mathrm{\mathsf{top\ 100\ DEGs}}}}$= " + f"{r_value_diff ** 2:.2f}",
                 fontsize=kwargs.get("textsize", fontsize),
             )
+
         if save:
             plt.savefig(save, bbox_inches="tight")
         if show:
@@ -514,16 +522,17 @@ class Scgen(JaxTrainingMixin, BaseModelClass):
         condition_key: str,
         axis_keys: dict[str, str],
         labels: dict[str, str],
-        save: str | bool | None = None,
+        *,
         gene_list: list[str] = None,
         top_100_genes: list[str] = None,
-        show: bool = False,
         legend: bool = True,
         title: str = None,
         verbose: bool = False,
         x_coeff: float = 0.3,
         y_coeff: float = 0.8,
         fontsize: float = 14,
+        show: bool = True,
+        save: str | bool | None = None,
         **kwargs,
     ) -> tuple[float, float] | float:
         """Plots variance matching for a set of specified genes.
@@ -534,19 +543,18 @@ class Scgen(JaxTrainingMixin, BaseModelClass):
                    corresponding to batch and cell type metadata, respectively.
             condition_key: Key of the condition.
             axis_keys: Dictionary of `adata.obs` keys that are used by the axes of the plot. Has to be in the following form:
-                       `{"x": "Key for x-axis", "y": "Key for y-axis"}`.
-            labels: Dictionary of axes labels of the form `{"x": "x-axis-name", "y": "y-axis name"}`.
-            path_to_save: path to save the plot.
-            save: Specify if the plot should be saved or not.
+                       {"x": "Key for x-axis", "y": "Key for y-axis"}.
+            labels: Dictionary of axes labels of the form {"x": "x-axis-name", "y": "y-axis name"}.
             gene_list: list of gene names to be plotted.
-            show: if `True`: will show to the plot after saving it.
             top_100_genes: List of the top 100 differentially expressed genes. Specify if you want the top 100 DEGs to be assessed extra.
-            legend: Whether to plot a elgend
+            legend: Whether to plot a legend.
             title: Set if you want the plot to display a title.
             verbose: Specify if you want information to be printed while creating the plot.
             x_coeff: Offset to print the R^2 value in x-direction.
             y_coeff: Offset to print the R^2 value in y-direction.
             fontsize: Fontsize used for text in the plot.
+            show: if `True`, will show to the plot after saving it.
+            save: Specify if the plot should be saved or not.
         """
         import seaborn as sns
 
@@ -636,6 +644,7 @@ class Scgen(JaxTrainingMixin, BaseModelClass):
         else:
             return r_value**2
 
+    @_doc_params(common_plot_args=doc_common_plot_args)
     def plot_binary_classifier(
         self,
         scgen: Scgen,
@@ -643,10 +652,11 @@ class Scgen(JaxTrainingMixin, BaseModelClass):
         delta: np.ndarray,
         ctrl_key: str,
         stim_key: str,
-        show: bool = False,
-        save: str | bool | None = None,
+        *,
         fontsize: float = 14,
-    ) -> plt.Axes | None:
+        show: bool = True,
+        return_fig: bool = False,
+    ) -> Figure | None:
         """Plots the dot product between delta and latent representation of a linear classifier.
 
         Builds a linear classifier based on the dot product between
@@ -661,9 +671,11 @@ class Scgen(JaxTrainingMixin, BaseModelClass):
             delta: Difference between stimulated and control cells in latent space
             ctrl_key: Key for `control` part of the `data` found in `condition_key`.
             stim_key: Key for `stimulated` part of the `data` found in `condition_key`.
-            path_to_save: Path to save the plot.
-            save: Specify if the plot should be saved or not.
             fontsize: Set the font size of the plot.
+            {common_plot_args}
+
+        Returns:
+            If `return_fig` is `True`, returns the figure, otherwise `None`.
         """
         plt.close("all")
         adata = scgen._validate_anndata(adata)
@@ -693,12 +705,10 @@ class Scgen(JaxTrainingMixin, BaseModelClass):
         ax = plt.gca()
         ax.grid(False)
 
-        if save:
-            plt.savefig(save, bbox_inches="tight")
         if show:
             plt.show()
-        if not (show or save):
-            return ax
+        if return_fig:
+            return plt.gcf()
         return None
 
 

{pertpy-0.9.3.dist-info → pertpy-0.9.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: pertpy
-Version: 0.9.3
+Version: 0.9.5
 Summary: Perturbation Analysis in the scverse ecosystem.
 Project-URL: Documentation, https://pertpy.readthedocs.io
 Project-URL: Source, https://github.com/scverse/pertpy
@@ -44,7 +44,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Classifier: Topic :: Scientific/Engineering :: Visualization
-Requires-Python: >=3.10
+Requires-Python: <3.13,>=3.10
 Requires-Dist: adjusttext
 Requires-Dist: blitzgsea
 Requires-Dist: decoupler
@@ -68,7 +68,8 @@ Requires-Dist: pyqt5; extra == 'coda'
 Requires-Dist: toytree; extra == 'coda'
 Provides-Extra: de
 Requires-Dist: formulaic; extra == 'de'
-Requires-Dist: pydeseq2; extra == 'de'
+Requires-Dist: formulaic-contrasts>=0.2.0; extra == 'de'
+Requires-Dist: pydeseq2>=v0.5.0pre1; extra == 'de'
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == 'dev'
 Provides-Extra: doc

{pertpy-0.9.3.dist-info → pertpy-0.9.5.dist-info}/RECORD

@@ -1,57 +1,57 @@
-pertpy/__init__.py,sha256=BDOzyW_PnNzv7Nfa8Skj90mC9T1ILiYtxI_bPXwhc1E,658
+pertpy/__init__.py,sha256=r5QhDw2-Ls4yYLs1kJJVe_r6dstQ7SjoASFutlTU9JA,658
+pertpy/_doc.py,sha256=pVt5Iegvh4rC1N81fd9e4cwmoGPNSgttZxxPWbLK6Bs,453
 pertpy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pertpy/data/__init__.py,sha256=ah3yvoxkgbdMUNAWxS3SyqcUuVamBOSeuWkF2QRAEwM,2703
-pertpy/data/_dataloader.py,sha256=fl16n82nun01gGiP7qhr5sShfcDchp0szzZp7aXkfBI,2495
-pertpy/data/_datasets.py,sha256=I-keaJSTsRBySCPjiVonKmC9rRIM0AEgo0_0UlEX804,65616
+pertpy/data/_dataloader.py,sha256=ENbk1T3w3N6tVI11V4FVUxuWFEwOHP8_kIB-ehiMlVQ,2428
+pertpy/data/_datasets.py,sha256=c_U2U2NvncPZc6vs6w_s77zmWqr8ywDpzmkx6edCfUE,65616
 pertpy/metadata/__init__.py,sha256=zoE_VXNyuKa4nlXlUk2nTgsHRW3jSQSpDEulcCnzOT0,222
-pertpy/metadata/_cell_line.py,sha256=-8KSqmP5XjmLEmNX3TavxSM_MtIHwLWS_x3MVkk6JEw,38595
-pertpy/metadata/_compound.py,sha256=JEFwP_TOTyMzfd2qFMb2VkJJvPhCVIvu6gs9Bq_stgs,4756
+pertpy/metadata/_cell_line.py,sha256=Ell5PDVoMlrhHXPDKGCiPGwNY0DAeghbUUvTYL-SFF0,38919
+pertpy/metadata/_compound.py,sha256=ywNNqtib0exHv0z8ctmTRf1Hk64tSGWSiUEffycxf6A,4755
 pertpy/metadata/_drug.py,sha256=8QDSyxiFl25JdS80EQJC_krg6fEe5LIQEE6BsV1r8nY,9006
 pertpy/metadata/_look_up.py,sha256=DoWp6OxIk_HyyyOhW1p8z5E68IZ31_nZDnqxk1rJqps,28778
-pertpy/metadata/_metadata.py,sha256=pvarnv3X5pblnvG8AQ8Omu5jQcC5ORzCxRk3FRhOLgs,3276
+pertpy/metadata/_metadata.py,sha256=hV2LTFrExddLNU_RsDkZju6lQUSRoP4OIn_dumCyQao,3277
 pertpy/metadata/_moa.py,sha256=u_OcMonjOeeoW5P9xOltquVSoTH3Vs80ztHsXf-X1DY,4701
 pertpy/plot/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pertpy/preprocessing/__init__.py,sha256=VAPFaeq2_qCvdFkQTCj_Hm460HC4Tersu8Rig_tnp_Y,71
-pertpy/preprocessing/_guide_rna.py,sha256=IgKhXEyfRwEA7ccKJNLA_aIxKHm09QJINM09KaIwn68,7644
-pertpy/tools/__init__.py,sha256=Zl4W4bWDIIUVRUFDh1qjT14Rg2hjJ6gvRHcupV_sywk,2647
-pertpy/tools/_augur.py,sha256=UWro1nIEZe_rWtjlQCBv4ucqeh3Vt1m8IRzKlux72Z8,55683
-pertpy/tools/_cinemaot.py,sha256=BD_oYC1TktbFMX7fpp0A57QAF6frLEgNQ_2wFUpxjyo,39509
-pertpy/tools/_dialogue.py,sha256=f2fbhKWdm4Co79ZzVgtVq9xYwjYWFLdGNDeGFOO_pfM,51990
-pertpy/tools/_enrichment.py,sha256=rjPHK9YBCJZfpa5Rvfxo3Ii7W5Mvm5dOdolAD7QazVg,21440
+pertpy/preprocessing/_guide_rna.py,sha256=D9hEh8LOOTs_UfVBsBW3b-o6ipRFq09J471Hg1s0tlM,7963
+pertpy/tools/__init__.py,sha256=NUTwCGxRdzUzLTgsS3r7MywENwPAdcGZDKrl83sU8mo,2599
+pertpy/tools/_augur.py,sha256=Vghsx5-fYlaEeu__8-HUg6v5_KoVNhiRDjhgE3pORpY,55339
+pertpy/tools/_cinemaot.py,sha256=U6vCb_mI4ZPFshYgsx-hOOsDA1IPwI7ZR_-IH4F9s7s,39621
+pertpy/tools/_dialogue.py,sha256=BShXZ1ehO2eMbP5PV-ONJ-1SsxD6h9nAN7bGQ4_F6Rw,51906
+pertpy/tools/_enrichment.py,sha256=jxVdOrpS_lAu7GCpemgdB4JJvsGH9SJTQsAKLBKi9Tc,21640
 pertpy/tools/_kernel_pca.py,sha256=_EJ9WlBLjHOafF34sZGdyBgZL6Fj0WiJ1elVT1XMmo4,1579
-pertpy/tools/_milo.py,sha256=FDFGmGMkJiVrvATEnOeAMCe-Q2w7F0nbBMuACVbyIQI,43699
-pertpy/tools/_mixscape.py,sha256=FtH3PKvbLTe03LPgN4O9sS70oj_6AHz4Mz5otzEwRl8,52406
+pertpy/tools/_milo.py,sha256=SQqknT2zkzI0pcUmTm0ijWMs7CFMRiyRnXt9rC0jvmg,43811
+pertpy/tools/_mixscape.py,sha256=T-oUHDnepao5aujAHw9bAbbQHPSK6oD_8Wr_mw4U0nc,52089
 pertpy/tools/decoupler_LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
 pertpy/tools/transferlearning_MMD_LICENSE,sha256=MUvDA-o_j9htRpI8fStVdCRuyLdPkQUuIH0a_EIc57w,1069
 pertpy/tools/_coda/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pertpy/tools/_coda/_base_coda.py,sha256=jnoLPFfluxB0_CK8-T-qolPa7xPIEb6NpeEpGwHPiNg,113058
+pertpy/tools/_coda/_base_coda.py,sha256=Uxb_vAORL77LkUri8QqL9SxaULK4hfpgRGsCQdtsAgk,111808
 pertpy/tools/_coda/_sccoda.py,sha256=gGmyd0MGpchulV9d4PxKSmGORyZ8fCDS9tQVPOuF_Og,22622
 pertpy/tools/_coda/_tasccoda.py,sha256=vNk43OQHn7pBLsez2rmSj0bMZKOf8jZTI7G8TfBByRg,30665
-pertpy/tools/_differential_gene_expression/__init__.py,sha256=sabAXym8mMLwp19ZjyBN7wp-oJh32iVj9plvJ-AbXlE,521
-pertpy/tools/_differential_gene_expression/_base.py,sha256=qnQkK_hyIcViHBSkgJcAazC26JQ72bEyafKiytZikCY,23624
+pertpy/tools/_differential_gene_expression/__init__.py,sha256=SEydWg0iT3Y1pApjnCAOuHxFeI6xVUfgyBHv2s3LADU,487
+pertpy/tools/_differential_gene_expression/_base.py,sha256=yc9DBj2KgJVk4mkjz7EDFoBj8WBZW92Z4ayD-Xdla1g,38514
 pertpy/tools/_differential_gene_expression/_checks.py,sha256=SxNHJDsCYZ6rWLTMEymEBpigs_B9cnXyw0kkAe1l6e0,1675
 pertpy/tools/_differential_gene_expression/_dge_comparison.py,sha256=9HjmWkrqZhj_ZJeR-ymyEDzpRJNx7JiYJoStvCfKuCU,4188
-pertpy/tools/_differential_gene_expression/_edger.py,sha256=JziiW5rkXuQBJISAD_LvB2HOZUgJ1_qoqiR5Q4hEoP0,4321
-pertpy/tools/_differential_gene_expression/_formulaic.py,sha256=X4rPv4j8SDu5VJnf6_AIYJCCquUQka7G2LGtDLa8FhE,8715
-pertpy/tools/_differential_gene_expression/_pydeseq2.py,sha256=JK7H7u4va0q_TLE_sqi4JEzoPBd_xNRycYGu1507HS4,4117
+pertpy/tools/_differential_gene_expression/_edger.py,sha256=ttgTocAYnr8BTDcixwHGjRZew6zeja-U77TLKkSdd1Y,4857
+pertpy/tools/_differential_gene_expression/_pydeseq2.py,sha256=aOqsdu8hKp8_h2HhjkxS0B_itxRBnzEU2oSnU2PYiQ4,2942
 pertpy/tools/_differential_gene_expression/_simple_tests.py,sha256=tTSr0Z2Qbpxdy9bcO8Gi_up6R616IcoK_e4_rlanyx4,6621
-pertpy/tools/_differential_gene_expression/_statsmodels.py,sha256=zSOwJYDJyrl3hsEhMI5Q9Pyw2XLuEuj7T0zSAVcP6tQ,2585
+pertpy/tools/_differential_gene_expression/_statsmodels.py,sha256=jBCtaCglOvvVjkIBGXuTCTDB6g2AJsZMCf7iOlDyn48,2195
 pertpy/tools/_distances/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pertpy/tools/_distances/_distance_tests.py,sha256=mNmNu5cX0Wj5IegR6x5K-CbBSid8EhrH2jZPQxuvK4U,13521
-pertpy/tools/_distances/_distances.py,sha256=iuHpBtWZbJhMZNSEjQkZUu6KPJXCjs_fX6YjopIWvwY,50343
+pertpy/tools/_distances/_distances.py,sha256=CmrOKevVCTY9j3PzhpVc3ga6SwZy9wbbJa0_7bwLMWQ,50569
 pertpy/tools/_perturbation_space/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pertpy/tools/_perturbation_space/_clustering.py,sha256=m52-J8c8OnIXRCf3NoFabIO2yMHIuy1X0m0amtsK2vE,3556
 pertpy/tools/_perturbation_space/_comparison.py,sha256=rLO-EGU0I7t5MnLw4k1gYU-ypRu-JsDPLat1t4h2U2M,4329
 pertpy/tools/_perturbation_space/_discriminator_classifiers.py,sha256=OA2eZeG_4iuW1T5ilsRIkS0rU-azmwEch7IuB546KSY,21617
 pertpy/tools/_perturbation_space/_metrics.py,sha256=y8-baP8WRdB1iDgvP3uuQxSCDxA2lcxvEHHM2C_vWHY,3248
-pertpy/tools/_perturbation_space/_perturbation_space.py,sha256=cZPPzzK4_UZV7ktcD5BQVXEy6ITHrfkg1CLFov3TzsY,18497
-pertpy/tools/_perturbation_space/_simple.py,sha256=LH5EYvcAbzFMvgd9bH7AUPKFmdioPiy2xG8xGaXzmq0,12624
+pertpy/tools/_perturbation_space/_perturbation_space.py,sha256=F-F-_pMCTWxjkVQSLre6hrE6PeRfCRscpt2ug3NlfuU,19531
+pertpy/tools/_perturbation_space/_simple.py,sha256=RQv6B0xPq4RJa5zlkLkxMYXQ3LAJLglmQDGaTMseaA8,14238
 pertpy/tools/_scgen/__init__.py,sha256=uERFlFyF88TH0uLiwmsUGEfHfLVCiZMFuk8gO5f7164,45
 pertpy/tools/_scgen/_base_components.py,sha256=Qq8myRUm43q9XBrZ9gBggfa2cSV2wbz_KYoLgH7iF1A,3009
-pertpy/tools/_scgen/_scgen.py,sha256=HPvFVjY9SS9bGqgTkCDuPYjmA4QHW7rKgHnI2yuI_Q4,30608
+pertpy/tools/_scgen/_scgen.py,sha256=oVY2JNYhDn1OrPoq22ATIP5-H615BafidBCC0eC5C-4,30756
 pertpy/tools/_scgen/_scgenvae.py,sha256=v_6tZ4wY-JjdMH1QVd_wG4_N0PoaqB-FM8zC2JsDu1o,3935
 pertpy/tools/_scgen/_utils.py,sha256=1upgOt1FpadfvNG05YpMjYYG-IAlxrC3l_ZxczmIczo,2841
-pertpy-0.9.3.dist-info/METADATA,sha256=S6HYSnvP3MYzaICvPCVeFkkOd6HSQU14kMzRTv2RUkI,6852
-pertpy-0.9.3.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
-pertpy-0.9.3.dist-info/licenses/LICENSE,sha256=OZ-ZkXM5CmExJiEMM90b_7dGNNvRpj7kdE-49AnrLuI,1070
-pertpy-0.9.3.dist-info/RECORD,,
+pertpy-0.9.5.dist-info/METADATA,sha256=vuf16H5cVKgNKRg35pFSWN7Oa7tT4IOLqqymVzZfnr4,6927
+pertpy-0.9.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pertpy-0.9.5.dist-info/licenses/LICENSE,sha256=OZ-ZkXM5CmExJiEMM90b_7dGNNvRpj7kdE-49AnrLuI,1070
+pertpy-0.9.5.dist-info/RECORD,,

{pertpy-0.9.3.dist-info → pertpy-0.9.5.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.25.0
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any

pertpy/tools/_differential_gene_expression/_formulaic.py

@@ -1,189 +0,0 @@
-"""Helpers to interact with Formulaic Formulas
-
-Some helpful definitions for working with formulaic formulas (e.g. `~ 0 + C(donor):treatment + np.log1p(continuous)`):
- * A *term* refers to an expression in the formula, separated by `+`, e.g. `C(donor):treatment`, or `np.log1p(continuous)`.
- * A *variable* refers to a column of the data frame passed to formulaic, e.g. `donor`.
- * A *factor* is the specification of how a certain variable is represented in the design matrix, e.g. treatment coding with base level "A" and reduced rank.
-"""
-
-from collections import defaultdict
-from collections.abc import Mapping, Sequence
-from dataclasses import dataclass
-from typing import Any
-
-from formulaic import FactorValues, ModelSpec
-from formulaic.materializers import PandasMaterializer
-from formulaic.materializers.types import EvaluatedFactor
-from formulaic.parser.types import Factor
-from interface_meta import override
-
-
-@dataclass
-class FactorMetadata:
-    """Store (relevant) metadata for a factor of a formula."""
-
-    name: str
-    """The unambiguous factor name as specified in the formula. E.g. `donor`, or `C(donor, contr.treatment(base="A"))`"""
-
-    reduced_rank: bool
-    """Whether a column will be dropped because it is redundant"""
-
-    custom_encoder: bool
-    """Whether or not a custom encoder (e.g. `C(...)`) was used."""
-
-    categories: Sequence[str]
-    """The unique categories in this factor (after applying `drop_rows`)"""
-
-    kind: Factor.Kind
-    """Type of the factor"""
-
-    drop_field: str = None
-    """The category that is dropped.
-
-    Note that
-      * this may also be populated if `reduced_rank = False`
-      * this is only populated when no encoder was used (e.g. `~ donor` but NOT `~ C(donor)`.
-    """
-
-    column_names: Sequence[str] = None
-    """The column names for this factor included in the design matrix.
-
-    This may be the same as `categories` if the default encoder is used, or
-    categories without the base level if a custom encoder (e.g. `C(...)`) is used.
-    """
-
-    colname_format: str = None
-    """A formattable string that can be used to generate the column name in the design matrix, e.g. `{name}[T.{field}]`"""
-
-    @property
-    def base(self) -> str | None:
-        """
-        The base category for this categorical factor.
-
-        This is derived from `drop_field` (for default encoding) or by comparing the column names in
-        the design matrix with all categories (for custom encoding, e.g. `C(...)`).
-        """
-        if not self.reduced_rank:
-            return None
-        else:
-            if self.custom_encoder:
-                tmp_base = set(self.categories) - set(self.column_names)
-                assert len(tmp_base) == 1
-                return tmp_base.pop()
-            else:
-                assert self.drop_field is not None
-                return self.drop_field
-
-
-def get_factor_storage_and_materializer() -> tuple[dict[str, list[FactorMetadata]], dict[str, set[str]], type]:
-    """Keeps track of categorical factors used in a model specification by generating a custom materializer.
-
-    This materializer reports back metadata upon materialization of the model matrix.
-
-    Returns:
-        - A dictionary storing metadata for each factor processed by the custom materializer, named `factor_storage`.
-        - A dictionary mapping variables to factor names, which works similarly to model_spec.variable_terms
-            but maps to factors rather than terms, named `variable_to_factors`.
-        - A materializer class tied to the specific instance of `factor_storage`.
-    """
-    # There can be multiple FactorMetadata entries per sample, for instance when formulaic generates an interaction
-    # term, it generates the factor with both full rank and reduced rank.
-    factor_storage: dict[str, list[FactorMetadata]] = defaultdict(list)
-    variable_to_factors: dict[str, set[str]] = defaultdict(set)
-
-    class CustomPandasMaterializer(PandasMaterializer):
-        """An extension of the PandasMaterializer that records all categorical variables and their (base) categories."""
-
-        REGISTER_NAME = "custom_pandas"
-        REGISTER_INPUTS = ("pandas.core.frame.DataFrame",)
-        REGISTER_OUTPUTS = ("pandas", "numpy", "sparse")
-
-        def __init__(
-            self,
-            data: Any,
-            context: Mapping[str, Any] | None = None,
-            record_factor_metadata: bool = False,
-            **params: Any,
-        ):
-            """Initialize the Materializer.
-
-            Args:
-                data: Passed to PandasMaterializer.
-                context: Passed to PandasMaterializer
-                record_factor_metadata: Flag that tells whether this particular instance of the custom materializer class
-                    is supposed to record factor metadata. Only the instance that is used for building the design
-                    matrix should record the metadata. All other instances (e.g. used to generate contrast vectors)
-                    should not record metadata to not overwrite the specifications from the design matrix.
-                **params: Passed to PandasMaterializer
-            """
-            self.factor_metadata_storage = factor_storage if record_factor_metadata else None
-            self.variable_to_factors = variable_to_factors if record_factor_metadata else None
-            # temporary pointer to metadata of factor that is currently evaluated
-            self._current_factor: FactorMetadata = None
-            super().__init__(data, context, **params)
-
-        @override
-        def _encode_evaled_factor(
-            self, factor: EvaluatedFactor, spec: ModelSpec, drop_rows: Sequence[int], reduced_rank: bool = False
-        ) -> dict[str, Any]:
-            """Function is called just before the factor is evaluated.
-
-            We can record some metadata, before we call the original function.
-            """
-            assert (
-                self._current_factor is None
-            ), "_current_factor should always be None when we start recording metadata"
-            if self.factor_metadata_storage is not None:
-                # Don't store if the factor is cached (then we should already have recorded it)
-                if factor.expr in self.encoded_cache or (factor.expr, reduced_rank) in self.encoded_cache:
-                    assert factor.expr in self.factor_metadata_storage, "Factor should be there since it's cached"
-                else:
-                    for var in factor.variables:
-                        self.variable_to_factors[var].add(factor.expr)
-                    self._current_factor = FactorMetadata(
-                        name=factor.expr,
-                        reduced_rank=reduced_rank,
-                        categories=tuple(sorted(factor.values.drop(index=factor.values.index[drop_rows]).unique())),
-                        custom_encoder=factor.metadata.encoder is not None,
-                        kind=factor.metadata.kind,
-                    )
-            return super()._encode_evaled_factor(factor, spec, drop_rows, reduced_rank)
-
-        @override
-        def _flatten_encoded_evaled_factor(self, name: str, values: FactorValues[dict]) -> dict[str, Any]:
-            """
-            Function is called at the end, before the design matrix gets materialized.
-
-            Here we have access to additional metadata, such as `drop_field`.
-            """
-            if self._current_factor is not None:
-                assert self._current_factor.name == name
-                self._current_factor.drop_field = values.__formulaic_metadata__.drop_field
-                self._current_factor.column_names = values.__formulaic_metadata__.column_names
-                self._current_factor.colname_format = values.__formulaic_metadata__.format
-                self.factor_metadata_storage[name].append(self._current_factor)
-                self._current_factor = None
-
-            return super()._flatten_encoded_evaled_factor(name, values)
-
-    return factor_storage, variable_to_factors, CustomPandasMaterializer
-
-
-class AmbiguousAttributeError(ValueError):
-    pass
-
-
-def resolve_ambiguous(objs: Sequence[Any], attr: str) -> Any:
-    """Given a list of objects, return an attribute if it is the same between all object. Otherwise, raise an error."""
-    if not objs:
-        raise ValueError("Collection is empty")
-
-    first_obj_attr = getattr(objs[0], attr)
-
-    # Check if the attribute is the same for all objects
-    for obj in objs[1:]:
-        if getattr(obj, attr) != first_obj_attr:
-            raise AmbiguousAttributeError(f"Ambiguous attribute '{attr}': values differ between objects")
-
-    # If attribute is the same for all objects, return it
-    return first_obj_attr