# Chalk Python SDK Reference: DataFrame
source: https://docs.chalk.ai/api-docs#section-dataframe

`chalk.features.DataFrame` declares has-many features and the input and return types of resolvers. For example:

```python
from chalk.features import DataFrame, features, online
@features
class User:
   id: int
   name: str
   email: str
```

```python
@online
def get_users() -> DataFrame[User.id, User.name]:
   return DataFrame([
       User(id=1, name="Alice"),
       User(id=2, name="Bob")
   ])
```

`DataFrame[...]` is parameterized by the columns it contains. Here, the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) has two columns, `User.id` and `User.name`.

This class is a different class from the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) in `chalkdf`, which is documented at [/dataframe-docs](https://docs.chalk.ai/dataframe-docs). For the feature [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) in feature classes and resolvers, see [Feature DataFrames](https://docs.chalk.ai/docs/dataframe).

## `DataFrame`
source: https://docs.chalk.ai/api-docs#DataFrame

Class

Chalk's DataFrame class models tabular data similar to how [`pandas`](https://pandas.pydata.org/) and `polars` do. DataFrame can be used a Chalk feature type, when defining has-many joins between feature classes. For more about the Chalk DataFrame, see: [Feature DataFrames](https://docs.chalk.ai/docs/dataframe)

NOTE: DataFrame functions are meant to be used in Python resolvers or in notebooks, but NOT in Chalk Expressions.

**Attributes**

- `filters`: `ClassVar[tuple[Filter, ...]]`
- `columns`: `tuple[Feature, ...]`
- `__limit__`: `int | None`
  The maximum number of rows to return
- `__relationship__`: `ClassVar[Feature | None]`
  The has-many relationship the rows belong to, if declared with `for_relationship(...)` or `DataFrame[...].for_relationship(...)`
- `shape`: `tuple[int, int]`
  The shape of the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) as a [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple) of `(num_rows, num_columns)`.

  **Examples**

  ```python
  DataFrame({User.id: [1, 2, 3, 4, 5]}).shape
  ```

  ```python
  (5, 1)
  ```

### `DataFrame.__class_getitem__(cols)`
source: https://docs.chalk.ai/api-docs#DataFrame.__class_getitem__

### `DataFrame.__init__(data, missing_value_strategy, pandas_dataframe, convert_dtypes, pydantic_model, verify_validity)`
source: https://docs.chalk.ai/api-docs#DataFrame.__init__

Construct a Chalk [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Parameters**

- `data`: `Any` = `None`
  The data. Can be an existing `pandas.DataFrame`, `polars.DataFrame` or `polars.LazyFrame`, a sequence of feature instances, or a [`dict`](https://docs.python.org/3/library/stdtypes.html#dict) mapping a feature to a sequence of values.
- `missing_value_strategy`: `MissingValueStrategy` = `'default_or_allow'`
  The strategy to use to handle missing values.

  A feature value is "missing" if it is an ellipsis (`...`), or it is [`None`](https://docs.python.org/3/library/constants.html#None) and the feature is not annotated as `Optional[...]`.

  The available strategies are:

  - `'error'`: Raise a [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError) if any missing values are found. Do not attempt to replace missing values with the default value for the feature.
  - `'default_or_error'`: If the feature has a default value, then replace missing values with the default value for the feature. Otherwise, raise a [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError).
  - `'default_or_allow'`: If the feature has a default value, then replace missing values with the default value for the feature. Otherwise, leave it as [`None`](https://docs.python.org/3/library/constants.html#None). This is the default strategy.
  - `'allow'`: Allow missing values to be stored in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame). This option may result non-nullable features being assigned [`None`](https://docs.python.org/3/library/constants.html#None) values.
- `pandas_dataframe`: `pd.DataFrame | None` = `None`
- `convert_dtypes`: `bool` = `True`
- `pydantic_model`: `Optional[Type[BaseModel]]` = `None`
- `verify_validity`: `bool` = `True`

**Examples**

Row-wise construction

```python
df = DataFrame([
    User(id=1, first="Sam", last="Wu"),
    User(id=2, first="Iris", last="Xi")
])
```

Column-wise construction

```python
df = DataFrame({
    User.id: [1, 2],
    User.first: ["Sam", "Iris"],
    User.last: ["Wu", "Xi"]
})
```

Construction from `polars.DataFrame`

```python
import polars
df = DataFrame(polars.DataFrame({
    "user.id": [1, 2],
    "user.first": ["Sam", "Iris"],
    "user.last": ["Wu", "Xi"]
}))
```

### `DataFrame.__getitem__(item)`
source: https://docs.chalk.ai/api-docs#DataFrame.__getitem__

Filter the rows of a [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) or project out columns.

You can select columns out of a [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) from the set of columns already present to produce a new [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) scoped down to those columns.

Or, you can filter the rows of a [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) by using Python's built-in operations on feature columns.

**Parameters**

- `item`: `Any`
  Filters and projections to apply to the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Returns**

`Features | DataFrame`

A [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with the filters and projections in `item` applied.

**Examples**

```python
df = DataFrame({
    User.age: [21, 22, 23],
    User.email: [...],
})
```

Filtering

```python
df = df[
    User.age > 21 and
    User.email == "joe@chalk.ai"
]
```

Projecting

```python
df[User.name]
```

Filtering & Projecting

```python
df = df[
    User.age > 21 and
    User.email == "joe@chalk.ai",
    User.name
]
```

### `DataFrame.group_by(group, agg)`
source: https://docs.chalk.ai/api-docs#DataFrame.group_by

Aggregate the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) by the specified columns. This can be used in Python resolvers or notebooks.

**Parameters**

- `group`: `Mapping[Feature | Any, Feature | Any]`
  A mapping from the desired column name in the resulting [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) to the name of the column in the source [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).
- `agg`: `Mapping[Any, Any]`
  A mapping from the desired column name in the resulting [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) to the aggregation operation to perform on the source [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Returns**

`DataFrame`

The [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with the specified aggregations applied.

**Examples**

```python
from chalk.features import DataFrame
df = DataFrame(
    {
        User.id: [1, 1, 3],
        User.val: [1, 5, 10],
    }
).group_by(
     group={User.id: User.id}
     agg={User.val: op.median(User.val)}
)
```

```python
╭─────────┬──────────╮
│ User.id │ User.val │
╞═════════╪══════════╡
│  1      │ 3        │
├─────────┼──────────┤
│  3      │ 10       │
╰─────────┴──────────╯
```

### `DataFrame.histogram_list(nbins, bin_width, base, eps, column, descending)`
source: https://docs.chalk.ai/api-docs#DataFrame.histogram_list

Compute a histogram with fixed width bins. This can be used in Python resolvers or notebooks.

**Parameters**

- `nbins`: `int | None` = `None`
  If supplied, will be used to compute the binwidth.
- `bin_width`: `float | int | Duration | None` = `None`
  If not supplied, computed from the data (actual max and min values).
- `base`: `float | int | datetime | date | None` = `None`
  The value of the first histogram bin. Defaults to the minimum value of column.
- `eps`: `float` = `1e-13`
  Allowed floating point epsilon for histogram base
- `column`: `Any | None` = `None`
  The column to compute the histogram on. If not supplied, the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) is assumed to contain a single column.
- `descending`: `bool` = `False`
  If [`True`](https://docs.python.org/3/library/constants.html#True), the histogram buckets will be sorted in descending order.

**Returns**

`list[int]`

A list of the counts in each bin.

**Examples**

```python
DataFrame({
  Taco.price: list(range(100, 200)),
}).histogram_list(nbins=4, base=100)
```

```python
[25, 25, 25, 25]
```

### `DataFrame.group_by_hopping(index, agg, every, group, period, offset, start_by)`
source: https://docs.chalk.ai/api-docs#DataFrame.group_by_hopping

Group based on a time value ([`date`](https://docs.python.org/3/library/datetime.html#datetime.date) or [`datetime`](https://docs.python.org/3/library/datetime.html?highlight=datetime#datetime.datetime)).

The groups are defined by a time-based window, and optionally, other columns in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame). The "width" of the window is defined by the `period` parameter, and the spacing between the windows is defined by the `every` parameter. Note that if the `every` parameter is smaller than the `period` parameter, then the windows will overlap, and a single row may be assigned to multiple groups.

As an example, consider the following [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame):

``

val: a b c d e f g h ─────────●─────────●─────────●─────────●───────▶ time: A B C D ┌─────────┐ 1 │ a b │ 1: [a, b] └────┬────┴────┐ 2 ◀───▶│ b c │ 2: [b, c] every└────┬────┴────┐ 3 ◀────────▶│ c d e │ 3: [c, d, e] period └────┬────┴────┐ 4 │d e f│ 4: [d, e, f] └────┬────┴────┐ 5 │ f │ 5: [f] └────┬────┴────┐ 6 │ │ └────┬────┴────┐ 7 │ g h │ 7: [g, h] └────┬────┴────┐ 8 │g h │ 8: [g, h] └─────────┘ ``

In the above example, the sixth time bucket is empty, and will not be included in the resulting [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

This can be used in Python resolvers or notebooks.

**Parameters**

- `index`: `Feature | Any`
  The column to use as the index for the time-based grouping.
- `agg`: `Mapping[Any, Any]`
  A mapping from the desired column name in the resulting [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) to the aggregation operation to perform on the source [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).
- `every`: `str | timedelta`
  The spacing between the time-based windows. This parameter can be specified as a [`str`](https://docs.python.org/3/library/stdtypes.html#str) or a [`timedelta`](https://docs.python.org/3/library/datetime.html?highlight=datetime#datetime.timedelta). If specified as a [`str`](https://docs.python.org/3/library/stdtypes.html#str), then it must be a valid [`Duration`](https://docs.chalk.ai/api-docs#Duration).
- `group`: `Mapping[Feature | Any, Feature | Any] | None` = `None`
  A mapping from the desired column name in the resulting [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) to the name of the column in the source [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame). This parameter is optional, and if not specified, then the resulting [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) groups will be determined by the `index` parameter alone.
- `period`: `str | timedelta | None` = `None`
  The width of the time-based window. This parameter can be specified as a [`str`](https://docs.python.org/3/library/stdtypes.html#str) or a [`timedelta`](https://docs.python.org/3/library/datetime.html?highlight=datetime#datetime.timedelta). If specified as a [`str`](https://docs.python.org/3/library/stdtypes.html#str), then it must be a valid [`Duration`](https://docs.chalk.ai/api-docs#Duration). If [`None`](https://docs.python.org/3/library/constants.html#None) it is equal to `every`.

**Other parameters**

- `offset`: `str | timedelta | None` = `None`
  The offset to apply to the time-based window. This parameter can be specified as a [`str`](https://docs.python.org/3/library/stdtypes.html#str) or a [`timedelta`](https://docs.python.org/3/library/datetime.html?highlight=datetime#datetime.timedelta). If specified as a [`str`](https://docs.python.org/3/library/stdtypes.html#str), then it must be a valid [`Duration`](https://docs.chalk.ai/api-docs#Duration). If [`None`](https://docs.python.org/3/library/constants.html#None) it is equal to negative `every`.
- `start_by`: `'window' | 'datapoint' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sunday'` = `'window'`
  The strategy to determine the start of the first window by.

  - [`window`](https://docs.chalk.ai/api-docs#window): Truncate the start of the window with the ‘every’ argument.
  - `datapoint`: Start from the first encountered data point.
  - `monday | tuesday | types.EllipsisType`: Start from the first Monday before the first encountered data point.

**Returns**

`DataFrame`

A new [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with the specified time-based grouping applied. The resulting [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) will have a column for each of the keys in `group", "or each of the keys in`agg`, and for the`index` parameter.

**Examples**

```python
from chalk import DataFrame, op
df = DataFrame(
    {
        User.id: [1, 1, 3],
        User.val: [1, 5, 10],
        User.ts: [datetime(2020, 1, 1), datetime(2020, 1, 1), datetime(2020, 1, 3)],
    },
).group_by_hopping(
     index=User.ts,
     group={User.id: User.id},
     agg={User.val: op.median(User.val)},
     period="1d",
)
```

```python
╭─────────┬──────────┬──────────╮
│ User.id │ User.ts  │ User.val │
╞═════════╪══════════╪══════════╡
│  1      │ 2020-1-1 │ 3        │
├─────────┼──────────┼──────────┤
│  3      │ 2020-1-3 │ 10       │
╰─────────┴──────────┴──────────╯
```

### `DataFrame.join(df, on, how)`
source: https://docs.chalk.ai/api-docs#DataFrame.join

### `DataFrame.vstack(other)`
source: https://docs.chalk.ai/api-docs#DataFrame.vstack

Vertically stack the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with another [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) containing the same columns. The [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) other will be appended to the bottom of this [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame). This can be used in Python resolvers or notebooks.

**Parameters**

- `other`: `DataFrame`
  The other [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) to stack with this [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Returns**

`DataFrame`

The [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with the other [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) stacked on the bottom.

**Examples**

```python
from chalk.features import DataFrame
df = DataFrame([
    User(id=1, first="Sam", last="Wu"),
    User(id=2, first="Iris", last="Xi")
])
df.vstack(df)
```

### `DataFrame.num_unique(column)`
source: https://docs.chalk.ai/api-docs#DataFrame.num_unique

Return the number of unique values in the specified column. This can be used in Python resolvers or notebooks.

**Parameters**

- `column`: `Any` = `None`
  The column to compute the number of unique values for. If [`None`](https://docs.python.org/3/library/constants.html#None), then the number of unique values in the entire [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) is returned.

**Returns**

`int`

The number of unique values in the specified column.

**Examples**

```python
from chalk.features import DataFrame
df = DataFrame([
    User(id=1, first="Sam", last="Wu"),
    User(id=2, first="Iris", last="Xi")
])
df.num_unique(User.id)
```

```python
2
```

### `DataFrame.rename(mapping)`
source: https://docs.chalk.ai/api-docs#DataFrame.rename

Rename columns in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Parameters**

- `mapping`: `Mapping[Any, Any]`
  A mapping from the current feature for a column to the desired feature for the column.

**Returns**

`DataFrame`

The [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with the specified columns renamed.

**Examples**

```python
df = DataFrame([
    User(id=1, first="Sam", last="Wu"),
    User(id=2, first="Iris", last="Xi")
]).rename({User.last: User.family})
```

### `DataFrame.with_column(column, value)`
source: https://docs.chalk.ai/api-docs#DataFrame.with_column

Add a column to the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Parameters**

- `column`: `Any`
  The name of the column to add.
- `value`: `Any`
  The definition of the column to add. This could be a constant value (e.g. `1` or [`True`](https://docs.python.org/3/library/constants.html#True)), an expression (e.g. `op.max(User.score_1, User.score_2)`), or a list of values (e.g. `[1, 2, 3]`).

**Examples**

```python
df = DataFrame([
    User(id=1, first="Sam", last="Wu"),
    User(id=2, first="Iris", last="Xi")
])
# Set the fraud score to 0 for all users
df.with_column(User.fraud_score, 0)
# Concatenation of first & last as full_name
df.with_column(
    User.full_name, op.concat(User.first, User.last)
)
# Alias a column name
df.with_column(
    User.first_name, User.first
)
```

### `DataFrame.with_columns(c)`
source: https://docs.chalk.ai/api-docs#DataFrame.with_columns

Add columns to the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Parameters**

- `c`: `Mapping[Any, Any]`
  A [`Mapping`](https://docs.python.org/3/library/typing.html#typing.Mapping) from the desired name of the column in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) to the definition of the new column.

**Returns**

`DataFrame`

A new [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with all the existing columns, plus those specified in this function.

**Examples**

```python
df = DataFrame([
    User(id=1, first="Sam", last="Wu"),
    User(id=2, first="Iris", last="Xi")
])
# Set the fraud score to 0 for all users
df.with_columns({User.fraud_score: 0})
# Concatenation of first & last as full_name
df.with_columns({
    User.full_name: op.concat(User.first, User.last)
})
# Alias a column name
df.with_columns({
    User.first_name: User.first
})
```

### `DataFrame.from_dict(data)`
source: https://docs.chalk.ai/api-docs#DataFrame.from_dict

Deprecated. Use DataFrame(...) instead.

### `DataFrame.from_list(data)`
source: https://docs.chalk.ai/api-docs#DataFrame.from_list

Deprecated. Use DataFrame(...) instead.

### `DataFrame.read_delta(table_uri, version, columns, delta_table_options, pyarrow_options)`
source: https://docs.chalk.ai/api-docs#DataFrame.read_delta

### `DataFrame.read_parquet(path, columns, use_pyarrow)`
source: https://docs.chalk.ai/api-docs#DataFrame.read_parquet

### `DataFrame.read_csv(path, has_header, columns)`
source: https://docs.chalk.ai/api-docs#DataFrame.read_csv

Read a .csv file as a [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Parameters**

- `path`: `str`
  The path to the .csv file. This may be a S3 or GCS storage url.
- `has_header`: `bool` = `True`
  Whether the .csv file has a header row as the first row.
- `columns`: ` | None` = `None`
  A mapping of index to feature name.

**Returns**

`DataFrame`

A [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with the contents of the file loaded as features.

**Examples**

```python
values = DataFrame.read_csv(
    "s3://...",
    columns={0: MyFeatures.id, 1: MyFeatures.name},
    has_header=False,
)
```

### `DataFrame.read_avro(path)`
source: https://docs.chalk.ai/api-docs#DataFrame.read_avro

Read a `.avro` file as a [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Parameters**

- `path`: `str`
  The path to the `.avro` file. This may be a S3 or GCS storage url.

**Returns**

`DataFrame`

A [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with the contents of the file loaded as features.

**Examples**

```python
values = DataFrame.read_avro(
    "s3://...",
)
```

### `DataFrame.max()`
source: https://docs.chalk.ai/api-docs#DataFrame.max

Compute the max value of each of the columns in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame). The resulting [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) will have a single row with the max value of each column.

**Returns**

`DataFrame`

A [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with the max value of each column.

**Examples**

```python
from chalk.features import DataFrame
df = DataFrame(
    {
        User.id: [1, 2, 3],
        User.val: [1, 4, 10],
    }
).max()
```

```python
╭─────────┬──────────╮
│ User.id │ User.val │
╞═════════╪══════════╡
│ 3       │ 10       │
╰─────────┴──────────╯
```

### `DataFrame.mean()`
source: https://docs.chalk.ai/api-docs#DataFrame.mean

Compute the mean value of each of the columns in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame). The resulting [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) will have a single row with the mean value of each column.

**Returns**

`DataFrame`

A [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with the mean value of each column.

**Examples**

```python
from chalk.features import DataFrame
df = DataFrame(
    {
        User.id: [1, 2, 3],
        User.val: [1, 4, 10],
    }
).mean()
```

```python
╭─────────┬──────────╮
│ User.id │ User.val │
╞═════════╪══════════╡
│ 2       │ 5        │
╰─────────┴──────────╯
```

### `DataFrame.median()`
source: https://docs.chalk.ai/api-docs#DataFrame.median

Compute the median value of each of the columns in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame). The resulting [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) will have a single row with the median value of each column.

**Returns**

`DataFrame`

A [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with the median value of each column.

**Examples**

```python
from chalk.features import DataFrame
df = DataFrame(
    {
        User.id: [1, 2, 3],
        User.val: [1, 4, 10],
    }
).median()
```

```python
╭─────────┬──────────╮
│ User.id │ User.val │
╞═════════╪══════════╡
│ 2       │ 4        │
╰─────────┴──────────╯
```

### `DataFrame.min()`
source: https://docs.chalk.ai/api-docs#DataFrame.min

Compute the min value of each of the columns in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame). The resulting [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) will have a single row with the min value of each column.

**Returns**

`DataFrame`

A [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with the min value of each column.

**Examples**

```python
from chalk.features import DataFrame
df = DataFrame(
    {
        User.id: [1, 2, 3],
        User.val: [1, 4, 10],
    }
).min()
```

```python
╭─────────┬──────────╮
│ User.id │ User.val │
╞═════════╪══════════╡
│ 1       │ 1        │
╰─────────┴──────────╯
```

### `DataFrame.std(ddof)`
source: https://docs.chalk.ai/api-docs#DataFrame.std

Compute the standard deviation of each of the columns in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame). The resulting [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) will have a single row with the standard deviation of each column.

**Parameters**

- `ddof`: `int` = `1`
  "Delta Degrees of Freedom": the divisor used in the calculation is N - ddof, where N represents the number of elements. By default, ddof is 1.

**Returns**

`DataFrame`

A [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with the standard deviation of each column.

**Examples**

```python
from chalk.features import DataFrame
df = DataFrame(
    {
        User.id: [1, 2, 3],
        User.val: [1, 4, 10],
    }
).std()
```

```python
╭─────────┬──────────╮
│ User.id │ User.val │
╞═════════╪══════════╡
│ 1       │ 4.5826   │
╰─────────┴──────────╯
```

### `DataFrame.sum()`
source: https://docs.chalk.ai/api-docs#DataFrame.sum

Compute the sum of each of the columns in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame). The resulting [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) will have a single row with the sum of each column.

**Returns**

`DataFrame`

A [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with the sum of each column.

### `DataFrame.var(ddof)`
source: https://docs.chalk.ai/api-docs#DataFrame.var

Compute the variance of each of the columns in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Parameters**

- `ddof`: `int` = `1`
  "Delta Degrees of Freedom": the divisor used in the calculation is N - ddof, where N represents the number of elements. By default, ddof is 1.

**Returns**

`DataFrame`

A [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with the variance of each column.

### `DataFrame.any()`
source: https://docs.chalk.ai/api-docs#DataFrame.any

Returns whether any the values in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) are truthy. Requires the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) to only contain boolean values.

### `DataFrame.all()`
source: https://docs.chalk.ai/api-docs#DataFrame.all

Returns whether all the values in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) are truthy. Requires the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) to only contain boolean values.

### `DataFrame.__len__()`
source: https://docs.chalk.ai/api-docs#DataFrame.__len__

Returns the number of rows in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Returns**

`int`

The number of rows in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Examples**

```python
from chalk.features import DataFrame
df = DataFrame(
    {
        User.id: [1, 2, 3],
        User.val: [1, 4, 10],
    }
)
len(df)
```

```python
3
```

### `DataFrame.count()`
source: https://docs.chalk.ai/api-docs#DataFrame.count

Returns the number of rows in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Returns**

`int`

The number of rows in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Examples**

```python
from chalk.features import DataFrame
df = DataFrame(
    {
        User.id: [1, 2, 3],
        User.val: [1, 4, 10],
    }
)
len(df)
```

```python
3
```

```python
df.count()
```

```python
3
```

### `DataFrame.item()`
source: https://docs.chalk.ai/api-docs#DataFrame.item

Get the only item from the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame). This method will raise an error if the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) contains more than one row or more than column.

### `DataFrame.sort(by, more_by, descending, nulls_last)`
source: https://docs.chalk.ai/api-docs#DataFrame.sort

Sort the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) by the given columns.

**Parameters**

- `by`: `str | Feature | Any`
  Feature(s) to sort by. Strings are parsed as feature names.
- `more_by`: `str | Feature | Any` = `()`
  Additional columns to sort by, specified as positional arguments.
- `descending`: `bool` = `False`
  Sort in descending order. When sorting by multiple columns, can be specified per feature by passing a sequence of booleans.
- `nulls_last`: `bool` = `False`
  Place null values last.

**Returns**

`DataFrame`

A new [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) with the rows sorted.

**Examples**

```python
df = DataFrame({
    User.a: [1, 2, 3],
    User.b: [3, 2, 1],
})
df.sort(User.a)
```

```python
a  b
-----------
0     1  3
1     2  2
2     3  1
```

### `DataFrame.__bool__()`
source: https://docs.chalk.ai/api-docs#DataFrame.__bool__

### `DataFrame.__float__()`
source: https://docs.chalk.ai/api-docs#DataFrame.__float__

### `DataFrame.__int__()`
source: https://docs.chalk.ai/api-docs#DataFrame.__int__

### `DataFrame.__eq__(other)`
source: https://docs.chalk.ai/api-docs#DataFrame.__eq__

### `DataFrame.__ne__(other)`
source: https://docs.chalk.ai/api-docs#DataFrame.__ne__

### `DataFrame.__gt__(other)`
source: https://docs.chalk.ai/api-docs#DataFrame.__gt__

### `DataFrame.__lt__(other)`
source: https://docs.chalk.ai/api-docs#DataFrame.__lt__

### `DataFrame.__ge__(other)`
source: https://docs.chalk.ai/api-docs#DataFrame.__ge__

### `DataFrame.__le__(other)`
source: https://docs.chalk.ai/api-docs#DataFrame.__le__

### `DataFrame.__add__(other)`
source: https://docs.chalk.ai/api-docs#DataFrame.__add__

### `DataFrame.__sub__(other)`
source: https://docs.chalk.ai/api-docs#DataFrame.__sub__

### `DataFrame.__mul__(other)`
source: https://docs.chalk.ai/api-docs#DataFrame.__mul__

### `DataFrame.__truediv__(other)`
source: https://docs.chalk.ai/api-docs#DataFrame.__truediv__

### `DataFrame.__floordiv__(other)`
source: https://docs.chalk.ai/api-docs#DataFrame.__floordiv__

### `DataFrame.__mod__(other)`
source: https://docs.chalk.ai/api-docs#DataFrame.__mod__

### `DataFrame.__pow__(other)`
source: https://docs.chalk.ai/api-docs#DataFrame.__pow__

### `DataFrame.to_polars(prefixed)`
source: https://docs.chalk.ai/api-docs#DataFrame.to_polars

Get the underlying [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) as a `polars.LazyFrame`.

**Parameters**

- `prefixed`: `bool` = `True`
  Whether to prefix the column names with the feature namespace (i.e. if prefixed=True, `user.name`, if if prefixed=False, `name`)

**Returns**

`pl.LazyFrame`

The underlying `polars.LazyFrame`.

### `DataFrame.to_pyarrow(prefixed)`
source: https://docs.chalk.ai/api-docs#DataFrame.to_pyarrow

Get the underlying [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) as a `pyarrow.Table`.

**Parameters**

- `prefixed`: `bool` = `True`
  Whether to prefix the column names with the feature namespace (i.e. if prefixed=True, `user.name`, if if prefixed=False, `name`)

**Returns**

`pa.Table`

The underlying `pyarrow.Table`. This format is the canonical representation of the data in Chalk.

### `DataFrame.to_pandas(string_names, prefixed)`
source: https://docs.chalk.ai/api-docs#DataFrame.to_pandas

Get the underlying [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) as a `pandas.DataFrame`.prefixed Whether to prefix the column names with the feature namespace (i.e. if prefixed=True, `user.name`, if if prefixed=False, `name`)

**Parameters**

- `string_names`: `bool` = `False`
  If [`True`](https://docs.python.org/3/library/constants.html#True), use strings for column names. If [`False`](https://docs.python.org/3/library/constants.html#False), use `Feature` objects.
- `prefixed`: `bool` = `True`

**Returns**

`pd.DataFrame`

The data formatted as a `pandas.DataFrame`.

### `DataFrame.to_features()`
source: https://docs.chalk.ai/api-docs#DataFrame.to_features

Get values in the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame) as `Features` instances.

**Examples**

```python
df = DataFrame({
    SpaceShip.id: [1, 2],
    SpaceShip.volume: [4_000, 5_000]
})
df.to_features()
```

```python
[
    SpaceShip(id=1, volume=4000),
    SpaceShip(id=2, volume=5000)
]
```

### `DataFrame.slice(offset, length)`
source: https://docs.chalk.ai/api-docs#DataFrame.slice

Slice the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Parameters**

- `offset`: `int` = `0`
  The offset to start at.
- `length`: `int | None` = `None`
  The number of rows in the slice. If [`None`](https://docs.python.org/3/library/constants.html#None) (the default), include all rows from `offset` to the end of the [`DataFrame`](https://docs.chalk.ai/api-docs#DataFrame).

**Returns**

`DataFrame`

The dataframe with the slice applied.
