{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "58f40b60",
   "metadata": {},
   "source": [
    "\n",
    "# Importing and Exporting Single-Case Data\n",
    "\n",
    "The functions `read_scd` and `write_scd` allow users to import and export single-case experimental design (SCED) data from various file formats such as CSV and Excel. These functions ensure that the data structure remains consistent for analysis.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "880673cb",
   "metadata": {},
   "source": [
    "\n",
    "## Importing Data with `read_scd`\n",
    "\n",
    "The `read_scd` function reads a dataset and formats it correctly for analysis. It supports CSV and Excel files and allows customization of column names and phase labels.\n",
    "\n",
    "### Required Arguments:\n",
    "- `file`: Path to the dataset.\n",
    "\n",
    "### Optional Arguments:\n",
    "- `cvar`: Name of the column containing case identifiers (default `\"case\"`).\n",
    "- `pvar`: Name of the column containing phase labels (default `\"phase\"`).\n",
    "- `dvar`: Name of the column containing dependent values (default `\"values\"`).\n",
    "- `mvar`: Name of the column containing measurement time (default `\"mt\"`).\n",
    "- `sort_cases`: If `True`, cases are sorted in the output.\n",
    "- `phase_names`: Allows renaming phases (e.g., `[\"A\", \"B\"]`).\n",
    "- `file_type`: Manually specify the file type (`\"csv\"`, `\"xls\"`, `\"xlsx\"`), if needed.\n",
    "- `na_values`: Defines which values should be treated as missing (default `[\"\", \"NA\"]`).\n",
    "\n",
    "If no phase information is provided, the function keeps the original structure.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "9c562b08",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "📖 scia 1.101.0.dev6 - For Documentation, visit: https://ahsankhodami.github.io/scia/intro.html\n"
     ]
    }
   ],
   "source": [
    "\n",
    "import scia as sc\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c960d37a",
   "metadata": {},
   "source": [
    "\n",
    "### Example 1: Reading a CSV File\n",
    "\n",
    "To import a dataset from a CSV file while keeping default settings:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "1491b39e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Imported 2 cases\n",
      "  case         phase  values  mt\n",
      "0    A      Baseline       2   1\n",
      "1    A      Baseline       3   2\n",
      "2    A  Intervention       5   3\n",
      "3    B      Baseline       1   1\n",
      "4    B      Baseline       4   2\n"
     ]
    }
   ],
   "source": [
    "\n",
    "df = sc.read_scd(\"sample.csv\")\n",
    "print(df.head())\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c20c0e29",
   "metadata": {},
   "source": [
    "\n",
    "### Example 2: Reading an Excel File with Phase Renaming\n",
    "\n",
    "This example imports an Excel file while renaming the phases.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "69c872f1",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Imported 2 cases\n",
      "  case         phase  values  mt\n",
      "0    A      Baseline       2   1\n",
      "1    A      Baseline       3   2\n",
      "2    A  Intervention       5   3\n",
      "3    B      Baseline       1   1\n",
      "4    B      Baseline       4   2\n"
     ]
    }
   ],
   "source": [
    "\n",
    "df = sc.read_scd(\"sample.xlsx\", phase_names=[\"Baseline\", \"Intervention\"])\n",
    "print(df.head())\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f4bd6a59",
   "metadata": {},
   "source": [
    "\n",
    "### Example 3: Sorting Cases Automatically\n",
    "\n",
    "To ensure cases are sorted in the output:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "fd552a4e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Imported 2 cases\n",
      "  case         phase  values  mt\n",
      "0    A      Baseline       2   1\n",
      "1    A      Baseline       3   2\n",
      "2    A  Intervention       5   3\n",
      "3    B      Baseline       1   1\n",
      "4    B      Baseline       4   2\n"
     ]
    }
   ],
   "source": [
    "\n",
    "df = sc.read_scd(\"sample.csv\", sort_cases=True)\n",
    "print(df.head())\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4582ce11",
   "metadata": {},
   "source": [
    "\n",
    "## Exporting Data with `write_scd`\n",
    "\n",
    "The `write_scd` function allows saving SCED data to a CSV or Excel file.\n",
    "\n",
    "### Required Arguments:\n",
    "- `data`: A Pandas DataFrame containing SCED data.\n",
    "- `filename`: Path where the file should be saved.\n",
    "\n",
    "### Optional Arguments:\n",
    "- `sep`: Separator for CSV files (default `\",\"`).\n",
    "- `dec`: Decimal format (default `\".\"`, can be changed to `\",\"` for certain locales).\n",
    "- `file_type`: Manually specify file type (`\"csv\"`, `\"xls\"`, `\"xlsx\"`), if needed.\n",
    "\n",
    "The function prints a message when the file is saved successfully.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eebc8e81",
   "metadata": {},
   "source": [
    "\n",
    "### Example 4: Saving Data to a CSV File\n",
    "\n",
    "To save the dataset as a CSV file:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "593e69a3",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Data successfully saved to sample_output.csv\n"
     ]
    }
   ],
   "source": [
    "\n",
    "sc.write_scd(df, \"sample_output.csv\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a40ab577",
   "metadata": {},
   "source": [
    "\n",
    "### Example 5: Saving Data to an Excel File with a Custom Decimal Format\n",
    "\n",
    "To save the dataset with decimal points replaced by commas:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "ada48d38",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Data successfully saved to sample_output.xlsx\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "D:\\Python Packages\\scia\\scia\\io.py:75: FutureWarning: DataFrame.applymap has been deprecated. Use DataFrame.map instead.\n",
      "  data = data.applymap(lambda x: str(x).replace(\".\", \",\") if isinstance(x, float) else x)\n"
     ]
    }
   ],
   "source": [
    "\n",
    "sc.write_scd(df, \"sample_output.xlsx\", dec=\",\")\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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",
   "version": "3.12.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}