funpack_demonstration_with_outputs.ipynb

{
 "cells": [
  {
   "attachments": {
    "image.png": {
     "image/png": "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"
    }
   },
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![image.png](attachment:image.png)\n",
    "\n",
    "\n",
    "# `funpack`\n",
    "\n",
    "> Paul McCarthy <paul.mccarthy@ndcn.ox.ac.uk> ([WIN@FMRIB](https://www.win.ox.ac.uk/)) \n",
    "\n",
    "`funpack` is a command-line program which you can use to extract data from UK BioBank (and other tabular) data.\n",
    "\n",
    "You can give `funpack` one or more input files (e.g. `.csv`, `.tsv`), and it will merge them together, perform some preprocessing, and produce a single output file. \n",
    "\n",
    "A large number of rules are built into `funpack` which are specific to the UK BioBank data set. But you can control and customise everything that `funpack` does to your data, including which rows and columns to extract, and which cleaning/processing steps to perform on each column.\n",
    "\n",
    "The `funpack` source code is available at https://git.fmrib.ox.ac.uk/fsl/funpack. You can install `funpack` into a Python environment using `pip`:\n",
    "\n",
    "    pip install fmrib-unpack\n",
    "    \n",
    "Get command-line help by typing:\n",
    "\n",
    "    funpack -h\n",
    "    \n",
    "*The examples in this notebook assume that you have installed `funpack` 1.6.0.dev0 or newer.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "funpack 1.6.0.dev0\n"
     ]
    }
   ],
   "source": [
    "funpack -V"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Contents\n",
    "\n",
    "1. [Overview](#Overview)\n",
    "   1. [Import](#1.-Import)\n",
    "   2. [Cleaning](#2.-Cleaning)\n",
    "   3. [Processing](#3.-Processing)\n",
    "   4. [Export](#4.-Export)\n",
    "2. [Examples](#Examples)\n",
    "3. [Import examples](#Import-examples)\n",
    "   1. [Selecting variables (columns)](#Selecting-variables-(columns))\n",
    "      1. [Selecting individual variables](#Selecting-individual-variables)\n",
    "      2. [Selecting variable ranges](#Selecting-variable-ranges)\n",
    "      3. [Selecting variables with a file](#Selecting-variables-with-a-file)\n",
    "      4. [Selecting variables from pre-defined categories](#Selecting-variables-from-pre-defined-categories)\n",
    "   2. [Selecting subjects (rows)](#Selecting-subjects-(rows))\n",
    "      1. [Selecting individual subjects](#Selecting-individual-subjects)\n",
    "      2. [Selecting subject ranges](#Selecting-subject-ranges)\n",
    "      3. [Selecting subjects from a file](#Selecting-subjects-from-a-file)\n",
    "      4. [Selecting subjects by variable value](#Selecting-subjects-by-variable-value)\n",
    "      5. [Excluding subjects](#Excluding-subjects)\n",
    "   3. [Selecting visits](#Selecting-visits)\n",
    "      1. [Evaluating expressions across visits](#Evaluating-expressions-across-visits)\n",
    "   4. [Merging multiple input files](#Merging-multiple-input-files)\n",
    "      1. [Merging by subject](#Merging-by-subject)\n",
    "      2. [Merging by column](#Merging-by-column)\n",
    "      3. [Naive merging](#Merging-by-column)\n",
    "4. [Cleaning examples](#Cleaning-examples)\n",
    "   1. [NA insertion](#NA-insertion)\n",
    "   2. [Variable-specific cleaning functions](#Variable-specific-cleaning-functions)\n",
    "   3. [Categorical recoding](#Categorical-recoding)\n",
    "   4. [Child value replacement](#Child-value-replacement)\n",
    "5. [Processing examples](#Processing-examples)\n",
    "   1. [Sparsity check](#Sparsity-check)\n",
    "   2. [Redundancy check](#Redundancy-check)\n",
    "   3. [Categorical binarisation](#Categorical-binarisation)\n",
    "6. [Custom cleaning, processing and loading - funpack plugins](#Custom-cleaning,-processing-and-loading---funpack-plugins)\n",
    "   1. [Custom cleaning functions](#Custom-cleaning-functions)\n",
    "   2. [Custom processing functions](#Custom-processing-functions)\n",
    "   3. [Custom file loaders](#Custom-file-loaders)\n",
    "7. [Miscellaneous topics](#Miscellaneous-topics)\n",
    "   1. [Non-numeric data](#Non-numeric-data)\n",
    "   2. [Dry run](#Dry-run)\n",
    "   3. [Built-in rules](#Built-in-rules)\n",
    "   4. [Using a configuration file](#Using-a-configuration-file)\n",
    "   5. [Reporting unknown variables](#Reporting-unknown-variables)\n",
    "   6. [Low-memory mode](#Low-memory-mode)   "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Overview\n",
    "\n",
    "`funpack` performs the following steps:\n",
    "\n",
    "## 1. Import\n",
    "\n",
    "\n",
    "   All data files are loaded in, unwanted columns and subjects are dropped, and the data files are merged into a single table (a.k.a. data frame). Multiple files can be merged according to an index column (e.g. subject ID). Or, if the input files contain the same columns/subjects, they can be naively concatenated along rows or columns.\n",
    "\n",
    "\n",
    "## 2. Cleaning\n",
    "\n",
    "\n",
    "The following cleaning steps are applied to each column:\n",
    "\n",
    "1. **NA value replacement:** Specific values for some columns are replaced with NA, for example, variables where a value of `-1` indicates *Do not know*.\n",
    "    \n",
    "    \n",
    "2. **Variable-specific cleaning functions:** Certain columns are re-formatted - for example, the [ICD10](https://en.wikipedia.org/wiki/ICD-10) disease codes can be converted to integer representations.\n",
    "   \n",
    "   \n",
    "3. **Categorical recoding:** Certain categorical columns are re-coded. \n",
    "\n",
    "\n",
    "4. **Child value replacement:** NA values within some columns which are dependent upon other columns may have values inserted based on the values of their parent columns. \n",
    "\n",
    "\n",
    "## 3. Processing\n",
    "\n",
    "\n",
    "During the processing stage, columns may be removed, merged, or expanded into additional columns. For example, a categorical column may be expanded into a set of binary columns, one for each category.\n",
    "\n",
    "A column may also be removed on the basis of being too sparse, or being redundant with respect to another column.\n",
    "\n",
    "\n",
    "## 4. Export\n",
    "\n",
    "\n",
    "The processed data can be saved as a `.csv`, `.tsv`, or `.hdf5` file."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Examples\n",
    "\n",
    "Throughout these examples, we are going to use a few command line options, which you will probably **not** normally want to use:\n",
    " - `-ow` (short for `--overwrite`): This tells `funpack` not to complain if the output file already exists.\n",
    " - `-q` (short for `--quiet`): This tells `funpack` to be quiet. \n",
    " \n",
    "Without the `-q` option, `funpack` can be quite verbose, which can be annoying, but is very useful when things go wrong. A good strategy is to tell `funpack` to produce verbose output using the `--noisy` (`-n` for short) option, and to send all of its output to a log file with the `--log_file` (or `-lf`) option.  For example:\n",
    "\n",
    "    funpack -n -n -n -lf log.txt out.tsv in.tsv \n",
    "    \n",
    "Here's the first example input data set, with UK BioBank-style column names:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t2-0.0\t3-0.0\t4-0.0\t5-0.0\t6-0.0\t7-0.0\t8-0.0\t9-0.0\t10-0.0\n",
      "1\t31\t65\t10\t11\t84\t22\t56\t65\t90\t12\n",
      "2\t56\t52\t52\t42\t89\t35\t3\t65\t50\t67\n",
      "3\t45\t84\t20\t84\t93\t36\t96\t62\t48\t59\n",
      "4\t7\t46\t37\t48\t80\t20\t18\t72\t37\t27\n",
      "5\t8\t86\t51\t68\t80\t84\t11\t28\t69\t10\n",
      "6\t6\t29\t85\t59\t7\t46\t14\t60\t73\t80\n",
      "7\t24\t49\t41\t46\t92\t23\t39\t68\t7\t63\n",
      "8\t80\t92\t97\t30\t92\t83\t98\t36\t6\t23\n",
      "9\t84\t59\t89\t79\t16\t12\t95\t73\t2\t62\n",
      "10\t23\t96\t67\t41\t8\t20\t97\t57\t59\t23\n"
     ]
    }
   ],
   "source": [
    "cat data_01.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The numbers in each column name typically represent: \n",
    "\n",
    "1. The variable ID\n",
    "2. The visit, for variables which were collected at multiple points in time.\n",
    "3. The \"instance\", for multi-valued variables.\n",
    "\n",
    "Note that one **variable** is typically associated with several **columns**, although we're keeping things simple for this first example - there is only one visit for each variable, and there are no mulit-valued variables.\n",
    "\n",
    "> _Most but not all_ variables in the UK BioBank contain data collected at different visits, the times that the participants visited a UK BioBank assessment centre. However there are some variables (e.g. [ICD10 diagnosis codes](https://biobank.ctsu.ox.ac.uk/crystal/field.cgi?id=41202)) for which this is not the case."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Import examples\n",
    "\n",
    "## Selecting variables (columns)\n",
    "\n",
    "You can specify which variables you want to load in the following ways, using the `--variable` (`-v` for short) and `--category` (`-c` for short) command line options:\n",
    "\n",
    " * By variable ID\n",
    " * By variable ranges\n",
    " * By a text file which contains the IDs you want to keep.\n",
    " * By pre-defined variable categories\n",
    " * By column name\n",
    " \n",
    "### Selecting individual variables\n",
    "\n",
    "Simply provide the IDs of the variables you want to extract:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t5-0.0\n",
      "1\t31\t84.0\n",
      "2\t56\t89.0\n",
      "3\t45\t93.0\n",
      "4\t7\t80.0\n",
      "5\t8\t80.0\n",
      "6\t6\t7.0\n",
      "7\t24\t92.0\n",
      "8\t80\t92.0\n",
      "9\t84\t16.0\n",
      "10\t23\t8.0\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -v 1 -v 5 out.tsv data_01.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Selecting variable ranges\n",
    "\n",
    "The `--variable`/`-v` option accepts MATLAB-style ranges of the form `start:step:stop` (where the `stop` is inclusive):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t4-0.0\t7-0.0\t10-0.0\n",
      "1\t31\t11.0\t56\t12\n",
      "2\t56\t42.0\t3\t67\n",
      "3\t45\t84.0\t96\t59\n",
      "4\t7\t48.0\t18\t27\n",
      "5\t8\t68.0\t11\t10\n",
      "6\t6\t59.0\t14\t80\n",
      "7\t24\t46.0\t39\t63\n",
      "8\t80\t30.0\t98\t23\n",
      "9\t84\t79.0\t95\t62\n",
      "10\t23\t41.0\t97\t23\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -v 1:3:10 out.tsv data_01.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Selecting variables with a file\n",
    "If your variables of interest are listed in a plain-text file, you can simply pass that file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t6-0.0\t9-0.0\n",
      "1\t31\t22.0\t90\n",
      "2\t56\t35.0\t50\n",
      "3\t45\t36.0\t48\n",
      "4\t7\t20.0\t37\n",
      "5\t8\t84.0\t69\n",
      "6\t6\t46.0\t73\n",
      "7\t24\t23.0\t7\n",
      "8\t80\t83.0\t6\n",
      "9\t84\t12.0\t2\n",
      "10\t23\t20.0\t59\n"
     ]
    }
   ],
   "source": [
    "echo -e \"1\\n6\\n9\" > vars.txt\n",
    "funpack -q -ow -v vars.txt out.tsv data_01.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Selecting variables from pre-defined categories\n",
    "\n",
    "Some UK BioBank-specific categories are baked into `funpack`, but you can also define your own categories - you just need to create a `.tsv` file, and pass it to `funpack` via the `--category_file` (`-cf` for short):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ID\tCategory\tVariables\n",
      "1\tCool variables\t1:5,7\n",
      "2\tUncool variables\t6,8:10\n"
     ]
    }
   ],
   "source": [
    "echo -e \"ID\\tCategory\\tVariables\"      > custom_categories.tsv\n",
    "echo -e \"1\\tCool variables\\t1:5,7\"    >> custom_categories.tsv\n",
    "echo -e \"2\\tUncool variables\\t6,8:10\" >> custom_categories.tsv\n",
    "cat custom_categories.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use the `--category` (`-c` for short) to select categories to output. You can refer to categories by their ID:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t2-0.0\t3-0.0\t4-0.0\t5-0.0\t7-0.0\n",
      "1\t31\t65\t10.0\t11.0\t84.0\t56\n",
      "2\t56\t52\t52.0\t42.0\t89.0\t3\n",
      "3\t45\t84\t20.0\t84.0\t93.0\t96\n",
      "4\t7\t46\t37.0\t48.0\t80.0\t18\n",
      "5\t8\t86\t51.0\t68.0\t80.0\t11\n",
      "6\t6\t29\t85.0\t59.0\t7.0\t14\n",
      "7\t24\t49\t41.0\t46.0\t92.0\t39\n",
      "8\t80\t92\t97.0\t30.0\t92.0\t98\n",
      "9\t84\t59\t89.0\t79.0\t16.0\t95\n",
      "10\t23\t96\t67.0\t41.0\t8.0\t97\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -cf custom_categories.tsv -c 1 out.tsv data_01.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or by name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t6-0.0\t8-0.0\t9-0.0\t10-0.0\n",
      "1\t22.0\t65\t90\t12\n",
      "2\t35.0\t65\t50\t67\n",
      "3\t36.0\t62\t48\t59\n",
      "4\t20.0\t72\t37\t27\n",
      "5\t84.0\t28\t69\t10\n",
      "6\t46.0\t60\t73\t80\n",
      "7\t23.0\t68\t7\t63\n",
      "8\t83.0\t36\t6\t23\n",
      "9\t12.0\t73\t2\t62\n",
      "10\t20.0\t57\t59\t23\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -cf custom_categories.tsv -c uncool out.tsv data_01.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Selecting column names\n",
    "\n",
    "If you are working with data that has non-UK BioBank style column names, you can use the `--column` (`-co` for short) to select individual columns by their name, rather than the variable with which they are associated. The `--column` option accepts full column names, and also shell-style wildcard patterns:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t4-0.0\t10-0.0\n",
      "1\t11.0\t12\n",
      "2\t42.0\t67\n",
      "3\t84.0\t59\n",
      "4\t48.0\t27\n",
      "5\t68.0\t10\n",
      "6\t59.0\t80\n",
      "7\t46.0\t63\n",
      "8\t30.0\t23\n",
      "9\t79.0\t62\n",
      "10\t41.0\t23\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -co 4-0.0 -co \"??-0.0\" out.tsv data_01.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Selecting subjects (rows)\n",
    "\n",
    "`funpack` assumes that the first column in every input file is a subject ID. You can specify which subjects you want to load via the `--subject` (`-s` for short) option. You can specify subjects in the same way that you specified variables above, and also:\n",
    "\n",
    " * By specifying a conditional expression on variable values - only subjects for which the expression evaluates to true will be imported\n",
    " * By specifying subjects to exclude\n",
    " \n",
    "### Selecting individual subjects"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t2-0.0\t3-0.0\t4-0.0\t5-0.0\t6-0.0\t7-0.0\t8-0.0\t9-0.0\t10-0.0\n",
      "1\t31\t65\t10.0\t11.0\t84.0\t22.0\t56\t65\t90\t12\n",
      "3\t45\t84\t20.0\t84.0\t93.0\t36.0\t96\t62\t48\t59\n",
      "5\t8\t86\t51.0\t68.0\t80.0\t84.0\t11\t28\t69\t10\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -s 1 -s 3 -s 5 out.tsv data_01.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Selecting subject ranges"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t2-0.0\t3-0.0\t4-0.0\t5-0.0\t6-0.0\t7-0.0\t8-0.0\t9-0.0\t10-0.0\n",
      "2\t56\t52\t52.0\t42.0\t89.0\t35.0\t3\t65\t50\t67\n",
      "4\t7\t46\t37.0\t48.0\t80.0\t20.0\t18\t72\t37\t27\n",
      "6\t6\t29\t85.0\t59.0\t7.0\t46.0\t14\t60\t73\t80\n",
      "8\t80\t92\t97.0\t30.0\t92.0\t83.0\t98\t36\t6\t23\n",
      "10\t23\t96\t67.0\t41.0\t8.0\t20.0\t97\t57\t59\t23\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -s 2:2:10 out.tsv data_01.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Selecting subjects from a file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t2-0.0\t3-0.0\t4-0.0\t5-0.0\t6-0.0\t7-0.0\t8-0.0\t9-0.0\t10-0.0\n",
      "5\t8\t86\t51.0\t68.0\t80.0\t84.0\t11\t28\t69\t10\n",
      "6\t6\t29\t85.0\t59.0\t7.0\t46.0\t14\t60\t73\t80\n",
      "7\t24\t49\t41.0\t46.0\t92.0\t23.0\t39\t68\t7\t63\n",
      "8\t80\t92\t97.0\t30.0\t92.0\t83.0\t98\t36\t6\t23\n",
      "9\t84\t59\t89.0\t79.0\t16.0\t12.0\t95\t73\t2\t62\n",
      "10\t23\t96\t67.0\t41.0\t8.0\t20.0\t97\t57\t59\t23\n"
     ]
    }
   ],
   "source": [
    "echo -e \"5\\n6\\n7\\n8\\n9\\n10\" > subjects.txt\n",
    "funpack -q -ow -s subjects.txt out.tsv data_01.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Selecting subjects by variable value\n",
    "\n",
    "The `--subject` option accepts *variable expressions* - you can write an expression performing numerical comparisons on variables (denoted with a leading `v`) and combine these expressions using boolean algebra. Only subjects for which the expression evaluates to true will be imported. For example, to only import subjects where variable 1 is greater than 10, and variable 2 is less than 70, you can type:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t2-0.0\t3-0.0\t4-0.0\t5-0.0\t6-0.0\t7-0.0\t8-0.0\t9-0.0\t10-0.0\n",
      "1\t31\t65\t10.0\t11.0\t84.0\t22.0\t56\t65\t90\t12\n",
      "2\t56\t52\t52.0\t42.0\t89.0\t35.0\t3\t65\t50\t67\n",
      "7\t24\t49\t41.0\t46.0\t92.0\t23.0\t39\t68\t7\t63\n",
      "9\t84\t59\t89.0\t79.0\t16.0\t12.0\t95\t73\t2\t62\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -sp -s \"v1 > 10 && v2 < 70\" out.tsv data_01.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following symbols can be used in variable expressions:\n",
    "\n",
    "| Symbol                    | Meaning                         |\n",
    "|---------------------------|---------------------------------|\n",
    "| `==`                      | equal to                        |\n",
    "| `!=`                      | not equal to                    |\n",
    "| `>`                       | greater than                    |\n",
    "| `>=`                      | greater than or equal to        |\n",
    "| `<`                       | less than                       |\n",
    "| `<=`                      | less than or equal to           |\n",
    "| `na`                      | N/A                             |\n",
    "| `&&`                      | logical and                     |\n",
    "| <code>&#x7c;&#x7c;</code> | logical or                      |\n",
    "| `~`                       | logical not                     |\n",
    "| `contains`                | Contains sub-string             |\n",
    "| `all`                     | all columns must meet condition |\n",
    "| `any`                     | any column must meet condition  |\n",
    "| `()`                      | to denote precedence            |\n",
    "\n",
    "Non-numeric (i.e. string) variables can be used in these expressions in conjunction with the `==`, `!=`, and `contains` operators. An example of such an expression is given in the section on [non-numeric data](#Non-numeric-data), below.\n",
    "\n",
    "The `all` and `any` symbols allow you to control how an expression is evaluated across multiple columns which are associated with one variable (e.g. separate columns for each visit). We will give an example of this in the section on [selecting visits](#Selecting-visits), below.\n",
    "\n",
    "### Excluding subjects\n",
    "\n",
    "The `--exclude` (`-ex` for short) option allows you to exclude subjects - it accepts individual IDs, an ID range, or a file containing IDs. The `--exclude`/`-ex` option takes precedence over the `--subject`/`-s` option:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t2-0.0\t3-0.0\t4-0.0\t5-0.0\t6-0.0\t7-0.0\t8-0.0\t9-0.0\t10-0.0\n",
      "1\t31\t65\t10.0\t11.0\t84.0\t22.0\t56\t65\t90\t12\n",
      "2\t56\t52\t52.0\t42.0\t89.0\t35.0\t3\t65\t50\t67\n",
      "3\t45\t84\t20.0\t84.0\t93.0\t36.0\t96\t62\t48\t59\n",
      "4\t7\t46\t37.0\t48.0\t80.0\t20.0\t18\t72\t37\t27\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -s 1:8 -ex 5:10 out.tsv data_01.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Selecting visits"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Many variables in the UK BioBank data contain observations at multiple points in time, or visits. `funpack` allows you to specify which visits you are interested in. Here is an example data set with variables that have data for multiple visits (remember that the second number in the column names denotes the visit):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t2-0.0\t2-1.0\t2-2.0\t3-0.0\t3-1.0\t4-0.0\t5-0.0\n",
      "1\t86\t76\t82\t75\t34\t99\t50\t5\n",
      "2\t20\t25\t40\t44\t30\t57\t54\t44\n",
      "3\t85\t2\t48\t42\t23\t77\t84\t27\n",
      "4\t23\t30\t18\t97\t44\t55\t97\t20\n",
      "5\t83\t45\t76\t51\t18\t64\t8\t33\n"
     ]
    }
   ],
   "source": [
    "cat data_02.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can use the `--visit` (`-vi` for short) option to get just the last visit for each variable:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t2-2.0\t3-1.0\t4-0.0\t5-0.0\n",
      "1\t86\t75\t99.0\t50.0\t5.0\n",
      "2\t20\t44\t57.0\t54.0\t44.0\n",
      "3\t85\t42\t77.0\t84.0\t27.0\n",
      "4\t23\t97\t55.0\t97.0\t20.0\n",
      "5\t83\t51\t64.0\t8.0\t33.0\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -vi last out.tsv data_02.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also specify which visit you want by its number:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t2-1.0\t3-1.0\n",
      "1\t82\t99.0\n",
      "2\t40\t57.0\n",
      "3\t48\t77.0\n",
      "4\t18\t55.0\n",
      "5\t76\t64.0\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -vi 1 out.tsv data_02.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> Variables which are not associated with specific visits (e.g. [ICD10 diagnosis codes](https://biobank.ctsu.ox.ac.uk/crystal/field.cgi?id=41202)) will not be affected by the `-vi` option."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Evaluating expressions across visits\n",
    "\n",
    "The variable expressions described above in the section on [selecting subjects](#Selecting-subjects-by-variable-value) will be applied to all of the columns associated with a variable. By default, an expression will evaluate to true where the values in _any_ column asssociated with the variable evaluate to true. For example, we can extract the data for subjects where the values of any column of variable 2 were less than 50: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t2-0.0\t2-1.0\t2-2.0\n",
      "2\t25\t40\t44\n",
      "3\t2\t48\t42\n",
      "4\t30\t18\t97\n",
      "5\t45\t76\t51\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -v 2 -s 'v2 < 50' out.tsv data_02.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can use the `any` and `all` operators to control how an expression is evaluated across the columns of a variable. For example, we may only be interested in subjects for whom all columns of variable 2 were greater than 50:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t2-0.0\t2-1.0\t2-2.0\n",
      "2\t25\t40\t44\n",
      "3\t2\t48\t42\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -v 2 -s 'all(v2 < 50)' out.tsv data_02.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can use `any` and `all` in expressions involving multiple variables:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t2-0.0\t2-1.0\t2-2.0\t3-0.0\t3-1.0\n",
      "4\t30\t18\t97\t44.0\t55.0\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -v 2,3 -s 'any(v2 < 50) && all(v3 >= 40)' out.tsv data_02.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Merging multiple input files\n",
    "\n",
    "If your data is split across multiple files, you can specify how `funpack` should merge them together. \n",
    "\n",
    "### Merging by subject\n",
    "\n",
    "For example, let's say we have these two input files (shown side-by-side):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t2-0.0\t3-0.0\t \teid\t4-0.0\t5-0.0\t6-0.0\n",
      "1\t89\t47\t26\t\t2\t19\t17\t62\n",
      "2\t94\t37\t70\t\t3\t41\t12\t7\n",
      "3\t63\t5\t97\t\t4\t8\t86\t9\n",
      "4\t98\t97\t91\t\t5\t7\t65\t71\n",
      "5\t37\t10\t11\t\t6\t3\t23\t15\n"
     ]
    }
   ],
   "source": [
    "echo \" \" | paste data_03.tsv - data_04.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that each file contains different variables, and different, but overlapping, subjects. By default, when you pass these files to `funpack`, it will output the intersection of the two files (more formally known as an *inner join*), i.e. subjects which are present in both files:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t2-0.0\t3-0.0\t4-0.0\t5-0.0\t6-0.0\n",
      "2\t94\t37\t70.0\t19.0\t17.0\t62.0\n",
      "3\t63\t5\t97.0\t41.0\t12.0\t7.0\n",
      "4\t98\t97\t91.0\t8.0\t86.0\t9.0\n",
      "5\t37\t10\t11.0\t7.0\t65.0\t71.0\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow out.tsv data_03.tsv data_04.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want to keep all subjects, you can instruct `funpack` to output the union (a.k.a. *outer join*) via the `--merge_strategy` (`-ms` for short) option:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t2-0.0\t3-0.0\t4-0.0\t5-0.0\t6-0.0\n",
      "1\t89.0\t47.0\t26.0\t\t\t\n",
      "2\t94.0\t37.0\t70.0\t19.0\t17.0\t62.0\n",
      "3\t63.0\t5.0\t97.0\t41.0\t12.0\t7.0\n",
      "4\t98.0\t97.0\t91.0\t8.0\t86.0\t9.0\n",
      "5\t37.0\t10.0\t11.0\t7.0\t65.0\t71.0\n",
      "6\t\t\t\t3.0\t23.0\t15.0\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -ms outer out.tsv data_03.tsv data_04.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Merging by column\n",
    "\n",
    "Your data may be organised in a different way. For example, these next two files contain different groups of subjects, but overlapping columns:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t1-0.0\t2-0.0\t3-0.0\t4-0.0\t5-0.0\t \teid\t2-0.0\t3-0.0\t4-0.0\t5-0.0\t6-0.0\n",
      "1\t69\t80\t70\t60\t42\t\t4\t17\t36\t56\t90\t12\n",
      "2\t64\t15\t82\t99\t67\t\t5\t63\t16\t87\t57\t63\n",
      "3\t33\t67\t58\t96\t26\t\t6\t43\t19\t84\t53\t63\n"
     ]
    }
   ],
   "source": [
    "echo \" \" | paste data_05.tsv - data_06.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case, we need to tell `funpack` to merge along the row axis, rather than along the column axis. We can do this with the `--merge_axis` (`-ma` for short) option:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "eid\t2-0.0\t3-0.0\t4-0.0\t5-0.0\n",
      "1\t80\t70.0\t60.0\t42.0\n",
      "2\t15\t82.0\t99.0\t67.0\n",
      "3\t67\t58.0\t96.0\t26.0\n",
      "4\t17\t36.0\t56.0\t90.0\n",
      "5\t63\t16.0\t87.0\t57.0\n",
      "6\t43\t19.0\t84.0\t53.0\n"
     ]
    }
   ],
   "source": [
    "funpack -q -ow -ma rows out.tsv data_05.tsv data_06.tsv\n",
    "cat out.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Again, if we want to retain all columns, we can tell `funpack` to perform an outer join with the `-ms` option:"