{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "b48d9725",
   "metadata": {},
   "source": [
    "# Custom filenames\n",
    "\n",
    "xemc3 allows to customise the file names used for reading and writing of the files.\n",
    "\n",
    "The default profile is called `default`.\n",
    "\n",
    "## Using a specific version\n",
    "\n",
    "This can be used to use the naming and normalisation scheeme from a specific version:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d86ad1bd",
   "metadata": {},
   "outputs": [],
   "source": [
    "import xemc3\n",
    "\n",
    "with xemc3.config.set(filenames=\"v0.2.4\"):\n",
    "    # Now you can load using the 0.2.4 version-compatibility mode\n",
    "    # xemc3.load.all('.')\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5c8f3fc3",
   "metadata": {},
   "source": [
    "## Ways to customise\n",
    "\n",
    "There are several ways to customise.\n",
    "\n",
    "### Extending existing profiles\n",
    "\n",
    "After reading the configuration provided by xemc3, xemc3 looks for a user provided file, in `~/.local/xemc3/<name>.yaml` where `<name>` is e.g. `default`.\n",
    "\n",
    "### Extending all profiles\n",
    "\n",
    "xemc3 also reads the file `~/.local/xemc3/files.yaml`. This file has lower priority then user provided `<names>.yaml`, but higher than xemc3 provided `<name>.yaml`. Thus it can be used to override things by xemc3.\n",
    "\n",
    "### Custom profiles\n",
    "\n",
    "Similar to extending existing profiles, it is possible to create on profiles. Just like in the case of extending a profile, `~/.local/xemc3/<name>.yaml` is read. In that case all needed files need to be set.\n",
    "\n",
    "## Syntax\n",
    "\n",
    "The file is using the yaml syntax. Note that while yaml does not is specified to preserve order, xemc3 requires the order for the `vars` key, as that specifies in which order the blocks are in the file. While all tested yaml reader preserve the order when reading, care has to be taken if the file is written from python.\n",
    "\n",
    "See `xemc3/data/default.yaml` for an example file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "90c85f5b",
   "metadata": {},
   "outputs": [],
   "source": [
    "with open(xemc3.__file__.rsplit(\"/\", 1)[0] + \"/data/default.yaml\") as yaml:\n",
    "    print(yaml.read())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "476b7c67",
   "metadata": {},
   "source": [
    "The first key is the file name. The type of the file is defined by `type`, and defaults to `mapped` if not given.\n",
    "\n",
    "The `var` option must always be given. It defines what variables are to be found in the files.\n",
    "As some files contain a variable number of arguments, the last variable may contain `%d`, in which case the remaining entries are enumerated starting from 0, with `%d` replaced by the number.\n",
    "Options for the variables are:\n",
    " * `scale` - by which the variable is multiplied on reading\n",
    " * `units` - The units of the quantity (after scaling)\n",
    " * `long_name` - a more descriptive name for the variable\n",
    " * other dictionary items are added to the read variable\n",
    "\n",
    "Given on the type several options are available.\n",
    "\n",
    " * `mapped`:\n",
    "   * `kinetic` : bool, whether the file contains values outside of the mapped region\n",
    "   * `unmapped` : bool, whether there is one number for each geometric cell\n",
    "   * `skip_first` : int or list of int, how many lines to skip before each data block\n",
    "   * `dtype` : str, The data type, defaults to float\n",
    " * `mapping` :\n",
    " * `full` :\n",
    " * `plates_mag` : \n",
    " * `geom` : \n",
    " * `info` :\n",
    "   * `fmt` : the formatting of each line\n",
    "   * `length` : length for the `iteration` dimension\n",
    " * `surfaces` :\n",
    " * `target_flux` :\n",
    " * `raw` :\n",
    " * `depo`"
   ]
  }
 ],
 "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.10.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}