Repository: starsimhub/starsim (language: python)

Issue:
Consider absolute default
I find myself wishing that `ss.Sim().run().plot()` would actually produce something, for super quick testing. I think `diseases='sir', networks='random'` would be a reasonable default setting, to be overwritten if the user supplied something.


Discussion / hints:
I have mixed feelings about what sensible defaults would be, considering the vast space of usages. In Atomica we've gotten a lot of mileage out of `at.demo()` as a way to construct valid demo projects, that has the advantage of being able to very quickly produce different demos e.g., if you wanted a simple demo for super quick testing, but for HIV rather than SIR
I don't mind `ss.demo()`, but I also don't see a downside of having `'sir'` and `'random'` as the defaults, since there are almost no use cases (that I can think of) where you'd actively want `None` instead, and of course if you supply something then the defaults will be overwritten
Can't say I feel super strongly about it, but in reducing surprise factor, I'd kind of expect that if I make a `Sim` and don't give it any diseases, then there won't be any diseases in the `Sim`. If there isn't an obvious choice for a default value, then it can be confusing for users to know when and what things are going to appear by default. That said - it's very context dependent, probably more qualitative than anything about whether a default is 'obvious' or not.

Regardless, `ss.demo()` would be great to have to provide shortcuts for other common models shipped with the code 👍 
I like the idea of a ss.demo() for simplicity of running a demo. Do we want to have a default disease (or shifting randomly selected disease) that can run with Sim.run() or does that go against the spirit and design goal of *sim/Starsim?

Fix patch:
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 5b8b663b..ca143c9f 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -9,6 +9,12 @@ All notable changes to the codebase are documented in this file. Changes that ma
    :depth: 1
 
 
+Version 0.2.8 (2024-03-13)
+--------------------------
+- Add ``ss.demo()`` to quickly create a default simulation.
+- *GitHub info*: PR `380 <https://github.com/amath-idm/stisim/pull/380>`_
+
+
 Version 0.2.7 (2024-03-09)
 --------------------------
 - Update ``StaticNet`` with defaults and correct argument passing
diff --git a/starsim/sim.py b/starsim/sim.py
index 0b4fbdd1..eb85d3a9 100644
--- a/starsim/sim.py
+++ b/starsim/sim.py
@@ -10,7 +10,7 @@
 import numba as nb
 
 
-__all__ = ['Sim', 'AlreadyRunError', 'diff_sims']
+__all__ = ['Sim', 'AlreadyRunError', 'demo', 'diff_sims']
 
 
 @nb.njit(cache=True)
@@ -651,7 +651,7 @@ def get_result(res, func):
             summary[key] = entry
         self.summary = summary
         return summary
-
+    
     def shrink(self, skip_attrs=None, in_place=True):
         """
         "Shrinks" the simulation by removing the people and other memory-intensive
@@ -961,6 +961,36 @@ class AlreadyRunError(RuntimeError):
     pass
 
 
+def demo(run=True, plot=True, summary=True, **kwargs):
+    """
+    Create a simple demo simulation for Starsim
+    
+    Defaults to using the SIR model with a random network, but these can be configured.
+    
+    Args:
+        run (bool): whether to run the sim
+        plot (bool): whether to plot the results
+        summary (bool): whether to print a summary of the results
+        kwargs (dict): passed to ``ss.Sim()``
+    
+    **Examples**::
+        
+        ss.demo() # Run, plot, and show results
+        ss.demo(diseases='hiv', networks='mf') # Run with different defaults
+    """
+    kw = sc.mergedicts(dict(pars=dict(diseases='sir', networks='random')), kwargs)
+    sim = Sim(**kw)
+    if run:
+        sc.heading('Running demo:')
+        sim.run()
+    if summary:
+        sc.heading('Results:')
+        print(sim.summary)
+    if plot:
+        sim.plot()
+    return sim
+
+
 def diff_sims(sim1, sim2, skip_key_diffs=False, skip=None, full=False, output=False, die=False):
     '''
     Compute the difference of the summaries of two simulations, and print any
diff --git a/starsim/version.py b/starsim/version.py
index 223b6049..297eb325 100644
--- a/starsim/version.py
+++ b/starsim/version.py
@@ -4,6 +4,6 @@
 
 __all__ = ['__version__', '__versiondate__', '__license__']
 
-__version__ = '0.2.7'
-__versiondate__ = '2024-03-09'
+__version__ = '0.2.8'
+__versiondate__ = '2024-03-13'
 __license__ = f'Starsim {__version__} ({__versiondate__}) — © 2023-2024 by IDM'


Test patch:
diff --git a/tests/test_simple.py b/tests/test_simple.py
index 1f5be007..34e6104f 100644
--- a/tests/test_simple.py
+++ b/tests/test_simple.py
@@ -13,6 +13,12 @@
 sc.options(interactive=False) # Assume not running interactively
 
 
+def test_demo():
+    """ Test Starsim's demo run """
+    sim = ss.demo()
+    return sim
+
+
 def test_default():
     """ Create, run, and plot a sim with default settings """
     sim = ss.Sim(n_agents=n_agents).run()
@@ -146,6 +152,7 @@ def test_parallel():
     sc.options(interactive=do_plot)
     T = sc.timer()
     
+    s0 = test_demo()
     s1 = test_default()
     s2 = test_simple()
     s3a, s3b = test_sir_epi()