spells-mtg 0.3.1__py3-none-any.whl → 0.5.0__py3-none-any.whl

{spells_mtg-0.3.1.dist-info → spells_mtg-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: spells-mtg
-Version: 0.3.1
+Version: 0.5.0
 Summary: analaysis of 17Lands.com public datasets
 Author-Email: Joel Barnes <oelarnes@gmail.com>
 License: MIT
@@ -74,8 +74,9 @@ Spells is not affiliated with 17Lands. Please review the [Usage Guidelines](http
 - Supports calculating the standard aggregations and measures out of the box with no arguments (ALSA, GIH WR, etc)
 - Caches aggregate DataFrames in the local file system automatically for instantaneous reproduction of previous analysis
 - Manages grouping and filtering by built-in and custom columns at the row level
-- Provides 118 explicitly specified, enumerated, documented column definitions
+- Provides 122 explicitly specified, enumerated, documented column definitions
 - Supports "Deck Color Data" aggregations with built-in column definitions.
+- Lets you feed card metrics back in to column definitions to support scientific workflows like MLE
 - Provides a CLI tool `spells [add|refresh|clean|remove|info] [SET]` to download and manage external files
 - Downloads and manages public datasets from 17Lands
 - Retrieves and models booster configuration and card data from [MTGJSON](https://mtgjson.com/)
@@ -87,7 +88,7 @@ Spells is not affiliated with 17Lands. Please review the [Usage Guidelines](http
 
 ## summon
 
-`summon` takes four optional arguments, allowing a fully declarative specification of your desired analysis. Basic functionality not provided by this api can often be managed by simple chained calls using the polars API, e.g. sorting and post-agg filtering.
+`summon` takes five optional arguments, allowing a fully declarative specification of your desired analysis. Basic functionality not provided by this api can often be managed by simple chained calls using the polars API, e.g. sorting and post-agg filtering.
   - `columns` specifies the desired output columns
     ```python
     >>> spells.summon('DSK', columns=["num_gp", "pct_gp", "gp_wr", "gp_wr_z"])
@@ -112,24 +113,24 @@ Spells is not affiliated with 17Lands. Please review the [Usage Guidelines](http
     ```
   - `group_by` specifies the grouping by one or more columns. By default, group by card names, but optionally group by any of a large set of fundamental and derived columns, including card attributes and your own custom extension.
     ```python
-    >>> spells.summon('BLB', columns=["num_won", "num_games", "game_wr"], group_by=["main_colors"], filter_spec={"num_colors": 2})
-    shape: (10, 4)
-    ┌─────────────┬─────────┬───────────┬──────────┐
-    │ main_colors ┆ num_won ┆ num_games ┆ game_wr  │
-    │ ---         ┆ ---     ┆ ---       ┆ ---      │
-    │ str         ┆ u32     ┆ u32       ┆ f64      │
-    ╞═════════════╪═════════╪═══════════╪══════════╡
-    │ BG          ┆ 85022   ┆ 152863    ┆ 0.556197 │
-    │ BR          ┆ 45900   ┆ 81966     ┆ 0.559988 │
-    │ RG          ┆ 34641   ┆ 64428     ┆ 0.53767  │
-    │ UB          ┆ 30922   ┆ 57698     ┆ 0.535928 │
-    │ UG          ┆ 59879   ┆ 109145    ┆ 0.548619 │
-    │ UR          ┆ 19638   ┆ 38679     ┆ 0.507717 │
-    │ WB          ┆ 59480   ┆ 107443    ┆ 0.553596 │
-    │ WG          ┆ 76134   ┆ 136832    ┆ 0.556405 │
-    │ WR          ┆ 49712   ┆ 91224     ┆ 0.544944 │
-    │ WU          ┆ 16483   ┆ 31450     ┆ 0.524102 │
-    └─────────────┴─────────┴───────────┴──────────┘
+    >>> summon('BLB', columns=["num_won", "num_games", "game_wr", "deck_mana_value_avg"], group_by=["main_colors"], filter_spec={"num_colors": 2})
+    shape: (10, 5)
+    ┌─────────────┬─────────┬───────────┬──────────┬─────────────────────┐
+    │ main_colors ┆ num_won ┆ num_games ┆ game_wr  ┆ deck_mana_value_avg │
+    │ ---         ┆ ---     ┆ ---       ┆ ---      ┆ ---                 │
+    │ str         ┆ u32     ┆ u32       ┆ f64      ┆ f64                 │
+    ╞═════════════╪═════════╪═══════════╪══════════╪═════════════════════╡
+    │ BG          ┆ 85022   ┆ 152863    ┆ 0.556197 ┆ 2.862305            │
+    │ BR          ┆ 45900   ┆ 81966     ┆ 0.559988 ┆ 2.76198             │
+    │ RG          ┆ 34641   ┆ 64428     ┆ 0.53767  ┆ 2.852182            │
+    │ UB          ┆ 30922   ┆ 57698     ┆ 0.535928 ┆ 3.10409             │
+    │ UG          ┆ 59879   ┆ 109145    ┆ 0.548619 ┆ 2.861026            │
+    │ UR          ┆ 19638   ┆ 38679     ┆ 0.507717 ┆ 2.908215            │
+    │ WB          ┆ 59480   ┆ 107443    ┆ 0.553596 ┆ 2.9217              │
+    │ WG          ┆ 76134   ┆ 136832    ┆ 0.556405 ┆ 2.721064            │
+    │ WR          ┆ 49712   ┆ 91224     ┆ 0.544944 ┆ 2.5222              │
+    │ WU          ┆ 16483   ┆ 31450     ┆ 0.524102 ┆ 2.930967            │
+    └─────────────┴─────────┴───────────┴──────────┴─────────────────────┘ 
     ```
   - `filter_spec` specifies a row-level filter for the dataset, using an intuitive custom query formulation
     ```python
@@ -150,14 +151,13 @@ Spells is not affiliated with 17Lands. Please review the [Usage Guidelines](http
   - `extensions` allows for the specification of arbitrarily complex derived columns and aggregations, including custom columns built on top of custom columns.
     ```python
     >>> import polars as pl
-    >>> from spells.columns import ColumnSpec
+    >>> from spells.columns import ColSpec
     >>> from spells.enums import ColType, View, ColName
-    >>> ext = ColumnSpec(
+    >>> ext = ColSpec(
     ...     name='deq_base',
     ...     col_type=ColType.AGG,
     ...     expr=(pl.col('gp_wr_excess') + 0.03 * (1 - pl.col('ata')/14).pow(2)) * pl.col('pct_gp'),
-    ...     dependencies=['gp_wr_excess', 'ata', 'pct_gp']
-    ...)
+    ... )
     >>> spells.summon('DSK', columns=['deq_base', 'color', 'rarity'], filter_spec={'player_cohort': 'Top'}, extensions=[ext])
     ...     .filter(pl.col('deq_base').is_finite())
     ...     .filter(pl.col('rarity').is_in(['common', 'uncommon'])
@@ -181,8 +181,34 @@ Spells is not affiliated with 17Lands. Please review the [Usage Guidelines](http
     │ Oblivious Bookworm       ┆ 0.028605 ┆ uncommon ┆ GU    │
     └──────────────────────────┴──────────┴──────────┴───────┘
     ```
-    
-    Note the use of chained calls to the Polars DataFrame api to perform manipulations on the result of `summon`.
+  - `card_context` takes a name-indexed DataFrame or name-keyed dict and allows the construction of column definitions based on the results.
+    ```python
+    >>> deq = spells.summon('DSK', columns=['deq_base'], filter_spec={'player_cohort': 'Top'}, extensions=[ext])
+    >>> ext = [ 
+    ...     ColSpec(
+    ...         name='picked_deq_base',
+    ...         col_type=ColType.PICK_SUM,
+    ...         expr=lambda name, card_context: card_context[name]['deq_base']
+    ...     ),
+    ...     ColSpec(
+    ...         name='picked_deq_base_avg',
+    ...         col_type=ColType.AGG,
+    ...         expr=pl.col('picked_deq_base') / pl.col('num_taken')
+    ...     ),
+    ... ]
+    >>> spells.summon('DSK', columns=['picked_deq_base_avg'], group_by=['player_cohort'], extensions=ext, card_context=deq)
+    shape: (4, 2)
+    ┌───────────────┬─────────────────────┐
+    │ player_cohort ┆ picked_deq_base_avg │
+    │ ---           ┆ ---                 │
+    │ str           ┆ f64                 │
+    ╞═══════════════╪═════════════════════╡
+    │ Bottom        ┆ 0.004826            │
+    │ Middle        ┆ 0.00532             │
+    │ Other         ┆ 0.004895            │
+    │ Top           ┆ 0.005659            │
+    └───────────────┴─────────────────────┘
+    ```
     
 ## Installation
 
@@ -278,43 +304,40 @@ summon(
 
 #### parameters
 
-- columns: a list of string or `ColName` values to select as non-grouped columns. Valid `ColTypes` are `PICK_SUM`, `NAME_SUM`, `GAME_SUM`, `CARD_ATTR`, `CARD_SUM` and `AGG`. Min/Max/Unique 
+- columns: a list of string or `ColName` values to select as non-grouped columns. Valid `ColTypes` are `PICK_SUM`, `NAME_SUM`, `GAME_SUM`, `CARD_ATTR`, and `AGG`. Min/Max/Unique 
 aggregations of non-numeric (or numeric) data types are not supported. If `None`, use a set of columns modeled on the commonly used values on 17Lands.com/card_data.
 
 - group_by: a list of string or `ColName` values to display as grouped columns. Valid `ColTypes` are `GROUP_BY` and `CARD_ATTR`. By default, group by "name" (card name).
 
 - filter_spec: a dictionary specifying a filter, using a small number of paradigms. Columns used must be in each base view ("draft" and "game") that the `columns` and `group_by` columns depend on, so 
-`AGG`, `CARD_SUM` and `CARD_ATTR` columns are not valid. `NAME_SUM` columns are also not supported. Derived columns are supported. No filter is applied by default. Yes, I should rewrite it to use the mongo query language. The specification is best understood with examples:
+`AGG` and `CARD_ATTR` columns are not valid. Functions of card attributes in the base views can be filtered on, see the documentation for `expr` for details. `NAME_SUM` columns are also not supported. Derived columns are supported. No filter is applied by default. Yes, I should rewrite it to use the mongo query language. The specification is best understood with examples:
 
     - `{'player_cohort': 'Top'}` "player_cohort" value equals "Top".
     - `{'lhs': 'player_cohort', 'op': 'in', 'rhs': ['Top', 'Middle']}` "player_cohort" value is either "Top" or "Middle". Supported values for `op` are `<`, `<=`, `>`, `>=`, `!=`, `=`, `in` and `nin`.
     - `{'$and': [{'lhs': 'draft_date', 'op': '>', 'rhs': datetime.date(2024, 10, 7)}, {'rank': 'Mythic'}]}` Drafts after October 7 by Mythic-ranked players. Supported values for query construction keys are `$and`, `$or`, and `$not`.
 
-- extensions: a list of `spells.columns.ColumnSpec` objects, which are appended to the definitions built-in columns described below. A name not in the enum `ColName` can be used in this way if it is the name of a provided extension. Existing names can also be redefined using extensions.
+- extensions: a list of `spells.columns.ColSpec` objects, which are appended to the definitions built-in columns described below. A name not in the enum `ColName` can be used in this way if it is the name of a provided extension. Existing names can also be redefined using extensions.
 
 - read_cache/write_cache: Use the local file system to cache and retrieve aggregations to minimize expensive reads of the large datasets. You shouldn't need to touch these arguments unless you are debugging.
 
 ### Enums
 
 ```python
-from spells.enums import ColName, ColType, View
+from spells.enums import ColName, ColType
 ```
 
-Recommended to import `ColName` for any usage of `summon`, and to import `ColType` when defining custom extensions. You shouldn't need `VIEW`.
+Recommended to import `ColName` for any usage of `summon`, and to import `ColType` when defining custom extensions.
 
-### ColumnSpec
+### ColSpec
 
 ```python
-from spells.columns import ColumnSpec
+from spells.columns import ColSpec
 
-ColumnSpec(
+ColSpec(
     name: str,
     col_type: ColType,
-    expr: pl.Expr | None = None,
-    exprMap: Callable[[str], pl.Expr] | None = None
-    dependencies: list[str] | None = None
+    expr: pl.Expr | Callable[..., pl.Expr] | None = None,
     version: str | None = None
-    views: list[View] | None = None,
 )
 ```
 
@@ -324,19 +347,19 @@ Used to define extensions in `summon`
 
 - `name`: any string, including existing columns, although this is very likely to break dependent columns, so don't do it. For `NAME_SUM` columns, the name is the prefix without the underscore, e.g. "drawn".
 
-- `col_type`: one of the `ColType` enum values, `FILTER_ONLY`, `GROUP_BY`, `PICK_SUM`, `NAME_SUM`, `GAME_SUM`, `CARD_ATTR`, `CARD_SUM`, and `AGG`. See documentation for `summon` for usage. All columns except `CARD_ATTR`, `CARD_SUM` and `AGG` must be derivable at the individual row level on one or both base views. `CARD_ATTR` must be derivable at the individual row level from the card file. `AGG` can depend on any column present after summing over groups, and can include polars Expression aggregations. `CARD_SUM` columns are expressed similarly to `AGG`, but they are calculated before grouping by card name and are summed before the `AGG` selection stage (for example, to calculate average mana value. See example notebook "Card Attributes"). Arbitrarily long chains of aggregate dependencies are supported.
-
-- `expr`: A polars expression giving the derivation of the column value at the first level where it is defined. For `NAME_SUM` columns the `exprMap` attribute must be used instead. `AGG` columns that depend on `NAME_SUM` columns reference the prefix (`cdef.name`) only, since the unpivot has occured prior to selection.
+- `col_type`: one of the `ColType` enum values, `FILTER_ONLY`, `GROUP_BY`, `PICK_SUM`, `NAME_SUM`, `GAME_SUM`, `CARD_ATTR`, and `AGG`. See documentation for `summon` for usage. All columns except `CARD_ATTR`
+and `AGG` must be derivable at the individual row level on one or both base views. `CARD_ATTR` must be derivable at the individual row level from the card file. `AGG` can depend on any column present after 
+summing over groups, and can include polars Expression aggregations. Arbitrarily long chains of aggregate dependencies are supported.
 
-- `exprMap`: A function of card name that returns the expression for a `NAME_SUM` column. 
-
-- `dependencies`: A list of column names. All dependencies must be declared by name.
+- `expr`: A polars expression or function returning a polars expression giving the derivation of the column value at the first level where it is defined. 
+    - For `NAME_SUM` columns, `expr` must be a function of `name` which will result in a list of expressions mapped over all card names.
+    - `PICK_SUM` columns can also be functions on `name`, in which case the value will be a function of the value of the `PICK` field. 
+    - `AGG` columns that depend on `NAME_SUM` columns reference the prefix (`cdef.name`) only, since the unpivot has occured prior to selection. 
+    - The possible arguments to `expr`, in addition to `name` when appropriate, include the full `names` array as well as a dictionary called `card_context` which contains card dict objects with all `CARD_ATTR` values, including custom extensions. See example notebooks for more details.
 
 - `version`: When defining a column using a python function, as opposed to Polars expressions, add a unique version number so that the unique hashed signature of the column specification can be derived 
 for caching purposes, since Polars cannot generate a serialization natively. When changing the definition, be sure to increment the version value. Otherwise you do not need to use this parameter.
 
-- `views`: Not needed for custom columns.
-
 ### Columns
 
 A table of all included columns. Columns can be referenced by enum or by string value in arguments and filter specs. The string value is always the lowercase version of the enum attribute.
@@ -370,6 +393,7 @@ A table of all included columns. Columns can be referenced by enum or by string
 | `PICK_NUMBER`            | `"pick_number"`            | `DRAFT` | `FILTER_ONLY` | Dataset Column                               | Int      |
 | `PICK_NUM`               | `"pick_num"`               | `DRAFT` | `GROUP_BY`    | 1-indexed                                    | Int      |
 | `TAKEN_AT`               | `"taken_at`                | `DRAFT` | `PICK_SUM`    | Summable alias of `PICK_NUM`                 | Int      |
+| `NUM_DRAFTS`           | `"num_drafts"` | `DRAFT` | `PICK_SUM` | | Int |
 | `NUM_TAKEN`              | `"num_taken"`              | `DRAFT` | `PICK_SUM`    | Sum 1 over rows                              | Int      |
 | `PICK`                   | `"pick"`                   | `DRAFT` | `FILTER_ONLY` | Dataset Column, joined as "name"             | String   |
 | `PICK_MAINDECK_RATE`     | `"pick_maindeck_rate"`     | `DRAFT` | `PICK_SUM`    | Dataset Column                               | Float    |
@@ -424,7 +448,9 @@ A table of all included columns. Columns can be referenced by enum or by string
 | `CARD_TYPE` | `"card_type"` | `CARD` | `CARD_ATTR` | | String |
 | `SUBTYPE` | `"subtype"` | `CARD` | `CARD_ATTR` | | String |
 | `MANA_VALUE` | `"mana_value"` | `CARD` | `CARD_ATTR` | | Float |
-| `DECK_MANA_VALUE` | `"deck_mana_value"` | | `CARD_SUM` | `DECK` * `MANA_VALUE` | Float |
+| `DECK_MANA_VALUE` | `"deck_mana_value"` | | `NAME_SUM` | `DECK` * `MANA_VALUE` | Float |
+| `DECK_LANDS` | `"deck_lands"` | | `NAME_SUM` | Number of lands in deck | Float |
+| `DECK_SPELLS` | `"deck_spells"` | | `NAME_SUM` | Number of spells in deck | Float |
 | `MANA_COST` | `"mana_cost"` | `CARD` | `CARD_ATTR` | | String |
 | `POWER` | `"power"` | `CARD` | `CARD_ATTR` | | Float |
 | `TOUGHNESS` | `"toughness"` | `CARD` | `CARD_ATTR` | | Float |
@@ -463,7 +489,9 @@ A table of all included columns. Columns can be referenced by enum or by string
 | `GIH_WR_VAR` | `"gih_wr_var"` | | `AGG` | Game-weighted Variance | Float |
 | `GIH_WR_STDEV` | `"gh_wr_stdev"` | | `AGG` | Sqrt of `GIH_WR_VAR` | Float |
 | `GIH_WR_Z` | `"gih_wr_z"` | | `AGG` |`GIH_WR_EXCESS` / `GIH_WR_STDEV` | Float |
-| `DECK_MANA_VALUE_AVG` | `"deck_mana_value_avg"` | | `AGG` | `DECK_MANA_VALUE ` / `DECK` | Float |
+| `DECK_MANA_VALUE_AVG` | `"deck_mana_value_avg"` | | `AGG` | `DECK_MANA_VALUE ` / `DECK_SPELLS` | Float |
+| `DECK_LANDS_AVG` | `"deck_lands_avg"` | | `AGG` | `DECK_LANDS ` / `NUM_GAMES` | Float |
+| `DECK_SPELLS_AVG` | `"deck_spells_avg"` | | `AGG` | `DECK_SPELLS ` / `NUM_GAMES` | Float |
 
 # Roadmap to 1.0
 

spells_mtg-0.5.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+spells/__init__.py,sha256=EcI7ijXYvPA8jj7wUZqs6CSWr__MD8AOXhkex-Hj37E,131
+spells/cache.py,sha256=4v7h8D3TtaT0R_EdiRNhdcQrXzdH_CukezO6oAXvNEY,2956
+spells/cards.py,sha256=EOXAB_F2yedjf6KquCERCIHl0TSIJIoOe1jv8g4JzOc,3601
+spells/columns.py,sha256=VP4jr2aeNffPJM5q_yp232K_VCaYHo0rzf1b7xev4X0,18955
+spells/draft_data.py,sha256=S1TGlxQqQE9QD40znomV5UGbb5bTO0W_BZLYuRICeec,13394
+spells/enums.py,sha256=2IZrty0OtcbXq8oiuDWF75_AacMBBY_JLaisc_bNSdk,4765
+spells/external.py,sha256=qe6wOBDhPN4CZNQvYRq6G-OpIZcWTZzJjySgnf2Gu1o,10258
+spells/filter.py,sha256=J-YTOOAzOQpvIX29tviYL04RVoOUlfsbjBXoQBDCEdQ,3380
+spells/manifest.py,sha256=UNCZT3StN_1DfYfWNuEQrQx7ZI8Z5Y_l6j2oaUaWdYA,8142
+spells/schema.py,sha256=z8Qn2SiHG4T6YfPsz8xHLGMjU_Ofm76-Vrquh3b9B64,6422
+spells_mtg-0.5.0.dist-info/METADATA,sha256=eGWQZTH8640g5LIZhm9Gw5vAszPEq2E62_AveZU3OIQ,45492
+spells_mtg-0.5.0.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
+spells_mtg-0.5.0.dist-info/entry_points.txt,sha256=a9Y1omdl9MdnKuIj3aOodgrp-zZII6OCdvqwgP6BFvI,63
+spells_mtg-0.5.0.dist-info/licenses/LICENSE,sha256=tS54XYbJSgmq5zuHhbsQGbNQLJPVgXqhF5nu2CSRMig,1068
+spells_mtg-0.5.0.dist-info/RECORD,,

spells_mtg-0.3.1.dist-info/RECORD

@@ -1,15 +0,0 @@
-spells/__init__.py,sha256=QCPWQySUK2SZtCU-mSZLsn7vrNLJMDsRwil8gmAzmdk,151
-spells/cache.py,sha256=4v7h8D3TtaT0R_EdiRNhdcQrXzdH_CukezO6oAXvNEY,2956
-spells/cards.py,sha256=EOXAB_F2yedjf6KquCERCIHl0TSIJIoOe1jv8g4JzOc,3601
-spells/columns.py,sha256=QIM-dV00Pe5En9EozPWpH_u5f8VSgxd0Pxd2QxYuOFk,23423
-spells/draft_data.py,sha256=ABIQoUD8MKnc2goTUGY33dOxCpH8ydXXuQnbHMNULZs,10999
-spells/enums.py,sha256=_yvb9AFPofRYwf0gndFteGQS9bSzHy2_HphYYhFr9Ro,4761
-spells/external.py,sha256=qe6wOBDhPN4CZNQvYRq6G-OpIZcWTZzJjySgnf2Gu1o,10258
-spells/filter.py,sha256=J-YTOOAzOQpvIX29tviYL04RVoOUlfsbjBXoQBDCEdQ,3380
-spells/manifest.py,sha256=oGkWuBYquJYmtaIp2O-x5nFKD5TkU5lzS-vera69jyU,7244
-spells/schema.py,sha256=z8Qn2SiHG4T6YfPsz8xHLGMjU_Ofm76-Vrquh3b9B64,6422
-spells_mtg-0.3.1.dist-info/METADATA,sha256=3K1GrMa-GXcb3J-0Xg71Vqi93LxoynWwLQ8UmcjhVxM,43073
-spells_mtg-0.3.1.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
-spells_mtg-0.3.1.dist-info/entry_points.txt,sha256=a9Y1omdl9MdnKuIj3aOodgrp-zZII6OCdvqwgP6BFvI,63
-spells_mtg-0.3.1.dist-info/licenses/LICENSE,sha256=tS54XYbJSgmq5zuHhbsQGbNQLJPVgXqhF5nu2CSRMig,1068
-spells_mtg-0.3.1.dist-info/RECORD,,