# Модель данных и числовые типы
## `DType`
Каждый читатель отображает собственные теги типов на это одно перечисление, а
каждый писатель — обратно. Благодаря этому объём работы по преобразованию
пропорционален сумме числа форматов и числа типов, а не их произведению.
| Логический | `Bool` | 1 |
| Знаковые | `I8` `I16` `I32` `I64` | 1, 2, 4, 8 |
| Беззнаковые | `U8` `U16` `U32` `U64` | 1, 2, 4, 8 |
| 8-битные вещественные | `F8E4M3` `F8E5M2` | 1 |
| Половинная точность | `F16` `BF16` | 2 |
| Одинарная, двойная | `F32` `F64` | 4, 8 |
| Четверная | `F128` | 16 |
| Расширенный x87 | `X87` | 10 (хранится в 12 или 16) |
| Комплексные | `C64` `C128` `C256` | 8, 16, 32 |
| Текст и байты | `Str(n)` `Bytes(n)` | фиксированная ширина |
| Непрозрачный | `Object` | в numpy размер указателя; здесь разбирается рекурсивно |
| Записи | `Struct(Vec<Field>)` | сумма полей |
Предикаты: `size()`, `is_integer()`, `is_float()`, `is_complex()`,
`is_numeric()`.
### Ловушка в именовании, о которой стоит знать
numpy называет типы по числу **байт**, поэтому `f8` — это double. `pyferrite`
называет малые вещественные типы по числу **бит**, поэтому `FloatKind::F8E4M3`
— восьмибитное число. `FloatKind::parse` разбирает оба написания, а строки
дескрипторов numpy в заголовках файлов всегда читаются в смысле numpy.
Двусмысленность существует только в прозе и никогда — в самом формате.
## Вещественные типы, написанные с нуля
Ни одного из них нет в стабильном Rust, поэтому крейт реализует их сам.
**`F16`** — IEEE binary16. Округление к ближайшему чётному, субнормальные
числа, сохранение полезной нагрузки NaN.
**`BF16`** — bfloat16: старшие шестнадцать бит `f32`, сохраняющие полный
диапазон порядка ценой битов мантиссы. Именно поэтому он не переполняется там,
где переполняется `F16`:
```rust
# use pyferrite::prelude::*;
let big = BF16::from_f32(3.0e38);
assert!(big.to_f32().is_finite()); // f16 здесь дал бы inf
```
**`F8E4M3`** — четыре бита порядка, три бита мантиссы, смещение 7, бесконечности
нет, максимум 448. **`F8E5M2`** — пять и два, смещение 15, форма как у IEEE,
максимум 57344. Это два формата, применяемых для квантованного вывода.
**`F128`** — IEEE binary128 с программными сложением, вычитанием, умножением и
делением. Корректное округление, субнормальные числа и все обычные особые
случаи.
```rust
# use pyferrite::prelude::*;
let third = F128::from_f64(1.0) / F128::from_f64(3.0);
assert_eq!((third * F128::from_f64(3.0)).to_f64(), 1.0);
```
**x87, 80 бит** — то, что numpy называет `longdouble` на x86 под Linux.
Декодируется в `F128` и кодируется из него, вместе с явным битом целой части,
который отличает этот формат от всех остальных типов IEEE.
**Комплексные** — `Complex32`, `Complex64` и `Complex128`; последний построен на
`F128` и покрывает numpy-типы `complex64`, `complex128` и `complex256`.
## Приведение типов
`Array::cast(&DType, CastPolicy)` преобразует между любыми двумя типами
элементов. Все преобразования идут через широкий промежуточный скаляр
(`i128`, `u128`, `F128` или пару комплексных), поэтому ни один путь не теряет
точности сверх неизбежного.
| `Strict` *(по умолчанию)* | `Err(Error::Cast)` с указанием значения и целевого диапазона |
| `Saturate` | Обрезать по минимуму или максимуму целевого типа |
| `Wrap` | Усечь битовый образ, как приведение в C |
```rust
# use pyferrite::prelude::*;
# use ndarray::{ArrayD, IxDyn};
let a = Array::I64(ArrayD::from_shape_vec(IxDyn(&[2]), vec![-99_999, 99_999]).unwrap());
assert!(a.cast(&DType::I16, CastPolicy::Strict).is_err());
let clamped = a.cast(&DType::I16, CastPolicy::Saturate).unwrap();
assert_eq!(clamped.as_i16().unwrap().as_slice().unwrap(), &[i16::MIN, i16::MAX]);
```
Сужение вещественных типов при `Strict` не приводит к ошибке — округление и
переполнение это разные вещи, — но значение за пределами диапазона целевого
типа станет бесконечностью, а это обычно та ошибка, о которой хочется узнать.
Если предпочтительнее обрезать, используйте `Saturate`.
## Изменяемость `Value`
Любое чтение возвращает данные во владение. Никакого заимствованного
представления отображённого файла, о котором нужно помнить, нет, поэтому для
изменения не требуется ничего, кроме `let mut`:
```rust,no_run
# use pyferrite::prelude::*;
let mut v = read("weights.npy")?;
v.as_array_mut()
.and_then(|a| a.as_f32_mut())
.map(|w| w.iter_mut().for_each(|x| *x = x.clamp(-1.0, 1.0)));
# Ok::<(), pyferrite::Error>(())
```
`arrays_mut()` делает то же самое для целого вложенного контейнера за один
проход.
## Таблицы
`Frame` — нейтральный табличный тип, стоящий между pandas, polars и
структурированными массивами numpy. Структурированный массив numpy при чтении
превращается в `Frame`, если только `ReadOptions::keep_record_arrays` не велит
обратное. Каждая `Series` несёт имя, `Array` значений и необязательную битовую
маску валидности для пропусков — единственное, что numpy выразить не умеет.
При включённой возможности `polars-interop` `Frame` преобразуется в
`polars::DataFrame` и обратно. Таблицы pandas приходят в виде своего
сериализованного `BlockManager`; числовые блоки восстанавливаются, а всё
экзотическое сохраняется как `PyObject`, а не угадывается.
### Чтение таблицы pandas
`interop::pandas::to_frame` восстанавливает сериализованный
`pandas.DataFrame`. pandas сохраняет не таблицу, а `BlockManager`: столбцы
сгруппированы по типу в двумерные блоки, каждый из которых помнит, какие
позиции столбцов он занимает. Преобразователь разбирает эти блоки обратно на
столбцы и соединяет их с индексом столбцов.
```rust,no_run
# use pyferrite::prelude::*;
let v = read("frame.pkl")?;
match pyferrite::interop::pandas::to_frame(&v)? {
Some(f) => println!("{:?}", f.names()),
None => println!("сохранено как инертный объект: {}", v.type_name()),
}
# Ok::<(), pyferrite::Error>(())
```
Раскладка различается от версии к версии: менеджер может нести содержимое как
аргументы конструктора или как сохранённое состояние, а блоки — приходить
вызовами `_unpickle_block` или простыми кортежами. Принимаются все варианты, а
массивы-расширения вроде `StringArray` разворачиваются до своих значений. Если
раскладка не распознана, функция возвращает `Ok(None)`, и вызывающая сторона
сохраняет инертный `PyObject`, так что ничего не теряется молча.
### Преобразование в polars
При включённой возможности `polars-interop`:
```rust,no_run
# #[cfg(feature = "polars-interop")] {
# use pyferrite::prelude::*;
# let frame = pyferrite::value::Frame::default();
let df = pyferrite::interop::polars::to_polars(&frame)?;
let back = pyferrite::interop::from_polars(&df)?;
# }
# Ok::<(), pyferrite::Error>(())
```
Пропуски передаются в обе стороны: null в polars становится отметкой в битовой
маске валидности `Series`, а числовой буфер под ней остаётся плотным, поэтому
его по-прежнему можно записать прямо в numpy. Типы, для которых у polars нет
места, — `f8`, `f16`, `bf16`, `f128` — расширяются до `f64`; комплексные числа
отвергаются, а не искажаются.