ak.enforce_type

Defined in awkward.operations.ak_enforce_type on line 23.

ak.enforce_type(array, type, *, highlevel=True, behavior=None, attrs=None)

Parameters:

• array – Array-like data (anything ak.to_layout recognizes).

• type (ak.types.Type, or str) – The type that array will be enforced to.

• highlevel (bool) – If True, return an ak.Array; otherwise, return a low-level ak.contents.Content subclass.

• behavior (None or dict) – Custom ak.behavior for the output array, if high-level.

• attrs (None or dict) – Custom attributes for the output array, if high-level.

Returns an array whose structure is modified to match the given type.

In addition to preserving the existing type and/or changing parameters,

• ak.types.OptionType can be added

  >>> a = ak.Array([1, 2, 3])
  >>> a.type.show()
  3 * int64
  >>> b = ak.enforce_type(a, "?int64")
  >>> b.type.show()
  3 * ?int64
  

  or removed (if there are no missing values)

  >>> a = ak.Array([1, 2, 3, None])
  >>> b = a[:-1]
  >>> b.type.show()
  3 * ?int64
  >>> c = ak.enforce_type(b, "int64")
  >>> c.type.show()
  3 * int64
  

• ak.types.UnionType can

  • grow to include new variant types,

  >>> a = ak.Array([{'x': 1}, 2.0])
  >>> a.type.show()
  2 * union[
      {
          x: int64
      },
      float64
  ]
  >>> b = ak.enforce_type(a, "union[{x: int64}, float64, string]")
  >>> b.type.show()
  2 * union[
  {
      x: float32
  },
      float64,
      string
  ]
  

  • convert to a single type,

  >>> a = ak.concatenate([
  ...   ak.Array([{'x': 1}, {'x': 2}]),
  ...   ak.Array([{'x': True, "y": None}, {'x': False, "y": None}])
  ... ])
  >>> a.type.show()
  4 * union[
      {
          x: int64
      },
      {
          x: bool,
          y: ?unknown
      }
  ]
  >>> b = ak.enforce_type(a, "{x: float64}")
  >>> b.type.show()
  4 * {
      x: float64
  }
  

  • project to a single type (if conversion to a single type is not possible, and the union contains no values for this type),

  >>> a = ak.concatenate([
  ...   ak.Array([{'x': 1}, {'x': 2}]),
  ...   ak.Array([{'x': "yes", "y": None}, {'x': "no", "y": None}])
  ... ])
  >>> b = a[:2]
  >>> b.type.show()
  2 * union[
      {
          x: int64
      },
      {
          x: string,
          y: ?unknown
      }
  ]
  >>> c = ak.enforce_type(b, "{x: int64}")
  >>> c.type.show()
  2 * {
      x: int64
  }
  

  • change type in a single variant.

  >>> a = ak.Array([{'x': 1}, 2.0])
  >>> a.type.show()
  2 * union[
      {
          x: int64
      },
      float64
  ]
  >>> b = ak.enforce_type(a, "union[{x: float32}, float64]")
  >>> b.type.show()
  2 * union[
  {
      x: float32
  },
      float64
  ]
  

  Due to these rules, changes to more than one variant of a union must be performed with multiple calls to ak.enforce_type

• ak.types.RecordType can

  • grow to include new optional fields / slots,

  >>> a = ak.Array([{'x': 1}])
  >>> a.type.show()
  1 * {
      x: int64
  }
  >>> b = ak.enforce_type(a, "{x: int64, y: ?float32}")
  >>> b.type.show()
  1 * {
      x: int64,
      y: ?float32
  }
  

  • shrink to drop existing fields / slots.

  >>> a = ak.Array([{'x': 1, 'y': 1j+3}])
  >>> a.type.show()
  1 * {
      x: int64,
      y: complex128
  }
  >>> b = ak.enforce_type(a, "{x: int64}")
  >>> b.type.show()
  1 * {
      x: int64
  }
  

  A ak.types.RecordType may only be converted to another ak.types.RecordType if it is of the same flavour, i.e. tuples can be converted to tuples, or records to records. Where a new field/slot is added to a ak.types.RecordType, it must be an ak.types.OptionType. For tuples, slots may only be added to the end of the tuple

• ak.types.RegularType can convert to a ak.types.ListType

  >>> a = ak.to_regular([[1, 2, 3], [4, 5, 6]])
  >>> a.type.show()
  2 * 3 * int64
  >>> b = ak.enforce_type(a, "var * int64")
  >>> b.type.show()
  2 * var * int64
  

• ak.types.ListType can convert to a ak.types.RegularType

  >>> a = ak.Array([[1, 2, 3], [4, 5, 6]])
  >>> a.type.show()
  2 * var * int64
  >>> b = ak.enforce_type(a, "3 * int64")
  >>> b.type.show()
  2 * 3 * int64
  

• ak.types.NumpyType can change primitive

  >>> a = ak.Array([1, 2, 3])
  >>> a.type.show()
  3 * int64
  >>> b = ak.enforce_type(a, "float32")
  >>> b.type.show()
  3 * float32
  

• ak.types.UnknownType can be converted to any other type

  >>> a = ak.Array([])
  >>> a.type.show()
  0 * unknown
  >>> b = ak.enforce_type(a, "float32")
  >>> b.type.show()
  0 * float32
  

  and can be converted to from any other type.

  >>> a = ak.Array([1, 2, 3])
  >>> a.type.show()
  3 * int64
  >>> b = ak.enforce_type(a, "?unknown")
  >>> b.type.show()
  3 * ?unknown
  

The conversion rules outlined above are not data-dependent; the appropriate rule is chosen from the layout and the given type value. If the conversion is not possible given the layout data, e.g. a conversion from an irregular list to a regular type, it will fail.