code: def find_events(
      raw,
      stim_channel=None,
      output="onset",
      consecutive="increasing",
      min_duration=0,
      shortest_event=2,
      mask=None,
      uint_cast=False,
      mask_type="and",
      initial_event=False,
      verbose=None,
  ):
      """Find :term:`events` from raw file.
  
      See :ref:`tut-events-vs-annotations` and :ref:`tut-event-arrays`
      for more information about events.
  
      Parameters
      ----------
      raw : Raw object
          The raw data.
      stim_channel : None | str | list of str
          Name of the stim channel or all the stim channels
          affected by triggers. If None, the config variables
          'MNE_STIM_CHANNEL', 'MNE_STIM_CHANNEL_1', 'MNE_STIM_CHANNEL_2',
          etc. are read. If these are not found, it will fall back to
          'STI 014' if present, then fall back to the first channel of type
          'stim', if present. If multiple channels are provided
          then the returned events are the union of all the events
          extracted from individual stim channels.
      output : 'onset' | 'offset' | 'step'
          Whether to report when events start, when events end, or both.
      consecutive : bool | 'increasing'
          If True, consider instances where the value of the events
          channel changes without first returning to zero as multiple
          events. If False, report only instances where the value of the
          events channel changes from/to zero. If 'increasing', report
          adjacent events only when the second event code is greater than
          the first.
      min_duration : float
          The minimum duration of a change in the events channel required
          to consider it as an event (in seconds).
      shortest_event : int
          Minimum number of samples an event must last (default is 2). If the
          duration is less than this an exception will be raised.
      mask : int | None
          The value of the digital mask to apply to the stim channel values.
          If None (default), no masking is performed.
      uint_cast : bool
          If True (default False), do a cast to ``uint16`` on the channel
          data. This can be used to fix a bug with STI101 and STI014 in
          Neuromag acquisition setups that use channel STI016 (channel 16
          turns data into e.g. -32768), similar to ``mne_fix_stim14 --32``
          in MNE-C.
  
          .. versionadded:: 0.12
      mask_type : 'and' | 'not_and'
          The type of operation between the mask and the trigger.
          Choose 'and' (default) for MNE-C masking behavior.
  
          .. versionadded:: 0.13
      initial_event : bool
          If True (default False), an event is created if the stim channel has a
          value different from 0 as its first sample. This is useful if an event
          at t=0s is present.
  
          .. versionadded:: 0.16
      %(verbose)s
  
      Returns
      -------
      %(events)s
  
      See Also
      --------
      find_stim_steps : Find all the steps in the stim channel.
      read_events : Read events from disk.
      write_events : Write events to disk.
  
      Notes
      -----
      .. warning:: If you are working with downsampled data, events computed
                   before decimation are no longer valid. Please recompute
                   your events after decimation, but note this reduces the
                   precision of event timing.
  
      Examples
      --------
      Consider data with a stim channel that looks like::
  
          [0, 32, 32, 33, 32, 0]
  
      By default, find_events returns all samples at which the value of the
      stim channel increases::
  
          >>> print(find_events(raw)) # doctest: +SKIP
          [[ 1  0 32]
           [ 3 32 33]]
  
      If consecutive is False, find_events only returns the samples at which
      the stim channel changes from zero to a non-zero value::
  
          >>> print(find_events(raw, consecutive=False)) # doctest: +SKIP
          [[ 1  0 32]]
  
      If consecutive is True, find_events returns samples at which the
      event changes, regardless of whether it first returns to zero::
  
          >>> print(find_events(raw, consecutive=True)) # doctest: +SKIP
          [[ 1  0 32]
           [ 3 32 33]
           [ 4 33 32]]
  
      If output is 'offset', find_events returns the last sample of each event
      instead of the first one::
  
          >>> print(find_events(raw, consecutive=True, # doctest: +SKIP
          ...                   output='offset'))
          [[ 2 33 32]
           [ 3 32 33]
           [ 4  0 32]]
  
      If output is 'step', find_events returns the samples at which an event
      starts or ends::
  
          >>> print(find_events(raw, consecutive=True, # doctest: +SKIP
          ...                   output='step'))
          [[ 1  0 32]
           [ 3 32 33]
           [ 4 33 32]
           [ 5 32  0]]
  
      To ignore spurious events, it is also possible to specify a minimum
      event duration. Assuming our events channel has a sample rate of
      1000 Hz::
  
          >>> print(find_events(raw, consecutive=True, # doctest: +SKIP
          ...                   min_duration=0.002))
          [[ 1  0 32]]
  
      For the digital mask, if mask_type is set to 'and' it will take the
      binary representation of the digital mask, e.g. 5 -> '00000101', and will
      allow the values to pass where mask is one, e.g.::
  
                7 '0000111' <- trigger value
               37 '0100101' <- mask
           ----------------
                5 '0000101'
  
      For the digital mask, if mask_type is set to 'not_and' it will take the
      binary representation of the digital mask, e.g. 5 -> '00000101', and will
      block the values where mask is one, e.g.::
  
                7 '0000111' <- trigger value
               37 '0100101' <- mask
           ----------------
                2 '0000010'
      """
      min_samples = min_duration * raw.info["sfreq"]
  
      # pull stim channel from config if necessary
      try:
          stim_channel = _get_stim_channel(stim_channel, raw.info)
      except ValueError:
          if len(raw.annotations) > 0:
              raise ValueError(
                  "No stim channels found, but the raw object has "
                  "annotations. Consider using "
                  "mne.events_from_annotations to convert these to "
                  "events."
              )
          else:
              raise
  
      picks = pick_channels(raw.info["ch_names"], include=stim_channel)
      if len(picks) == 0:
          raise ValueError(
              "No stim channel found to extract event triggers."
          )
      data, _ = raw[picks, :]
  
      events_list = []
      for d, ch_name in zip(data, stim_channel):
          events = _find_events(
              d[np.newaxis, :],
              raw.first_samp,
              verbose=verbose,
              output=output,
              consecutive=consecutive,
              min_samples=min_samples,
              mask=mask,
              uint_cast=uint_cast,
              mask_type=mask_type,
              initial_event=initial_event,
              ch_name=ch_name,
          )
          # add safety check for spurious events (for ex. from neuromag syst.) by
          # checking the number of low sample events
          n_short_events = np.sum(
              np.diff(events[:, 0]) < shortest_event
          )
          if n_short_events > 0:
              raise ValueError(
                  "You have %i events shorter than the "
                  "shortest_event. These are very unusual and you "
                  "may want to set min_duration to a larger value "
                  "e.g. x / raw.info['sfreq']. Where x = 1 sample "
                  "shorter than the shortest event "
                  "length." % (n_short_events)
              )
  
          events_list.append(events)
  
      events = np.concatenate(events_list, axis=0)
      events = _find_unique_events(events)
      events = events[np.argsort(events[:, 0])]
      return events
  
imports: from collections.abc import Sequence
  from pathlib import Path
  import numpy
  from ._fiff.constants import FIFF
  from ._fiff.open import fiff_open
  from ._fiff.pick import pick_channels
  from ._fiff.tag import read_tag
  from ._fiff.tree import dir_tree_find
  from ._fiff.write import end_block, start_and_end_file, start_block, write_int
  from .utils import _check_fname, _check_integer_or_list, _check_on_missing, _check_option, _get_stim_channel, _on_missing, _pl, _validate_type, check_fname, fill_doc, logger, verbose, warn
label_desc: Use image node_id 10 for calling a global function with example usage: find_events(raw, stim_channel, output, consecutive, min_duration, shortest_event, mask, uint_cast, mask_type, initial_event, verbose) and returns: events