Deprecate CmdStanMCMC.metric, provide .inv_metric instead

Author: WardBrian

cmdstanpy/stanfit/mcmc.py

@@ -233,19 +233,27 @@ def metric_type(self) -> Optional[str]:
             else None
         )
 
+    # TODO(2.0): remove
     @property
     def metric(self) -> Optional[np.ndarray]:
+        """Deprecated. Use ``.inv_metric`` instead."""
+        get_logger().warning(
+            'The "metric" property is deprecated, use "inv_metric" instead. '
+            'This will be the same quantity, but with a more accurate name.'
+        )
+        return self.inv_metric
+
+    @property
+    def inv_metric(self) -> Optional[np.ndarray]:
         """
-        Metric used by sampler for each chain.
-        When sampler algorithm 'fixed_param' is specified, metric is None.
+        Inverse mass matrix used by sampler for each chain.
+        Returns a ``nchains x nparams`` array when metric_type is 'diag_e',
+        a ``nchains x nparams x nparams`` array when metric_type is 'dense_e',
+        or ``None`` when metric_type is 'unit_e' or algorithm is 'fixed_param'.
         """
-        if self._is_fixed_param:
-            return None
-        if self._metadata.cmdstan_config['metric'] == 'unit_e':
-            get_logger().info(
-                'Unit diagnonal metric, inverse mass matrix size unknown.'
-            )
+        if self._is_fixed_param or self.metric_type == 'unit_e':
             return None
+
         self._assemble_draws()
         return self._metric
 

cmdstanpy_tutorial.ipynb

@@ -352,7 +352,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fit.metric_type,  fit.metric"
+    "fit.metric_type,  fit.inv_metric"
    ]
   },
   {

cmdstanpy_tutorial.py

@@ -37,7 +37,7 @@
 
 print(fit.step_size)
 print(fit.metric_type)
-print(fit.metric)
+print(fit.inv_metric)
 
 # #### Summarize the results
 

docsrc/users-guide/examples/MCMC Sampling.ipynb

@@ -1483,7 +1483,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 25,
+   "execution_count": null,
    "metadata": {},
    "outputs": [
     {
@@ -1502,7 +1502,7 @@
     }
    ],
    "source": [
-    "print(f'adapted step_size per chain\\n{fit.step_size}\\nmetric_type: {fit.metric_type}\\nmetric:\\n{fit.metric}')"
+    "print(f'adapted step_size per chain\\n{fit.step_size}\\nmetric_type: {fit.metric_type}\\ninverse metric:\\n{fit.inv_metric}')"
    ]
   },
   {

docsrc/users-guide/hello_world.rst

@@ -171,7 +171,7 @@ access to the the per-chain HMC tuning parameters from the NUTS-HMC adaptive sam
 .. ipython:: python
 
     print(fit.metric_type)
-    print(fit.metric)
+    print(fit.inv_metric)
     print(fit.step_size)
 
 

test/test_sample.py

@@ -89,7 +89,7 @@ def test_bernoulli_good(stanfile: str):
     assert bern_fit.draws().shape == (100, 2, len(BERNOULLI_COLS))
     assert bern_fit.metric_type == 'diag_e'
     assert bern_fit.step_size.shape == (2,)
-    assert bern_fit.metric.shape == (2, 1)
+    assert bern_fit.inv_metric.shape == (2, 1)
 
     assert bern_fit.draws(concat_chains=True).shape == (
         200,
@@ -125,7 +125,7 @@ def test_bernoulli_good(stanfile: str):
     assert bern_sample.shape == (100, 2, len(BERNOULLI_COLS))
     assert bern_fit.metric_type == 'dense_e'
     assert bern_fit.step_size.shape == (2,)
-    assert bern_fit.metric.shape == (2, 1, 1)
+    assert bern_fit.inv_metric.shape == (2, 1, 1)
 
     bern_fit = bern_model.sample(
         data=jdata,
@@ -186,9 +186,7 @@ def test_bernoulli_good(stanfile: str):
 
 
 @pytest.mark.parametrize("stanfile", ["bernoulli.stan"])
-def test_bernoulli_unit_e(
-    stanfile: str, caplog: pytest.LogCaptureFixture
-) -> None:
+def test_bernoulli_unit_e(stanfile: str) -> None:
     stan = os.path.join(DATAFILES_PATH, stanfile)
     bern_model = CmdStanModel(stan_file=stan)
 
@@ -204,19 +202,9 @@ def test_bernoulli_unit_e(
         show_progress=False,
     )
     assert bern_fit.metric_type == 'unit_e'
-    assert bern_fit.metric is None
+    assert bern_fit.inv_metric is None
     assert bern_fit.step_size.shape == (2,)
-    with caplog.at_level(logging.INFO):
-        logging.getLogger()
-        assert bern_fit.metric is None
-    check_present(
-        caplog,
-        (
-            'cmdstanpy',
-            'INFO',
-            'Unit diagnonal metric, inverse mass matrix size unknown.',
-        ),
-    )
+
     assert bern_fit.draws().shape == (100, 2, len(BERNOULLI_COLS))
 
 
@@ -535,7 +523,7 @@ def test_fixed_param_good() -> None:
     )
     assert datagen_fit.runset._args.method == Method.SAMPLE
     assert datagen_fit.metric_type is None
-    assert datagen_fit.metric is None
+    assert datagen_fit.inv_metric is None
     assert datagen_fit.step_size is None
     assert datagen_fit.divergences is None
     assert datagen_fit.max_treedepths is None
@@ -638,7 +626,7 @@ def test_fixed_param_good() -> None:
     assert datagen_fit.column_names == tuple(column_names)
     assert datagen_fit.num_draws_sampling == 100
     assert datagen_fit.draws().shape == (100, 1, len(column_names))
-    assert datagen_fit.metric is None
+    assert datagen_fit.inv_metric is None
     assert datagen_fit.metric_type is None
     assert datagen_fit.step_size is None
 
@@ -860,7 +848,7 @@ def test_validate_big_run() -> None:
     assert fit.column_names == tuple(column_names)
     assert fit.metric_type == 'diag_e'
     assert fit.step_size.shape == (2,)
-    assert fit.metric.shape == (2, 2095)
+    assert fit.inv_metric.shape == (2, 2095)
     assert fit.draws().shape == (1000, 2, 2102)
     assert fit.draws_pd(vars=['phi']).shape == (2000, 2095)
     with raises_nested(ValueError, r'Unknown variable: gamma'):
@@ -2136,8 +2124,8 @@ def test_sample_dense_mass_matrix():
     linear_model = CmdStanModel(stan_file=stan)
 
     fit = linear_model.sample(data=jdata, metric="dense_e", chains=2)
-    assert fit.metric is not None
-    assert fit.metric.shape == (2, 3, 3)
+    assert fit.inv_metric is not None
+    assert fit.inv_metric.shape == (2, 3, 3)
 
 
 def test_no_output_draws():