Merge pull request #106 from rstudio/model-card

adding model card template

Author: isabelizimm

.gitignore

@@ -1,5 +1,6 @@
 /docs/site/*
-
+docs/source/reference
+vetiver/templates/*.html
 # Mac specific
 .DS_Store
 

vetiver/__init__.py

@@ -18,6 +18,7 @@
 from .handlers.xgboost import XGBoostHandler  # noqa
 from .rsconnect import deploy_rsconnect  # noqa
 from .monitor import compute_metrics, pin_metrics, plot_metrics, _rolling_df  # noqa
+from .model_card import model_card  # noqa
 
 __author__ = "Isabel Zimmerman <isabel.zimmerman@rstudio.com>"
 __all__ = []

vetiver/data/__init__.py

@@ -3,6 +3,7 @@
 sources = {
     "mtcars": _files("vetiver") / "data/mtcars.csv",
     "chicago": _files("vetiver") / "data/chicago.csv",
+    "sacramento": _files("vetiver") / "data/sacramento.csv",
 }
 
 
@@ -16,5 +17,6 @@ def __getattr__(k):
     f_path = sources.get("mtcars")
     if k == "chicago":
         f_path = sources.get("chicago")
-
+    elif k == "sacramento":
+        f_path = sources.get("sacramento")
     return pd.read_csv(f_path)

vetiver/data/sacramento.csv

@@ -0,0 +1,173 @@
+"price","type","sqft","beds","baths"
+68212,"Residential",1167,3,1
+89921,"Condo",1122,3,1
+98937,"Residential",1146,3,2
+122682,"Residential",1329,4,2
+123000,"Residential",1240,4,2
+124100,"Residential",1601,3,2
+126640,"Residential",1088,3,2
+131200,"Residential",1380,4,2
+141000,"Condo",1039,2,2
+146250,"Residential",1418,3,2
+149593,"Residential",1146,4,2
+152000,"Condo",1304,2,2
+164000,"Residential",1120,4,1
+173000,"Residential",1590,4,2
+181000,"Residential",1172,3,2
+189000,"Residential",1420,3,2
+195000,"Multi_Family",2162,4,4
+231477,"Residential",1478,3,2
+234697,"Residential",1287,3,2
+242638,"Residential",2163,3,2
+244500,"Residential",1473,3,3
+254200,"Residential",1921,4,2
+263500,"Residential",1713,4,2
+265000,"Condo",1672,3,2
+285000,"Residential",2056,4,2
+292024,"Residential",1126,2,1
+334150,"Residential",1690,2,1
+370500,"Residential",2734,4,3
+372000,"Residential",2110,3,2
+430000,"Residential",3615,5,3
+510000,"Residential",3508,5,4
+539000,"Residential",2462,4,2
+98000,"Residential",1220,2,1
+99000,"Residential",1643,3,1
+100000,"Condo",722,1,1
+111000,"Residential",1039,3,1
+123750,"Residential",1110,3,2
+126000,"Residential",1080,3,2
+135500,"Residential",1264,3,2
+145000,"Residential",1448,4,2
+146000,"Residential",1183,4,2
+150000,"Residential",1364,3,2
+161653,"Residential",1156,3,2
+175000,"Residential",1671,3,2
+180400,"Residential",1716,3,2
+205000,"Residential",1953,4,3
+230000,"Residential",1567,3,2
+236250,"Residential",1291,3,1
+256054,"Multi_Family",2085,5,4
+261000,"Residential",1567,3,2
+270000,"Residential",1531,3,2
+280000,"Residential",2494,4,3
+330000,"Residential",1258,3,2
+350000,"Residential",2295,4,3
+460000,"Residential",2129,3,2
+504000,"Residential",2791,3,3
+613401,"Residential",3838,4,3
+614000,"Residential",3059,4,3.5
+48000,"Condo",484,1,1
+100000,"Condo",625,1,1
+101000,"Residential",888,2,1
+114750,"Residential",779,2,1
+116100,"Residential",1174,3,1
+120000,"Multi_Family",1995,4,4
+123000,"Residential",1104,3,2
+130000,"Residential",1209,3,2
+133105,"Residential",1139,2,1
+136500,"Residential",1690,2,2
+145000,"Residential",1120,3,2
+147000,"Residential",1590,4,2
+149600,"Residential",1407,3,2
+150000,"Condo",1057,2,2
+150000,"Residential",1646,3,2
+165000,"Residential",1112,2,2
+168000,"Residential",1039,3,1
+188325,"Residential",1152,3,1
+215000,"Residential",1856,4,2
+220000,"Residential",950,2,1
+232000,"Residential",1375,3,2
+232500,"Condo",1250,2,2
+233641,"Residential",1058,3,1
+236000,"Multi_Family",2382,5,4
+240000,"Residential",1816,4,2
+252155,"Residential",1574,4,2
+254172,"Residential",1830,3,2
+261000,"Residential",1904,4,2
+270000,"Residential",1457,3,2
+285000,"Multi_Family",960,2,2
+296000,"Residential",2109,4,2
+304000,"Residential",2489,5,3
+305000,"Residential",1851,4,3
+325000,"Residential",2347,5,3
+351000,"Residential",2789,4,2
+355000,"Residential",3499,5,3.5
+360552,"Residential",1871,4,2
+362305,"Residential",1800,3,2
+395100,"Residential",3281,5,3
+408431,"Residential",2085,4,3
+445000,"Residential",2002,4,2
+500000,"Residential",1905,3,2
+677048,"Residential",2025,3,2
+95625,"Residential",1089,3,2
+115000,"Residential",911,2,1
+115000,"Condo",846,1,1
+115620,"Residential",1410,3,2
+131750,"Residential",1118,2,2
+137760,"Residential",1260,3,2
+176095,"Residential",1200,3,2
+176250,"Residential",1170,3,2
+178000,"Residential",1199,3,2
+190000,"Residential",796,2,1
+193000,"Residential",1452,3,2
+193500,"Residential",1513,3,2
+204918,"Residential",2306,4,2
+210944,"Condo",984,1,1
+212500,"Condo",1462,3,2.5
+220000,"Residential",1566,4,2
+220000,"Residential",1419,4,2
+220000,"Residential",1261,3,2
+232500,"Residential",2258,5,3
+233000,"Residential",1074,3,2
+242000,"Residential",1406,2,2
+243500,"Residential",1876,4,2
+247000,"Residential",1676,3,2
+249000,"Residential",1899,4,3
+260000,"Residential",1196,3,2
+270000,"Residential",2750,2,2
+271000,"Residential",1910,3,2.5
+280000,"Residential",1443,3,2
+285000,"Residential",1857,3,2
+289000,"Residential",2096,4,3
+290000,"Residential",1720,3,2
+294000,"Residential",1282,3,2
+299000,"Residential",1144,2,1
+300000,"Residential",1457,3,2
+300567,"Residential",1577,3,2
+310000,"Residential",1800,4,3
+315000,"Residential",3134,5,3
+326951,"Residential",1744,3,2
+331200,"Residential",2484,4,2
+335000,"Residential",1616,3,2
+350000,"Residential",2960,3,2
+375000,"Residential",2616,5,3
+380000,"Residential",1727,3,1
+400000,"Residential",3566,5,4
+455000,"Residential",2379,4,3
+600000,"Residential",3901,5,5
+61000,"Residential",876,2,1
+70000,"Residential",1011,2,1
+80000,"Residential",1158,4,2
+85500,"Residential",1092,3,2
+92000,"Condo",956,2,1
+112500,"Residential",1249,3,2
+114800,"Residential",1161,3,2
+128687,"Residential",962,3,1
+130000,"Residential",1127,3,2
+132000,"Residential",970,2,1
+145846,"Residential",1543,3,2
+150000,"Residential",1392,4,2
+170000,"Residential",1232,3,2
+171750,"Residential",1177,2,2
+172000,"Residential",1582,3,2
+176850,"Residential",1477,4,2
+189000,"Residential",1039,3,1
+191675,"Residential",1638,3,2
+209347,"Residential",1262,3,2
+216000,"Residential",1416,3,2
+216021,"Residential",888,3,1
+220000,"Residential",1770,4,2
+224252,"Residential",960,3,1
+228000,"Residential",1450,3,2
+235301,"Residential",1685,4,2

vetiver/model_card.py

@@ -0,0 +1,20 @@
+from importlib_resources import files as _files
+import shutil
+
+
+def model_card(path="."):
+    """Create a model card for documentation
+
+    Parameters
+    ----------
+    path : str
+       Path to save model card
+
+    Notes
+    -----
+    This model card is generated as a Quarto document. For more info on
+    Quarto, visit https://quarto.org/
+    """
+    src_path = _files("vetiver") / "templates/model_card.qmd"
+
+    return shutil.copy(src=src_path, dst=path)

vetiver/pin_read_write.py

@@ -1,7 +1,17 @@
 import warnings
-
 from .vetiver_model import VetiverModel
-from .write_fastapi import _choose_version
+
+
+class ModelCard(UserWarning):
+    def __init__(
+        self,
+        message="""
+        Model Cards provide a framework for transparent, responsible reporting.
+        Use the vetiver `.qmd` Quarto template as a place to start,
+        with vetiver.model_card()""",
+    ):
+        self.message = message
+        super().__init__(self.message)
 
 
 def vetiver_pin_write(board, model: VetiverModel, versioned: bool = True):
@@ -20,6 +30,9 @@ def vetiver_pin_write(board, model: VetiverModel, versioned: bool = True):
     if not board.allow_pickle_read:
         raise NotImplementedError  # must be pickle-able
 
+    warnings.simplefilter("once", ModelCard)
+    warnings.warn(ModelCard().message)
+
     board.pin_write(
         model.model,
         name=model.model_name,
@@ -32,15 +45,6 @@ def vetiver_pin_write(board, model: VetiverModel, versioned: bool = True):
         versioned=versioned,
     )
 
-    # to do: Model card
-
-    # message = """
-    # Create a Model Card for your published model.
-    # Model Cards provide a framework for transparent, responsible reporting.
-    # Use the vetiver `.Rmd` template as a place to start."""
-
-    # warnings.warn(message=message)
-
 
 def vetiver_pin_read(board, name: str, version: str = None) -> VetiverModel:
     """
@@ -72,10 +76,6 @@ def vetiver_pin_read(board, name: str, version: str = None) -> VetiverModel:
         DeprecationWarning,
     )
 
-    version = (
-        version if version is not None else _choose_version(board.pin_versions(name))
-    )
-
     v = VetiverModel.from_pin(board=board, name=name, version=version)
 
     return v