docs/source/adding.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "3917dbcd",
   "metadata": {},
   "source": [
    "# Adding or subtracting datasets"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8b38a60b",
   "metadata": {},
   "source": [
    "Often you might want to subtract datasets from each other. This is potentially made complicated as datasets can take different forms. For example, you might want to subtract a dataset which contains annual means from a dataset that contains monthly values. In this case you want to subtract the annual mean from the relevant month in each year. To deal with this problem, nctoolkit offers the methods `add`, `subtract`, `multiply` and `divide`, which from nctoolkit v0.4.0 onwards can automatically work out the relevant method required for the dataset given. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "28916421",
   "metadata": {},
   "source": [
    "Let's illustrate this using a dataset of [monthly sea surface temperature](https://psl.noaa.gov/data/gridded/data.cobe2.html) from 1850 to the present day. In the snippet below, we load the data into a dataset. Then we generate a second which is the annual mean temperature and subtract it from the original dataset:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "79cb05eb",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "nctoolkit is using Climate Data Operators version 1.9.10\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Subtracting a yearly time series\n"
     ]
    }
   ],
   "source": [
    "import nctoolkit as nc\n",
    "ds1 = nc.open_data(\"sst.mon.mean.nc\")\n",
    "ds2 = nc.open_data(\"sst.mon.mean.nc\")\n",
    "ds2.tmean(\"year\")\n",
    "ds1.subtract(ds2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1ce228cd",
   "metadata": {},
   "source": [
    "You can see that nctoolkit has stated that it has subtracted a yearly time series.\n",
    "\n",
    "If we wanted to subtract the monthly mean, we would do this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "2e3c3842",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Subtracting a monthly time series\n"
     ]
    }
   ],
   "source": [
    "import nctoolkit as nc\n",
    "ds1 = nc.open_data(\"sst.mon.mean.nc\")\n",
    "ds2 = nc.open_data(\"sst.mon.mean.nc\")\n",
    "ds2.tmean(\"month\")\n",
    "ds1.subtract(ds2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ec972711",
   "metadata": {},
   "source": [
    "Similarly, if you want to subtract a dataset with only one time step, things will work as expected:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "c7eaeb4f",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Subtracting a single time step time series\n"
     ]
    }
   ],
   "source": [
    "import nctoolkit as nc\n",
    "ds1 = nc.open_data(\"sst.mon.mean.nc\")\n",
    "ds2 = nc.open_data(\"sst.mon.mean.nc\")\n",
    "ds2.tmean()\n",
    "ds1.subtract(ds2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2b44a4ca",
   "metadata": {},
   "source": [
    "Note: these methods require consistency between the datasets. For example, in the code below we are subtracting the annual means from the monthly values, but we have removed the year 2000. So running this code will throw an error."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c1a12418",
   "metadata": {},
   "outputs": [],
   "source": [
    "import nctoolkit as nc\n",
    "ds1 = nc.open_data(\"sst.mon.mean.nc\")\n",
    "ds2 = nc.open_data(\"sst.mon.mean.nc\")\n",
    "ds2.drop(year = 2000)\n",
    "ds2.tmean(\"year\")\n",
    "ds1.subtract(ds2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3f222624",
   "metadata": {},
   "source": [
    "## Automatic methods available\n",
    "\n",
    "At present, the `add`, `subtract` `divide` and `multiply` methods will be automatically able to handle daily, monthly and yearly dataset. At present, they will not be able to handle hourly datasets or anything finer. \n",
    "\n",
    "However, it will automatically be able to deal `add`, `subtract`, `divide` or `multiply` files that either have single time steps or have identical time steps. In this case time step comparisons are unambiguous. "
   ]
  }
 ],
 "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",
   "version": "3.9.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}