Catalog infrastructure updates

.gitignore

@@ -51,4 +51,4 @@ Gambit.app/*
 build_support/msw/gambit.wxs
 build_support/osx/Info.plist
 src/pygambit/catalog
-doc/catalog.csv
+doc/catalog_table.rst

build_support/catalog/update.py

@@ -1,13 +1,106 @@
 import argparse
 from pathlib import Path
 
+import pandas as pd
+
 import pygambit as gbt
 
-CATALOG_CSV = Path(__file__).parent.parent.parent / "doc" / "catalog.csv"
+CATALOG_RST_TABLE = Path(__file__).parent.parent.parent / "doc" / "catalog_table.rst"
 CATALOG_DIR = Path(__file__).parent.parent.parent / "catalog"
 MAKEFILE_AM = Path(__file__).parent.parent.parent / "Makefile.am"
 
 
+def _write_efg_table(df: pd.DataFrame, f):
+    """Write the EFG games list-table to file handle f."""
+    f.write(".. list-table::\n")
+    f.write("   :header-rows: 1\n")
+    f.write("   :widths: 100\n")
+    f.write("   :class: tight-table\n")
+    f.write("\n")
+    f.write("   * - **Extensive form games**\n")
+
+    efg_df = df[df["Format"] == "efg"]
+    for _, row in efg_df.iterrows():
+        slug = row["Game"]
+        title = str(row.get("Title", "")).strip()
+        description = str(row.get("Description", "")).strip()
+        # Skip any games which lack a description
+        if description:
+            # Main dropdown
+            f.write(f"   * - .. dropdown:: {title}\n")
+            f.write("          :open:\n")
+            f.write("          \n")
+            for line in description.splitlines():
+                f.write(f"          {line}\n")
+            f.write("          \n")
+            f.write("          **Load in PyGambit:**\n")
+            f.write("          \n")
+            f.write("          .. code-block:: python\n")
+            f.write("             \n")
+            f.write(f'             pygambit.catalog.load("{slug}")\n')
+            f.write("          \n")
+
+            # Download links (inside the dropdown)
+            download_links = [row["Download"]]
+            f.write("          **Download:**\n")
+            f.write("          \n")
+            f.write(f"          {' '.join(download_links)}\n")
+            f.write("       \n")
+
+
+# def _write_nfg_table(df: pd.DataFrame, f):
+#     """Write the NFG games list-table to file handle f."""
+#     f.write(".. list-table::\n")
+#     f.write("   :header-rows: 1\n")
+#     f.write("   :widths: 100\n")
+#     f.write("   :class: tight-table\n")
+#     f.write("\n")
+#     f.write("   * - **Strategic form games**\n")
+
+#     nfg_df = df[df["Format"] == "nfg"]
+#     for _, row in nfg_df.iterrows():
+#         slug = row["Game"]
+
+#         # Title as plain text header
+#         f.write("   * - \n")
+#         f.write("       \n")
+
+#         # Jupyter-execute block (no dropdown)
+#         f.write("       .. jupyter-execute::\n")
+#         f.write("          \n")
+#         f.write("          import pygambit\n")
+#         f.write(f'          pygambit.catalog.load("{slug}")\n')
+#         f.write("       \n")
+
+#         # Download link (plain, no dropdown)
+#         f.write(f"       :download:`{slug}.nfg <../catalog/{slug}.nfg>`\n")
+#         f.write("       \n")
+
+
+def generate_rst_table(df: pd.DataFrame, rst_path: Path):
+    """Generate RST output with two list-tables: one for EFG and one for NFG games."""
+
+    with open(rst_path, "w", encoding="utf-8") as f:
+        # TOC linking to both sections
+        # f.write(".. contents::\n")
+        # f.write("   :local:\n")
+        # f.write("   :depth: 1\n")
+        # f.write("\n")
+
+        # EFG section
+        # f.write("Extensive form games\n")
+        # f.write("--------------------\n")
+        # f.write("\n")
+        _write_efg_table(df, f)
+        # f.write("\n")
+
+        # # NFG section
+        # f.write("Strategic form games\n")
+        # f.write("--------------------\n")
+        # f.write("\n")
+        # _write_nfg_table(df, f)
+
+
 def update_makefile():
     """Update the Makefile.am with all games from the catalog."""
 
@@ -60,15 +153,14 @@ def update_makefile():
 
 
 if __name__ == "__main__":
-
     parser = argparse.ArgumentParser()
     parser.add_argument("--build", action="store_true")
     args = parser.parse_args()
 
-    # Create CSV used by RST docs page
-    gbt.catalog.games().to_csv(CATALOG_CSV, index=False)
-    print(f"Generated {CATALOG_CSV} for use in local docs build. DO NOT COMMIT.")
-
-    # Update the Makefile.am with the current list of catalog files
+    # Create RST list-table used by doc/catalog.rst
+    df = gbt.catalog.games(include_descriptions=True)
+    generate_rst_table(df, CATALOG_RST_TABLE)
+    print(f"Generated {CATALOG_RST_TABLE} for use in local docs build. DO NOT COMMIT.")
     if args.build:
+        # Update the Makefile.am with the current list of catalog files
         update_makefile()

catalog/__init__.py

@@ -1,5 +1,6 @@
 from importlib.resources import as_file, files
 from pathlib import Path
+from typing import Any
 
 import pandas as pd
 
@@ -17,44 +18,160 @@
 def load(slug: str) -> gbt.Game:
     """
     Load a game from the package catalog.
+
+    Parameters
+    ----------
+    slug : str
+        The slug of the game to load.
+
+    Returns
+    -------
+    gbt.Game
+        The loaded game.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the game does not exist in the catalog.
     """
     slug = str(Path(slug)).replace("\\", "/")
 
+    # Try to load from file
     for suffix, reader in READERS.items():
         resource_path = _CATALOG_RESOURCE / f"{slug}{suffix}"
-
         if resource_path.is_file():
-            # as_file ensures we have a real filesystem path for the reader
             with as_file(resource_path) as path:
                 return reader(str(path))
 
-    raise FileNotFoundError(f"No catalog entry called {slug}.nfg or {slug}.efg")
-
-
-def games() -> pd.DataFrame:
+    # Raise error if game does not exist
+    raise FileNotFoundError(f"No catalog entry called {slug}")
+
+
+def games(
+    n_actions: int | None = None,
+    n_contingencies: int | None = None,
+    n_infosets: int | None = None,
+    is_const_sum: bool | None = None,
+    is_perfect_recall: bool | None = None,
+    is_tree: bool | None = None,
+    min_payoff: float | None = None,
+    max_payoff: float | None = None,
+    n_nodes: int | None = None,
+    n_outcomes: int | None = None,
+    n_players: int | None = None,
+    n_strategies: int | None = None,
+    include_descriptions: bool = False,
+) -> pd.DataFrame:
     """
-    List games available in the package catalog, including subdirectories.
+    List games available in the package catalog.
+
+    Most arguments are treated as filters on the
+    attributes of the Game objects.
+
+    Parameters
+    ----------
+    n_actions: int, optional
+        The number of actions in the game. Only extensive games are returned.
+    n_contingencies: int, optional
+        The number of contingencies in the game.
+    n_infosets: int, optional
+        The number of information sets in the game. Only extensive games are returned.
+    is_const_sum: bool, optional
+        Whether the game is constant-sum.
+    is_perfect_recall: bool, optional
+        Whether the game has perfect recall.
+    is_tree: bool, optional
+        Whether the game is an extensive game (a tree).
+    min_payoff: float, optional
+        The minimum payoff in the game. Games returned have `min_payoff >= value`.
+    max_payoff: float, optional
+        The maximum payoff in the game. Games returned have `max_payoff <= value`.
+    n_nodes: int, optional
+        The number of nodes in the game. Only extensive games are returned.
+    n_outcomes: int, optional
+        The number of outcomes in the game.
+    n_players: int, optional
+        The number of players in the game.
+    n_strategies: int, optional
+        The number of pure strategies in the game.
+    include_descriptions: bool, optional
+        Whether to include the description of each game in the returned DataFrame.
+        Defaults to False.
+
+    Returns
+    -------
+    pd.DataFrame
+        A DataFrame with columns "Game" and "Title", where "Game" is the slug to load the game.
+        If `include_descriptions=True`, the DataFrame will also include a "Description" column.
     """
-    records: list[dict[str, str]] = []
-
-    # Using rglob("*") to find files in all subdirectories
+    records: list[dict[str, Any]] = []
+
+    def check_filters(game: gbt.Game) -> bool:
+        if n_actions is not None:
+            if not game.is_tree:
+                return False
+            if len(game.actions) != n_actions:
+                return False
+        if n_contingencies is not None and len(game.contingencies) != n_contingencies:
+            return False
+        if n_infosets is not None:
+            if not game.is_tree:
+                return False
+            if len(game.infosets) != n_infosets:
+                return False
+        if is_const_sum is not None and game.is_const_sum != is_const_sum:
+            return False
+        if is_perfect_recall is not None and game.is_perfect_recall != is_perfect_recall:
+            return False
+        if is_tree is not None and game.is_tree != is_tree:
+            return False
+        if min_payoff is not None and game.min_payoff < min_payoff:
+            return False
+        if max_payoff is not None and game.max_payoff > max_payoff:
+            return False
+        if n_nodes is not None:
+            if not game.is_tree:
+                return False
+            if len(game.nodes) != n_nodes:
+                return False
+        if n_outcomes is not None and len(game.outcomes) != n_outcomes:
+            return False
+        if n_players is not None and len(game.players) != n_players:
+            return False
+        return not (n_strategies is not None and len(game.strategies) != n_strategies)
+
+    def append_record(
+        slug: str,
+        game: gbt.Game,
+    ) -> None:
+        record = {
+            "Game": slug,
+            "Title": game.title,
+        }
+        if include_descriptions:
+            record["Description"] = game.description
+            ext = "efg" if game.is_tree else "nfg"
+            record["Download"] = f":download:`{slug}.{ext} <../catalog/{slug}.{ext}>`"
+            record["Format"] = ext
+        records.append(record)
+
+    # Add all the games stored as EFG/NFG files
     for resource_path in sorted(_CATALOG_RESOURCE.rglob("*")):
         reader = READERS.get(resource_path.suffix)
 
         if reader is not None and resource_path.is_file():
-
             # Calculate the path relative to the root resource
             # and remove the suffix to get the "slug"
             rel_path = resource_path.relative_to(_CATALOG_RESOURCE)
             slug = rel_path.with_suffix("").as_posix()
 
             with as_file(resource_path) as path:
                 game = reader(str(path))
-                records.append(
-                    {
-                        "Game": slug,
-                        "Title": game.title,
-                    }
-                )
+                if check_filters(game):
+                    append_record(slug, game)
 
+    if include_descriptions:
+        return pd.DataFrame.from_records(
+            records, columns=["Game", "Title", "Description", "Download", "Format"]
+        )
     return pd.DataFrame.from_records(records, columns=["Game", "Title"])

catalog/bagwell1995.efg

@@ -1,15 +1,12 @@
 EFG 2 R "Bagwell (GEB 1995) commitment and (un)observability" { "Player 1" "Player 2" }
 "This is a Stackelberg-type game with imperfectly observed commitment, following the
-analysis of Bagwell [^Bag1995].  The outcomes and payoffs are the same as in Bagwell's
+analysis of `Bag1995 <https://gambitproject.readthedocs.io/en/latest/biblio.html#Bag1995>`_.  The outcomes and payoffs are the same as in Bagwell's
 model.  This example sets the probability that the follower 'correctly' observes the
 leader's action as .99 (99/100).  The key result is that the only pure-strategy
 equilibrium that survives if observability is imperfect is the one in which players
 choose the actions that would form an equilibrium if the game was a *simultaneous-move*
 game.  There is an equilibrium in which the 'Stackelberg' action is played with high
 probability, but strictly less than one.
-
-[^Bag1995]: Bagwell, Kyle (1995)  Commitment and observability in games.
-    _Games and Economic Behavior_ 8: 271-280.
 "
 
 p "" 1 1 "" { "S" "C" } 0

catalog/myerson1991/fig2_1.efg

@@ -1,20 +1,14 @@
 EFG 2 R "A simple Poker game" { "Fred" "Alice" }
-"This is a simple game of one-card poker from Myerson [^Mye91], used as the
+"This is a simple game of one-card poker from `Mye91 <https://gambitproject.readthedocs.io/en/latest/biblio.html#Mye91>`_, used as the
 introductory example for game models.
 
 Note that as specified in the text, the game has the slightly unusual feature
 that folding with the high (red) card results in the player winning rather than
 losing.
 
-See also
---------
-reiley2008/fig1
+See also `Rei2008 <https://gambitproject.readthedocs.io/en/latest/biblio.html#Rei2008>`_
    Another one-card poker game where folding with the high card is a loss rather
    than a win.
-
-
-[^Mye1991]: Myerson, Roger B. (1991)  Game Theory: Analysis of Conflict.
-  Cambridge: Harvard University Press.
 "
 
 c "" 1 "" { "Red" 1/2 "Black" 1/2 } 0

catalog/myerson1991/fig4_2.efg

@@ -1,15 +1,12 @@
 EFG 2 R "Myerson (1991) Figure 4.2" { "Player 1" "Player 2" }
-"An example from Myerson [^Mye1991] which illustrates the distinction between
+"An example from `Mye91 <https://gambitproject.readthedocs.io/en/latest/biblio.html#Mye91>`_ which illustrates the distinction between
 an equilibrium of an extensive form game and an equilibrium of its
 (multi)agent representation.  The actions B1, Z1, and W2 form a
 behavior profile which is an equilibrium in the (multi)agent
 representation.  However, it is not a Nash equilibrium of the extensive
 game, because Player 1 would prefer to switch from (B1, Z1) to
 (A1, Y1); the (multi)agent representation rules out such coordinated
 deviations across information sets.
-
-[^Mye1991]: Myerson, Roger B. (1991)  Game Theory: Analysis of Conflict.
-  Cambridge: Harvard University Press.
 "
 
 p "" 1 1 "" { "A1" "B1" } 0

catalog/reiley2008/fig1.efg

@@ -1,14 +1,8 @@
 EFG 2 R "Stripped-down poker (Reiley et al 2008)" { "Professor" "Student" }
-"This is a one-card poker game used in [^Rei2008] as a teaching exercise.
+"This is a one-card poker game used in `Rei2008 <https://gambitproject.readthedocs.io/en/latest/biblio.html#Rei2008>`_ as a teaching exercise.
 
-See also
---------
-myerson1991/fig2_1
+See also `Mye91 <https://gambitproject.readthedocs.io/en/latest/biblio.html#Mye91>`_
     Another one-card poker game with slightly different rules.
-
-[^Rei2008]: Reiley, David H., Urbancic, Michael B, and Walker, Mark. (2008)
-    Stripped-Down Poker: A Classroom Game with Signaling and Bluffing.
-    _The Journal of Economic Education_ 4: 323-341.
 "
 
 c "" 1 "" { "King" 1/2 "Queen" 1/2 } 0