# StateMonitor class

(Shortest import: `from brian2 import StateMonitor)`

class brian2.monitors.statemonitor.StateMonitor(*args, **kw)

  Bases: `Group`, `CodeRunner`

  Record values of state variables during a run

  To extract recorded values after a run, use the `t` attribute for the array of times at which values were recorded, and variable name attribute for the values. The values will have shape `(len(indices), len(t))`, where `indices` are the array indices which were recorded. When indexing the `StateMonitor` directly, the returned object can be used to get the recorded values for the specified indices, i.e. the indexing semantic refers to the indices in `source`, not to the relative indices of the recorded values. For example, when recording only neurons with even numbers, `mon[[0, 2]].v` will return the values for neurons 0 and 2, whereas `mon.v[[0, 2]]` will return the values for the first and third recorded neurons, i.e. for neurons 0 and 4.

  Parameters:

    source : `Group`

    > Which object to record values from.

    variables : str, sequence of str, True

    > Which variables to record, or `True` to record all variables (note that this may use a great deal of memory).

    record : bool, sequence of ints

    > Which indices to record, nothing is recorded for `False`, everything is recorded for `True` (warning: may use a great deal of memory), or a specified subset of indices.

    dt : `Quantity`, optional

    > The time step to be used for the monitor. Cannot be combined with the `clock` argument.

    clock : `Clock`, optional

    > The update clock to be used. If neither a clock, nor the `dt` argument is specified, the clock of the `source` will be used.

    when : str, optional

    > At which point during a time step the values should be recorded. Defaults to `'start'`. See Scheduling for possible values.

    order : int, optional

    > The priority of of this group for operations occurring at the same time step and in the same scheduling slot. Defaults to 0.

    name : str, optional

    > A unique name for the object, otherwise will use `source.name+'statemonitor_0'`, etc.

    codeobj_class : `CodeObject`, optional

    > The `CodeObject` class to create.

  Notes

  Since this monitor by default records in the `'start'` time slot, recordings of the membrane potential in integrate-and-fire models may look unexpected: the recorded membrane potential trace will never be above threshold in an integrate-and-fire model, because the reset statement will have been applied already. Set the `when` keyword to a different value if this is not what you want.

  Note that `record=True` only works in runtime mode for synaptic variables. This is because the actual array of indices has to be calculated and this is not possible in standalone mode, where the synapses have not been created yet at this stage. Consider using an explicit array of indices instead, i.e. something like `record=np.arange(n_synapses)`.

  Examples

  Record all variables, first 5 indices:

      eqs = '''
      dV/dt = (2-V)/(10*ms) : 1
      '''
      threshold = 'V>1'
      reset = 'V = 0'
      G = NeuronGroup(100, eqs, threshold=threshold, reset=reset)
      G.V = rand(len(G))
      M = StateMonitor(G, True, record=range(5))
      run(100*ms)
      plot(M.t, M.V.T)
      show()

  Attributes

  `record` | The array of recorded indices
  `record_variables` | The variables to record

  Methods

  `record_single_timestep`() | Records a single time step.
  `reinit`() |
  `resize`(new_size) |

  Details

  record

    The array of recorded indices

  record_variables

    The variables to record

  record_single_timestep()

    Records a single time step. Useful for recording the values at the end of the simulation – otherwise a `StateMonitor` will not record the last simulated values since its `when` attribute defaults to `'start'`, i.e. the last recording is at the beginning of the last time step.

    Notes

    This function will only work if the `StateMonitor` has been already run, but a run with a length of `0*ms` does suffice.

    Examples

        >>> from brian2 import *
        >>> G = NeuronGroup(1, 'dv/dt = -v/(5*ms) : 1')
        >>> G.v = 1
        >>> mon = StateMonitor(G, 'v', record=True)
        >>> run(0.5*ms)
        >>> print(np.array_str(mon.v[:], precision=3))
        [[ 1.     0.98   0.961  0.942  0.923]]
        >>> print(mon.t[:])
        [   0.  100.  200.  300.  400.] us
        >>> print(np.array_str(G.v[:], precision=3))  # last value had not been recorded
        [ 0.905]
        >>> mon.record_single_timestep()
        >>> print(mon.t[:])
        [   0.  100.  200.  300.  400.  500.] us
        >>> print(np.array_str(mon.v[:], precision=3))
        [[ 1.     0.98   0.961  0.942  0.923  0.905]]

  reinit()
  resize(new_size)

## Tutorials and examples using this

- Tutorial 1-intro-to-brian-neurons

- Tutorial 2-intro-to-brian-synapses

- Tutorial 3-intro-to-brian-simulations

- Example COBAHH

- Example adaptive_threshold

- Example advanced/COBAHH_approximated

- Example advanced/Ornstein_Uhlenbeck

- Example advanced/compare_GSL_to_conventional

- Example advanced/custom_events

- Example advanced/modelfitting_sbi

- Example advanced/stochastic_odes

- Example compartmental/bipolar_cell

- Example compartmental/bipolar_with_inputs

- Example compartmental/bipolar_with_inputs2

- Example compartmental/hh_with_spikes

- Example compartmental/hodgkin_huxley_1952

- Example compartmental/infinite_cable

- Example compartmental/lfp

- Example compartmental/spike_initiation

- Example coupled_oscillators

- Example frompapers/Brette_2012/Fig1

- Example frompapers/Brette_2012/Fig3AB

- Example frompapers/Brette_2012/Fig3CF

- Example frompapers/Brette_2012/Fig4

- Example frompapers/Brette_2012/Fig5A

- Example frompapers/Brette_Gerstner_2005

- Example frompapers/Brette_Guigon_2003

- Example frompapers/Clopath_et_al_2010_homeostasis

- Example frompapers/Destexhe_et_al_1998

- Example frompapers/Hindmarsh_Rose_1984

- Example frompapers/Izhikevich_2003

- Example frompapers/Izhikevich_2007

- Example frompapers/Jansen_Rit_1995_single_column

- Example frompapers/Morris_Lecar_1981

- Example frompapers/Naud_et_al_2008_adex_firing_patterns

- Example frompapers/Nicola_Clopath_2017

- Example frompapers/Platkiewicz_Brette_2011

- Example frompapers/Rossant_et_al_2011bis

- Example frompapers/Rothman_Manis_2003

- Example frompapers/Stimberg_et_al_2018/example_1_COBA

- Example frompapers/Stimberg_et_al_2018/example_2_gchi_astrocyte

- Example frompapers/Stimberg_et_al_2018/example_3_io_synapse

- Example frompapers/Stimberg_et_al_2018/example_4_rsmean

- Example frompapers/Stimberg_et_al_2018/example_4_synrel

- Example frompapers/Stimberg_et_al_2018/example_5_astro_ring

- Example frompapers/Tetzlaff_2015

- Example frompapers/Touboul_Brette_2008

- Example frompapers/Tsodyks_Pawelzik_Markram_1998

- Example frompapers/Tsodyks_Uziel_Markram_2000

- Example frompapers/Wang_2002

- Example frompapers/Wang_Buszaki_1996

- Example multiprocessing/01_using_cython

- Example multiprocessing/02_using_standalone

- Example multiprocessing/03_standalone_joblib

- Example phase_locking

- Example standalone/STDP_standalone

- Example standalone/simple_case

- Example standalone/simple_case_build

- Example synapses/STDP

- Example synapses/continuous_interaction

- Example synapses/gapjunctions

- Example synapses/homeostatic_stdp_at_inhibitory_synapes

- Example synapses/jeffress

- Example synapses/nonlinear

- Example synapses/spike_based_homeostasis

- Example synapses/synapses