{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# FancyArray Examples\n",
    "\n",
    "The `FancyArray` class in the `fancypy` library provides a robust and flexible way to handle array data with enhanced functionality. This documentation covers the usage of the `FancyArray` class, including initialization, array manipulation, and array analysis.\n",
    "\n",
    "## Array Initialization\n",
    "\n",
    "### Creating a FancyArray\n",
    "\n",
    "To create an instance of a `FancyArray`, simply initialize it with the necessary data. `FancyArray` can handle different types of data and provide various functionalities out of the box.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import ClassVar\n",
    "\n",
    "import numpy as np\n",
    "from numpy.typing import NDArray\n",
    "\n",
    "from power_grid_model_ds.fancypy import FancyArray\n",
    "\n",
    "\n",
    "class FancyTestArray(FancyArray):\n",
    "    \"\"\"Test array with some attributes\"\"\"\n",
    "\n",
    "    id: NDArray[np.int_]\n",
    "    test_int: NDArray[np.int_]\n",
    "    test_float: NDArray[np.float64]\n",
    "    test_str: NDArray[np.str_]\n",
    "    test_bool: NDArray[np.bool_]\n",
    "\n",
    "\n",
    "fancy_array = FancyTestArray(\n",
    "    id=[1, 2, 3],\n",
    "    test_int=[3, 0, 4],\n",
    "    test_float=[4.0, 4.0, 1.0],\n",
    "    test_str=[\"a\", \"c\", \"d\"],\n",
    "    test_bool=[True, False, True],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This creates a FancyTestArray instance with integer, float, boolean and string columns.\n",
    "\n",
    "## Array Manipulation\n",
    "\n",
    "### Accessing Array Elements\n",
    "\n",
    "You can access the elements of a FancyArray using standard indexing. The class supports both single and multiple column access.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Accessing a single column\n",
    "id_column = fancy_array[\"id\"]\n",
    "id_column = fancy_array.id\n",
    "\n",
    "# Accessing multiple columns\n",
    "subset = fancy_array[[\"id\", \"test_int\"]]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setting Attributes\n",
    "\n",
    "Attributes of the FancyArray can be dynamically set and modified. Changes are reflected in the underlying data.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Setting new values to a column\n",
    "fancy_array.id = np.array([9, 9, 9])\n",
    "fancy_array[\"id\"] = np.array([9, 9, 9])\n",
    "fancy_array.id = [9, 9, 9]\n",
    "fancy_array[\"id\"] = [9, 9, 9]\n",
    "fancy_array.id = 9\n",
    "fancy_array[\"id\"] = 9"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Preventing Deletion of Numpy Attributes\n",
    "\n",
    "Certain attributes inherent to numpy arrays, like size, cannot be deleted from a FancyArray.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Attempting to delete a numpy attribute raises an error\n",
    "try:\n",
    "    del fancy_array.size\n",
    "except AttributeError as e:\n",
    "    print(e)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Array Analysis\n",
    "\n",
    "Iterating Over Rows\n",
    "You can iterate over the rows of a FancyArray, and each row is also an instance of FancyArray.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for row in fancy_array:\n",
    "    print(row)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Analyzing Data\n",
    "\n",
    "The FancyArray class allows for detailed data analysis. You can use various numpy functions and methods to perform analysis on the data.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Example analysis: sum of a column\n",
    "total = np.sum(fancy_array.test_int)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Handling Non-Existing Attributes\n",
    "\n",
    "Attempting to access a non-existing attribute will raise an AttributeError.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    value = fancy_array.non_existing_attribute\n",
    "except AttributeError as e:\n",
    "    print(e)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Subclassing FancyArray\n",
    "\n",
    "You can create subclasses of FancyArray to add specific functionality or constraints, such as custom string lengths.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class CustomStrLengthArray(FancyArray):\n",
    "    test_str: NDArray[np.str_]\n",
    "    _str_lengths: ClassVar = {\"test_str\": 100}\n",
    "\n",
    "\n",
    "custom_array = CustomStrLengthArray(test_str=[\"a\" * 100])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using `fancypy`\n",
    "\n",
    "The `fancypy` library provides additional tools and utilities to enhance the functionality of `FancyArray`. These tools help with various operations such as data manipulation, validation, and transformation.\n",
    "\n",
    "### Importing `fancypy`\n",
    "\n",
    "To use the functionalities provided by `fancypy`, you need to import the library along with `FancyArray`.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "from power_grid_model_ds import fancypy as fp\n",
    "from power_grid_model_ds.fancypy import FancyArray"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example Functions\n",
    "\n",
    "#### concatenate\n",
    "\n",
    "The concatenate function combines multiple FancyArray instances into a single array. This is useful for merging datasets.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class FancyTestArray(FancyArray):\n",
    "    \"\"\"Test array with some attributes\"\"\"\n",
    "\n",
    "    id: NDArray[np.int_]\n",
    "    value: NDArray[np.int_]\n",
    "\n",
    "\n",
    "# Creating two FancyTestArray instances\n",
    "array1 = FancyTestArray(\n",
    "    id=[1, 2],\n",
    "    value=[10, 20],\n",
    ")\n",
    "array2 = FancyTestArray(\n",
    "    id=[3, 4],\n",
    "    value=[30, 40],\n",
    ")\n",
    "\n",
    "# Concatenating the arrays\n",
    "concatenated_array = fp.concatenate(array1, array2)\n",
    "print(concatenated_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### unique\n",
    "\n",
    "The unique function returns the unique elements of a FancyArray along a specified axis. This is similar to numpy's unique function but tailored for FancyArray.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Creating a FancyTestArray with duplicate values\n",
    "fancy_array = FancyTestArray(\n",
    "    id=[1, 2, 2, 3],\n",
    "    value=[10, 20, 20, 30],\n",
    ")\n",
    "\n",
    "\n",
    "# Getting unique elements\n",
    "unique_array = fp.unique(fancy_array, axis=0)\n",
    "print(unique_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### sort\n",
    "\n",
    "The sort function sorts the elements of a FancyArray along a specified axis.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Creating a FancyArray with unsorted values\n",
    "fancy_array = FancyTestArray(\n",
    "    id=[3, 1, 2],\n",
    "    value=[30, 10, 20],\n",
    ")\n",
    "\n",
    "# Sorting the array by the 'id' column\n",
    "sorted_array = fp.sort(fancy_array, axis=0)\n",
    "print(sorted_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### array_equal\n",
    "\n",
    "The array_equal function checks whether two FancyArray instances are element-wise equal. This is useful for comparing datasets.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Creating two FancyTestArray instances for comparison\n",
    "array1 = FancyTestArray(\n",
    "    id=[1, 2, 3],\n",
    "    value=[10, 20, 30],\n",
    ")\n",
    "array2 = FancyTestArray(\n",
    "    id=[1, 2, 3],\n",
    "    value=[10, 20, 30],\n",
    ")\n",
    "\n",
    "# Checking if the arrays are equal\n",
    "are_equal = fp.array_equal(array1, array2)\n",
    "print(f\"Are the arrays equal? {are_equal}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using Filters\n",
    "\n",
    "The FancyArray class provides various filtering capabilities to manipulate and analyze array data efficiently. This section covers how to use the filtering functions such as exclude, filter, and get based on the provided test files.\n",
    "\n",
    "### Excluding Elements\n",
    "\n",
    "#### Exclude by ID\n",
    "\n",
    "The exclude method allows you to remove elements from the array based on specified criteria. You can exclude elements by their ID.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Exclude elements with ID 1\n",
    "excluded_array = fancy_array.exclude(id=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Exclude by Value\n",
    "\n",
    "You can also exclude elements based on the value of a specific attribute.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Exclude elements where 'value' is 10\n",
    "excluded_array = fancy_array.exclude(value=10)\n",
    "print(excluded_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Exclude with Multiple Conditions\n",
    "\n",
    "The exclude method supports logical operations to combine multiple conditions. By default, it uses the AND operation, but you can specify the OR operation using the mode\\_ parameter.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Exclude elements where 'id'=1 or 'value'=20\n",
    "excluded_array = fancy_array.exclude(id=1, value=20, mode_=\"OR\")\n",
    "print(excluded_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Filtering Elements\n",
    "\n",
    "#### Filter by ID\n",
    "\n",
    "The filter method allows you to select elements from the array based on specified criteria. Filtering by ID can be done as follows:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Filter elements with ID 1\n",
    "filtered_array = fancy_array.filter(id=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Filter by Value\n",
    "\n",
    "Similar to the exclude method, you can filter elements based on the value of a specific attribute.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Filter elements where 'value' is 20\n",
    "filtered_array = fancy_array.filter(value=20)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Filter with Multiple Conditions\n",
    "\n",
    "The filter method also supports logical operations for combining multiple conditions.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Filter elements where 'id' is 1 or 'value' is 20\n",
    "filtered_array = fancy_array.filter(id=1, value=20, mode_=\"OR\")\n",
    "print(filtered_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Getting Elements\n",
    "\n",
    "#### Get by ID\n",
    "\n",
    "The get method retrieves a single element from the array that matches the specified criteria. You can get elements by their ID.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get element with ID 1\n",
    "element = fancy_array.get(id=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Get by Value\n",
    "\n",
    "You can also retrieve elements based on the value of a specific attribute.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get element where 'value' is 20\n",
    "element = fancy_array.get(value=20)\n",
    "print(element)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Handling Multiple Matches\n",
    "\n",
    "If the get method finds multiple elements that match the criteria, it raises a MultipleRecordsReturned exception. If no elements match, it raises a RecordDoesNotExist exception.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Handling multiple matches\n",
    "from power_grid_model_ds.errors import MultipleRecordsReturned, RecordDoesNotExist\n",
    "\n",
    "fancy_array = FancyTestArray(\n",
    "    id=[1, 2, 3, 4],\n",
    "    value=[10, 20, 20, 30],\n",
    ")\n",
    "\n",
    "try:\n",
    "    element = fancy_array.get(value=20)\n",
    "except MultipleRecordsReturned:\n",
    "    print(\"Multiple records found\")\n",
    "\n",
    "# Handling no matches\n",
    "try:\n",
    "    element = fancy_array.get(value=99.0)\n",
    "except RecordDoesNotExist:\n",
    "    print(\"No record found\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}