# `LabeledInstance`

### *class* capymoa.core.LabeledInstance[[source]](https://github.com/adaptive-machine-learning/CapyMOA/blob/3e255b1/src/capymoa/core/_instance.py#L273)

Bases: [`Instance`](capymoa.core.Instance.md#capymoa.core.Instance)

An [`Instance`](capymoa.core.Instance.md#capymoa.core.Instance) with a class label.

Most classification datastreams will automatically return instances for you
with the class label and index. For example, the [`capymoa.datasets.ElectricityTiny`](capymoa.datasets.ElectricityTiny.md#capymoa.datasets.ElectricityTiny)
dataset:

```pycon
>>> from capymoa.datasets import ElectricityTiny
...
>>> from capymoa.core import LabeledInstance
>>> stream = ElectricityTiny()
>>> instance: LabeledInstance = stream.next_instance()
>>> instance.y_label
'1'
```

The label and index are NOT the same. One is a human-readable string
and the other is a integer representation of the class label.
>>> instance.y_index
1
>>> instance.x
array([0.      , 0.056443, 0.439155, 0.003467, 0.422915, 0.414912])

#### \_\_init_\_(schema: [Schema](capymoa.stream.Schema.md#capymoa.stream.Schema), instance: InstanceExample | [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[Any](https://docs.python.org/3/library/typing.html#typing.Any), ...], [dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype)[float64]], [int](https://docs.python.org/3/builtins/functions.html#int)]) → [None](https://docs.python.org/3/builtins/constants.html#None)[[source]](https://github.com/adaptive-machine-learning/CapyMOA/blob/3e255b1/src/capymoa/core/_instance.py#L296)

Creates a new instance.

Its recommended that you prefer using [`from_array()`](#capymoa.core.LabeledInstance.from_array) or
[`from_java_instance()`](#capymoa.core.LabeledInstance.from_java_instance) to create instances, as they provide a more
user-friendly interface.

* **Parameters:**
  * **schema** – A schema that describes the datastream the instance belongs to.
  * **instance** – A vector of features (float values) or a Java instance.
* **Raises:**
  [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If the given instance type is of an unsupported type.

#### *classmethod* from_array(schema: [Schema](capymoa.stream.Schema.md#capymoa.stream.Schema), x: [ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[Any](https://docs.python.org/3/library/typing.html#typing.Any), ...], [dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype)[float64]], y_index: [int](https://docs.python.org/3/builtins/functions.html#int)) → [LabeledInstance](#capymoa.core.LabeledInstance)[[source]](https://github.com/adaptive-machine-learning/CapyMOA/blob/3e255b1/src/capymoa/core/_instance.py#L306)

Creates a new labeled instance from a schema, feature vector, and class index.

This is useful in the rare cases you need to create custom labeled instances
from scratch. In most cases, your datastream will automatically create
instances for you.

```pycon
>>> from capymoa.stream import Schema
...
>>> from capymoa.core import LabeledInstance
>>> import numpy as np
>>> schema = Schema.from_custom(
...     ["f1", "f2", "class"],
...     target="class",
...     name="CustomDataset",
...     categories={"class": ["yes", "no"]}
... )
>>> x = np.array([0.1, 0.2])
>>> instance = LabeledInstance.from_array(schema, x, 0)
>>> instance
LabeledInstance(
    Schema(CustomDataset),
    x=[0.1 0.2],
    y_index=0,
    y_label='yes'
)
>>> instance.y_label
'yes'
>>> instance.java_instance.toString()
'0.1,0.2,yes,'
```

#### *classmethod* from_csv_row(schema: [Schema](capymoa.stream.Schema.md#capymoa.stream.Schema), row: [Sequence](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]) → [Instance](capymoa.core.Instance.md#capymoa.core.Instance)[[source]](https://github.com/adaptive-machine-learning/CapyMOA/blob/3e255b1/src/capymoa/core/_instance.py#L132)

Create an instance from a CSV row.

```pycon
>>> from capymoa.stream import Schema
>>> from capymoa.core import Instance
>>> schema = Schema.from_custom(
...     ["feature1", "feature2", "target"],
...     target="target",
...     categories={"feature2": ["A", "B"], "target": ["yes", "no"]},
...     name="classification-example"
... )
>>> row = ["1.0", "A", "yes"]
>>> instance = Instance.from_csv_row(schema, row)
>>> instance
Instance(
    Schema(classification-example),
    x=[1. 0.],
)
>>> instance.x
array([1., 0.])
```

* **Parameters:**
  * **schema** – A schema providing the structure of each row. Like the header of the CSV.
  * **row** – A sequence of strings representing a CSV row.
* **Raises:**
  [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If an attribute type is unsupported.
* **Returns:**
  A new [`Instance`](capymoa.core.Instance.md#capymoa.core.Instance) object.

#### *classmethod* from_java_instance(schema: [Schema](capymoa.stream.Schema.md#capymoa.stream.Schema), java_instance: InstanceExample) → [Instance](capymoa.core.Instance.md#capymoa.core.Instance)[[source]](https://github.com/adaptive-machine-learning/CapyMOA/blob/3e255b1/src/capymoa/core/_instance.py#L99)

#### *property* java_instance *: InstanceExample*

Returns a representation of the instance in Java for use in MOA. This
method is for advanced users who want to directly interact with MOA’s Java
API.

#### *property* schema *: [Schema](capymoa.stream.Schema.md#capymoa.stream.Schema)*

Returns the schema of the instance and the stream it belongs to.

#### *property* x *: [ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[Any](https://docs.python.org/3/library/typing.html#typing.Any), ...], [dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype)[float64]]*

Returns a feature vector containing float values for the instance.

* NaN values indicate missing features.

#### *property* y_index *: [int](https://docs.python.org/3/builtins/functions.html#int)*

Returns the index of the class. It is useful for classification
tasks as it provides a numeric representation of the class label, ranging
from zero to the number of classes.

* Values of -1 indicate a missing class label.

#### *property* y_label *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)*

Returns the class label of the instance as a string.