docs: def root2array(filenames,
                 treename=None,
                 branches=None,
                 selection=None,
                 object_selection=None,
                 start=None,
                 stop=None,
                 step=None,
                 include_weight=False,
                 weight_name='weight',
                 cache_size=-1,
                 warn_missing_tree=False):
      """Convert trees in ROOT files into a numpy structured array.
  
      Refer to the documentation of :func:`tree2array`.
  
      Parameters
      ----------
      filenames : str or list
          ROOT file name pattern or list of patterns. Wildcarding is supported by
          Python globbing.
      treename : str, optional (default=None)
          Name of the tree to convert (optional if each file contains exactly one
          tree).
      branches : list of strings and tuples or a string or tuple, optional (default=None)
          List of branches and expressions to include as columns of the array or
          a single branch or expression in which case a nonstructured array is
          returned. If None then include all branches that can be converted.
          Branches or expressions that result in variable-length subarrays can be
          truncated at a fixed length by using the tuple ``(branch_or_expression,
          fill_value, length)`` or converted into a single value with
          ``(branch_or_expression, fill_value)`` where ``length==1`` is implied.
          ``fill_value`` is used when the original array is shorter than
          ``length``. This truncation is after any object selection performed
          with the ``object_selection`` argument.
      selection : str, optional (default=None)
          Only include entries fulfilling this condition. If the condition
          evaluates to multiple values per tree entry (e.g. conditions on array
          branches) then an entry will be included if the condition evaluates to
          true for at least one array element.
      object_selection : dict, optional (default=None)
          A dictionary mapping selection strings to branch names or lists of
          branch names. Only array elements passing the selection strings will be
          included in the output array per entry in the tree. The branches
          specified must be variable-length array-type branches and the length of
          the selection and branches it acts on must match for each tree entry.
          For example ``object_selection={'a > 0': ['a', 'b']}`` will include all
          elements of 'a' and corresponding elements of 'b' where 'a > 0' for
          each tree entry. 'a' and 'b' must have the same length in every tree
          entry.
      start, stop, step: int, optional (default=None)
          The meaning of the ``start``, ``stop`` and ``step`` parameters is the
          same as for Python slices. If a range is supplied (by setting some of
          the ``start``, ``stop`` or ``step`` parameters), only the entries in
          that range and fulfilling the ``selection`` condition (if defined) are
          used.
      include_weight : bool, optional (default=False)
          Include a column containing the tree weight ``TTree::GetWeight()``.
          Note that this will be the same value for all entries unless the tree
          is actually a TChain containing multiple trees with different weights.
      weight_name : str, optional (default='weight')
          The field name for the weight column if ``include_weight=True``.
      cache_size : int, optional (default=-1)
          Set the size (in bytes) of the TTreeCache used while reading a TTree. A
          value of -1 uses ROOT's default cache size. A value of 0 disables the
          cache.
      warn_missing_tree : bool, optional (default=False)
          If True, then warn when a tree is missing from an input file instead of
          raising an IOError.
  
      Notes
      -----
      * Refer to the :ref:`type conversion table <conversion_table>`.
  
      See Also
      --------
      tree2array
      array2tree
      array2root
  
      """
      filenames = _glob(filenames)
  
      if not filenames:
          raise ValueError("specify at least one filename")
  
      if treename is None:
          trees = list_trees(filenames[0])
          if len(trees) > 1:
              raise ValueError(
                  "treename must be specified if the file "
                  "contains more than one tree")
          elif not trees:
              raise IOError(
                  "no trees present in {0}".format(filenames[0]))
          treename = trees[0]
  
      if isinstance(branches, string_types):
          # single branch selected
          flatten = branches
          branches = [branches]
      elif isinstance(branches, tuple):
          if len(branches) not in (2, 3):
              raise ValueError(
                  "invalid branch tuple: {0}. "
                  "A branch tuple must contain two elements "
                  "(branch_name, fill_value) or three elements "
                  "(branch_name, fill_value, length) "
                  "to yield a single value or truncate, respectively".format(branches))
          flatten = branches[0]
          branches = [branches]
      else:
          flatten = False
  
      arr = _librootnumpy.root2array_fromfile(
          filenames, treename, branches,
          selection, object_selection,
          start, stop, step,
          include_weight,
          weight_name,
          cache_size,
          warn_missing_tree)
  
      if flatten:
          # select single column
          return arr[flatten]
      return arr