code: def set_bipolar_reference(
      inst,
      anode,
      cathode,
      ch_name=None,
      ch_info=None,
      drop_refs=True,
      copy=True,
      on_bad="warn",
      verbose=None,
  ):
      """Re-reference selected channels using a bipolar referencing scheme.
  
      A bipolar reference takes the difference between two channels (the anode
      minus the cathode) and adds it as a new virtual channel. The original
      channels will be dropped by default.
  
      Multiple anodes and cathodes can be specified, in which case multiple
      virtual channels will be created. The 1st cathode will be subtracted
      from the 1st anode, the 2nd cathode from the 2nd anode, etc.
  
      By default, the virtual channels will be annotated with channel-info and
      -location of the anodes and coil types will be set to EEG_BIPOLAR.
  
      Parameters
      ----------
      inst : instance of Raw | Epochs | Evoked
          Data containing the unreferenced channels.
      anode : str | list of str
          The name(s) of the channel(s) to use as anode in the bipolar reference.
      cathode : str | list of str
          The name(s) of the channel(s) to use as cathode in the bipolar
          reference.
      ch_name : str | list of str | None
          The channel name(s) for the virtual channel(s) containing the resulting
          signal. By default, bipolar channels are named after the anode and
          cathode, but it is recommended to supply a more meaningful name.
      ch_info : dict | list of dict | None
          This parameter can be used to supply a dictionary (or a dictionary for
          each bipolar channel) containing channel information to merge in,
          overwriting the default values. Defaults to None.
      drop_refs : bool
          Whether to drop the anode/cathode channels from the instance.
      copy : bool
          Whether to operate on a copy of the data (True) or modify it in-place
          (False). Defaults to True.
      on_bad : str
          If a bipolar channel is created from a bad anode or a bad cathode, mne
          warns if on_bad="warns", raises ValueError if on_bad="raise", and does
          nothing if on_bad="ignore". For "warn" and "ignore", the new bipolar
          channel will be marked as bad. Defaults to on_bad="warns".
      %(verbose)s
  
      Returns
      -------
      inst : instance of Raw | Epochs | Evoked
          Data with the specified channels re-referenced.
  
      See Also
      --------
      set_eeg_reference : Convenience function for creating an EEG reference.
  
      Notes
      -----
      1. If the anodes contain any EEG channels, this function removes
         any pre-existing average reference projections.
  
      2. During source localization, the EEG signal should have an average
         reference.
  
      3. The data must be preloaded.
  
      .. versionadded:: 0.9.0
      """
      from ..epochs import BaseEpochs, EpochsArray
      from ..evoked import EvokedArray
      from ..io import BaseRaw, RawArray
      from .meas_info import create_info
  
      _check_can_reref(inst)
      if not isinstance(anode, list):
          anode = [anode]
  
      if not isinstance(cathode, list):
          cathode = [cathode]
  
      if len(anode) != len(cathode):
          raise ValueError(
              "Number of anodes (got %d) must equal the number "
              "of cathodes (got %d)." % (len(anode), len(cathode))
          )
  
      if ch_name is None:
          ch_name = [f"{a}-{c}" for (a, c) in zip(anode, cathode)]
      elif not isinstance(ch_name, list):
          ch_name = [ch_name]
      if len(ch_name) != len(anode):
          raise ValueError(
              "Number of channel names must equal the number of "
              "anodes/cathodes (got %d)." % len(ch_name)
          )
  
      # Check for duplicate channel names (it is allowed to give the name of the
      # anode or cathode channel, as they will be replaced).
      for ch, a, c in zip(ch_name, anode, cathode):
          if ch not in [a, c] and ch in inst.ch_names:
              raise ValueError(
                  'There is already a channel named "%s", please '
                  "specify a different name for the bipolar "
                  "channel using the ch_name parameter." % ch
              )
  
      if ch_info is None:
          ch_info = [{} for _ in anode]
      elif not isinstance(ch_info, list):
          ch_info = [ch_info]
      if len(ch_info) != len(anode):
          raise ValueError(
              "Number of channel info dictionaries must equal the "
              "number of anodes/cathodes."
          )
  
      if copy:
          inst = inst.copy()
  
      anode = _check_before_reference(
          inst, ref_from=cathode, ref_to=anode, ch_type="auto"
      )
  
      # Create bipolar reference channels by multiplying the data
      # (channels x time) with a matrix (n_virtual_channels x channels)
      # and add them to the instance.
      multiplier = np.zeros((len(anode), len(inst.ch_names)))
      for idx, (a, c) in enumerate(zip(anode, cathode)):
          multiplier[idx, inst.ch_names.index(a)] = 1
          multiplier[idx, inst.ch_names.index(c)] = -1
  
      ref_info = create_info(
          ch_names=ch_name,
          sfreq=inst.info["sfreq"],
          ch_types=inst.get_channel_types(picks=anode),
      )
  
      # Update "chs" in Reference-Info.
      for ch_idx, (an, info) in enumerate(zip(anode, ch_info)):
          _check_ch_keys(info, ch_idx, name="ch_info", check_min=False)
          an_idx = inst.ch_names.index(an)
          # Copy everything from anode (except ch_name).
          an_chs = {
              k: v
              for k, v in inst.info["chs"][an_idx].items()
              if k != "ch_name"
          }
          ref_info["chs"][ch_idx].update(an_chs)
          # Set coil-type to bipolar.
          ref_info["chs"][ch_idx][
              "coil_type"
          ] = FIFF.FIFFV_COIL_EEG_BIPOLAR
          # Update with info from ch_info-parameter.
          ref_info["chs"][ch_idx].update(info)
  
      # Set other info-keys from original instance.
      pick_info = {
          k: v
          for k, v in inst.info.items()
          if k not in ["chs", "ch_names", "bads", "nchan", "sfreq"]
      }
  
      with ref_info._unlock():
          ref_info.update(pick_info)
  
      # Rereferencing of data.
      ref_data = multiplier @ inst._data
  
      if isinstance(inst, BaseRaw):
          ref_inst = RawArray(
              ref_data, ref_info, first_samp=inst.first_samp, copy=None
          )
      elif isinstance(inst, BaseEpochs):
          ref_inst = EpochsArray(
              ref_data,
              ref_info,
              events=inst.events,
              tmin=inst.tmin,
              event_id=inst.event_id,
              metadata=inst.metadata,
          )
      else:
          ref_inst = EvokedArray(
              ref_data,
              ref_info,
              tmin=inst.tmin,
              comment=inst.comment,
              nave=inst.nave,
              kind="average",
          )
  
      # Add referenced instance to original instance.
      inst.add_channels([ref_inst], force_update_info=True)
  
      # Handle bad channels.
      bad_bipolar_chs = []
      for ch_idx, (a, c) in enumerate(zip(anode, cathode)):
          if a in inst.info["bads"] or c in inst.info["bads"]:
              bad_bipolar_chs.append(ch_name[ch_idx])
  
      # Add warnings if bad channels are present.
      if bad_bipolar_chs:
          msg = f"Bipolar channels are based on bad channels: {bad_bipolar_chs}."
          _on_missing(on_bad, msg)
          inst.info["bads"] += bad_bipolar_chs
  
      added_channels = ", ".join([name for name in ch_name])
      logger.info(
          f"Added the following bipolar channels:\n{added_channels}"
      )
  
      for attr_name in ["picks", "_projector"]:
          setattr(inst, attr_name, None)
  
      # Drop remaining channels.
      if drop_refs:
          drop_channels = list(
              (set(anode) | set(cathode)) & set(inst.ch_names)
          )
          inst.drop_channels(drop_channels)
  
      return inst
  
file_path: mne-python/mne/_fiff/reference.py
imports: import numpy
  from ..defaults import DEFAULTS
  from ..fixes import pinv
  from ..utils import _check_option, _check_preload, _on_missing, _validate_type, fill_doc, logger, verbose, warn
  from .constants import FIFF
  from .meas_info import _check_ch_keys
  from .pick import _ELECTRODE_CH_TYPES, pick_channels, pick_channels_forward, pick_types
  from .proj import _has_eeg_average_ref_proj, make_eeg_average_ref_proj, setup_proj
label_desc: Use image node_id 8 for calling a global function with example usage: set_bipolar_reference(inst, anode, cathode, ch_name, ch_info, drop_refs, copy, on_bad, verbose) and returns: inst