{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# A tool for referencing _PyMICE_\n",
    "\n",
    "When importing the _PyMICE library_, you are prompted to reference it in any published research."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pymice as pm"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The `Citation` class"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To facilitate the referencing, the library provides a class `Citation`. The class may be especially useful in publications/reports written according to the [Literate Programming paradigm](https://en.wikipedia.org/wiki/Literate_programming) (e.g. with [Pweave](http://mpastell.com/pweave/) tool).\n",
    "\n",
    "Objects of the class may be converted both to `unicode` and `str` (UTF-8 encoded) strings which are the recommended in-text reference of the library."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "citation = pm.Citation()\n",
    "print unicode(citation)\n",
    "print str(citation)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you may see, the current version of the library has been referenced.\n",
    "\n",
    "The `citation` object provides also items to be included in the _Bibliography_ section as its attributes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "print citation.PAPER\n",
    "print\n",
    "print citation.SOFTWARE"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To cite PyMICE not in the suggested format you may use `.CITE_PAPER` and `.CITE_SOFTWARE` properties."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print citation.CITE_PAPER\n",
    "print\n",
    "print citation.CITE_SOFTWARE"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The new style of _Python_ string formatting\n",
    "\n",
    "With [the new style of Python string formatting](https://pyformat.info/) (`.format()`), the object may be easily used to automatically generate the reference."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "PUBLICATION_TEMPLATE = u\"\"\"With the new Python string formatting API (.format()), the object may be easily used to automatically generate the reference.\n",
    "\n",
    "Methods\n",
    "\n",
    "The following tutorial has been executed with {reference}.\n",
    "\n",
    "Bibliography\n",
    "\n",
    "{reference.PAPER}\n",
    "\n",
    "{reference.SOFTWARE}\n",
    "\"\"\"\n",
    "\n",
    "print PUBLICATION_TEMPLATE.format(reference=pm.Citation())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Customizing the `Citation` object\n",
    "\n",
    "Sometimes it is necessary to comply with a certain reference style (like Vancouver or APA6). Objects of the `Citation` class may be easily customised to fit such needs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "PUBLICATION_TEMPLATE = u\"\"\"\\n\\n{reference} facilitates referencing in {style} style.\n",
    "\n",
    "Bibliography:\n",
    "\n",
    "{reference.PAPER}\n",
    "\n",
    "{reference.SOFTWARE}\\n\"\"\"\n",
    "\n",
    "for style in ['Vancouver', 'APA6']:\n",
    "    print PUBLICATION_TEMPLATE.format(style=style,\n",
    "                                      reference=pm.Citation(style=style))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As most publications is written with some markup system, the `Citation` class supports different markups as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for name, symbol in [('Plain', 'txt'),\n",
    "                     ('Markdown', 'md'),\n",
    "                     ('reStructuredText', 'rst'),\n",
    "                     ('HTML', 'html'),\n",
    "                     ('LaTeX', 'latex'),]:\n",
    "    print '{} ({})'.format(name, symbol)\n",
    "    print\n",
    "    print pm.Citation(style='APA6', markdown=symbol).PAPER\n",
    "    print\n",
    "    print"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `Citation` class supports also export of BibTeX entries."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print pm.Citation(style='BibTeX').SOFTWARE"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In some cases (e.g. in case of BibTeX, LaTeX or Vancouver style) \"keys\" automatically assigned to bibliography items may be improper. The `Citation` class provides mechanism to assign custom \"keys\" to the items."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "PUBLICATION_TEMPLATE = u\"\"\"[...]\n",
    "\n",
    "{reference} was used to run this tutorial.\n",
    "\n",
    "[...]\n",
    "\n",
    "Bibliography:\n",
    "\n",
    "[...]\n",
    "\n",
    "{reference.PAPER}\n",
    "\n",
    "[...]\n",
    "\n",
    "{reference.SOFTWARE}\n",
    "\n",
    "[...]\"\"\"\n",
    "\n",
    "print PUBLICATION_TEMPLATE.format(reference=pm.Citation(style='Vancouver',\n",
    "                                                        paperKey='42',\n",
    "                                                        softwareKey='44'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sometimes it may be necessary to reference another version of PyMICE than currently used. The `version` parameter of the `Citation` class enables referencing a custom version."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "PUBLICATION_TEMPLATE = u\"\"\"Our publication introducing the PyMICE library ({reference.CITE_PAPER}) has been compiled with PyMICE v. {version} ({reference.CITE_SOFTWARE})\n",
    "\n",
    "Bibliography:\n",
    "\n",
    "{reference.PAPER}\n",
    "\n",
    "{reference.SOFTWARE}\n",
    "\"\"\"\n",
    "\n",
    "print PUBLICATION_TEMPLATE.format(version='1.1.0',\n",
    "                                  reference=pm.Citation(version='1.1.0'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overriding the constructor parameters\n",
    "\n",
    "If you need to generate a reference using different style, PyMICE version or markdown than set in the object constructor, you do not have to create a new object. A call to the methods: `.cite()`, `.citePaper()`, `.citeSoftware()`, `.referencePaper()` or `.referenceSoftware()` with optional parameters `style`, `markdown` and `version` returns a customised reference."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "reference = pm.Citation()\n",
    "print reference.cite(version='0.2.3')\n",
    "print\n",
    "print reference.citePaper(markdown='LaTeX')\n",
    "print\n",
    "print reference.citeSoftware(style='APA6')\n",
    "print\n",
    "print reference.referencePaper(style='Vancouver', markdown='HTML')\n",
    "print\n",
    "print reference.referenceSoftware(style='BibTeX', version='1.0.0')"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}