{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Data types\n",
    "\n",
    "In most cases, the data type (`dtype`) of a [Variable](../generated/classes/scipp.Variable.rst) is derived from the data.\n",
    "For instance when passing a [NumPy array](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) to Scipp, Scipp will use the `dtype` provided by NumPy:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import scipp as sc\n",
    "\n",
    "var = sc.Variable(dims=['x'], values=np.arange(4.0))\n",
    "var.dtype"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "var = sc.Variable(dims=['x'], values=np.arange(4))\n",
    "var.dtype"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `dtype` may also be specified using a keyword argument to `sc.Variable` and most [creation functions](./creation-functions.rst#creation-functions).\n",
    "It is possible to use Scipp's own [scipp.DType](../generated/classes/scipp.DType.rst), [numpy.dtype](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html), or (where a NumPy equivalent exists) a string:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "var = sc.zeros(dims=['x'], shape=[2], dtype=sc.DType.float32)\n",
    "var.dtype"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "var = sc.zeros(dims=['x'], shape=[2], dtype=np.dtype(np.float32))\n",
    "var.dtype"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "var = sc.zeros(dims=['x'], shape=[2], dtype='float32')\n",
    "var.dtype"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Scipp supports common dtypes like\n",
    "\n",
    "- `float32`, `float64`\n",
    "- `int32`, `int64`\n",
    "- `bool`\n",
    "- `string`\n",
    "- `datetime64`\n",
    "\n",
    "It is also possible to nest Variables, DataArrays, or Datasets inside of Variables. But there is only limited interoperability with NumPy in those cases."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "var = sc.scalar(sc.zeros(dims=['x'], shape=[2], dtype='float64'))\n",
    "var"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can find a full list in the docs of the [scipp.DType](../generated/classes/scipp.DType.rst) class."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Dates and Times\n",
    "\n",
    "Scipp has a special dtype for time-points, `sc.DType.datetime64`.\n",
    "Variables can be constructed using [scipp.datetime](../generated/functions/scipp.datetime.rst) and [scipp.datetimes](../generated/functions/scipp.datetimes.rst):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.datetime('2022-01-10T14:31:21')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.datetimes(dims=['t'], values=['2022-01-10T14:31:21', '2022-01-11T11:09:05'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Datetimes can also be constructed from integers which encode the time since the Scipp epoch which is equal to the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time).\n",
    "The `unit` argument determines what time scale the integers represent."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.datetime(0, unit='s')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.datetimes(dims=['t'], values=[123456789, 345678912], unit='us')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As a shortand, [scipp.epoch](../generated/functions/scipp.epoch.rst) can be used to get a scalar containing Scipp's epoch:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.epoch(unit='s')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The other creation functions also work with datetimes by specifying the `datetime64` dtype explicitly.\n",
    "However, only integer inputs and Numpy arrays of [numpy.datetime64](https://numpy.org/doc/stable/reference/arrays.datetime.html#basic-datetimes) can be used in those cases."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.scalar(value=24, unit='h', dtype=sc.DType.datetime64)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "var = sc.scalar(value=681794055, unit=sc.units.s, dtype='datetime64')\n",
    "var"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Scipp's datetime variables can interoperate with [numpy.datetime64](https://numpy.org/doc/stable/reference/arrays.datetime.html#basic-datetimes) and arrays thereof:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "var.value"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.scalar(value=np.datetime64('now'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or more succinctly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.datetime('now')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that `'now'` implies unit `s` even though we did not specify it.\n",
    "The unit was deduced from the `numpy.datetime64` object which encodes a unit of its own."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Operations\n",
    "\n",
    "Variables containing datetimes only support a limited set of operations as it makes no sense to, for instance, add two time points.\n",
    "In contrast to NumPy, Scipp does not have a separate type for time differences.\n",
    "Those are simply encoded by integer Variables with a temporal unit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = sc.datetime('2021-03-14T00:00:00', unit='ms')\n",
    "b = sc.datetime('2000-01-01T00:00:00', unit='ms')\n",
    "a - b"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "raises-exception"
    ]
   },
   "outputs": [],
   "source": [
    "a + b"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a + sc.scalar(value=123, unit='ms')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Time zones\n",
    "\n",
    "Scipp does not support manual handling of time zones.\n",
    "All datetime objects are assumed to be in UTC.\n",
    "Scipp does not look at your local time zone, thus the following will always produce 12:30 on 2021-03-09 UTC no matter where you are when you run this code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.scalar(value=np.datetime64('2021-09-03T12:30:00'))"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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": 4
}