The Kitchin Research Group

Consider this bibtex entry from http://pubs.acs.org/action/showCitFormats?doi=10.1021%2Fie500588j .

@article{doi:10.1021/ie500588j,
author = {Okada, Tomohiko and Ozono, Shoya and Okamoto, Masami and Takeda, Yohei and Minamisawa, Hikari M. and Haeiwa, Tetsuji and Sakai, Toshio and Mishima, Shozi},
title = {Magnetic Rattle-Type Core–Shell Particles Containing Iron Compounds with Acid Tolerance by Dense Silica},
journal = {Industrial & Engineering Chemistry Research},
volume = {0},
number = {0},
pages = {null},
year = {0},
doi = {10.1021/ie500588j},

URL = {http://pubs.acs.org/doi/abs/10.1021/ie500588j},
eprint = {http://pubs.acs.org/doi/pdf/10.1021/ie500588j}
}

On the surface it looks fine, but there are the following issues with it:

1. The bibtex key is hard to remember. I like systematically named keys.
2. There is a bare & in the journal title, which is not legal in LaTeX.
3. There is no year entry, even though it is a 2014 entry. The pages, volume, and number are also problematic, but this is an ASAP article and the reference does not have those yet.
4. It is hard to see, but the dash between core and shell is a non-ascii character, which can cause problems in LaTeX.
5. The entry is not very nicely aligned or indented.

You can fix these problems by putting your cursor on the bibtex entry, and typing M-x org-ref-clean-bibtex-entry. This will fix the bibtex key to a standard form, align and indent the entry, escape the & so it is legal syntax, prompt you for a year, and show you the non-ascii characters so you can replace them. The resulting, nicely formatted entry is shown below.

@article{okada-2014-magnet-rattl,
  author =	 {Okada, Tomohiko and Ozono, Shoya and Okamoto, Masami
                  and Takeda, Yohei and Minamisawa, Hikari M. and
                  Haeiwa, Tetsuji and Sakai, Toshio and Mishima,
                  Shozi},
  title =	 {Magnetic Rattle-Type Core-Shell Particles Containing
                  Iron Compounds with Acid Tolerance by Dense Silica},
  journal =	 {Industrial \& Engineering Chemistry Research},
  volume =	 0,
  pages =	 {null},
  year =	 2014,
  doi =		 {10.1021/ie500588j},
  number =	 0,
  url =		 {http://pubs.acs.org/doi/abs/10.1021/ie500588j},
  eprint =	 {http://pubs.acs.org/doi/pdf/10.1021/ie500588j},
}

The key formatting comes from these definitions:

;; variables that control bibtex key format for auto-generation
;; I want firstauthor-year-title-words
;; this usually makes a legitimate filename to store pdfs under.
(setq bibtex-autokey-year-length 4
      bibtex-autokey-name-year-separator "-"
      bibtex-autokey-year-title-separator "-"
      bibtex-autokey-titleword-separator "-"
      bibtex-autokey-titlewords 2
      bibtex-autokey-titlewords-stretch 1
      bibtex-autokey-titleword-length 5)

You should develop a discipline to clean each entry as you add them, and before you cite them. It is a pain to change the key, and then find and change all the places you used that key before. Now that you have a systematic key, go ahead and download the pdf for the article, and save it in your pdf directory by that key name. Set the variable org-ref-pdf-directory to this directory, and later when you click on citations you will be able to open the pdf easily.

elisp:bibtex-validate

org-bib.bib

It is a good idea to keep your bibtex file sorted. This will facilitate finding duplicate entries, and will make it easier to find things. I usually add entries to the top of the file, and then clean them. Then run the command

elisp:bibtex-sort-buffer

org-bib.bib

A good way to check your bibliography for duplicates, spelling errors, and invalid formats is to make a pdf containing all the entries. Open your bibtex file, and run

elisp:org-ref-build-full-bibliography

Try it out: org-bib.bib

Sometimes you will get bad citation links in your document. Maybe there is no corresponding entry, maybe you typed in the wrong key, maybe you changed the key. Either way, you need to find them and fix them. Run the command

elisp:org-ref-find-bad-citations

cite:test

You will often work from your default bibliography for your own work. Eventually you will need to extract the entries cited so you can send them to someone. The command

elisp:org-ref-extract-bibtex-entries

cite:calle-vallejo-2010-trend-stabil

You can see a screen cast of this post here: http://screencast.com/t/yZCOdO6kJ

#+BEGIN_SRC: text :tangle extract-bib7108tYg.bib @article{calle-vallejo-2010-trend-stabil, author = {Calle-Vallejo, F. and Martinez, J. I. and Garcia- Lastra, J. M. and Mogensen, M. and Rossmeisl, J.}, title = {Trends in Stability of Perovskite Oxides}, journal = "Angewandte Chemie-International Edition", volume = 49, number = 42, pages = {7699-7701}, year = 2010, doi = {10.1002/anie.201002301}, keyword = {density functional calculations heats of formation perovskites thermochemistry transition-metals catalysts ferroelectricity}, } #+END_SRC

You can get the source here: https://github.com/jkitchin/jmax/blob/master/org-ref.org . This is an org-mode file, and you can load it with

(org-babel-load-file "org-ref.org")

That should be all you need for basic usage.

org-ref was written with bibtex in mind. We will discuss customization to use biblatex later.

The first thing you should do is add a bibliography link to your document. This link is usually put at the end of the document, where you want the bibliography to be printed in a LaTeX export. Use the filename of the bibliography with its extension in the link, and you can use multiple files if they are separated by commas. The bibliography link is clickable, and it will open the bibliography that you clicked on. Depending on the LaTeX class you are exporting to, you may also need to set a bibliographystyle.

Out of the box, org-ref binds the key "C-c ]" to insert a citation. That key runs the command org-ref-insert-cite-link, which will prompt you for a regular expression to search your bibliographies for. The search is done using reftex, so you can mark several entries at once, and they will be added as a citation link. The actual kind of link used is dependent on the value of org-ref-default-citation-link, which defaults to cite.

If your cursor is on a citation link, or at the end of the link, you can run the command again to append new citations to the link. The new entries are separated by commas. The links are clickable, and when you click on them you will see a message in the minibuffer with the citation, and options to open the entry, open a pdf (if you have it), open the url (if the entry has one), or to open notes about the entry. You get this menu for the entry that you clicked on.

If you want a different type of citation, type C-u C-c ]. You will be prompted for a format, and you can choose a different type of link format. Most bibtex formats are supported, and some biblatex formats are supported.

The other use of org-ref is for references to labels in your document. You can put labels in figure and table captions, and then reference them in your document. The label link is clickable, and when you click on it there will be a message in the minibuffer telling you how many labels of that name were found (it should be one).

You can then refer to Table (tab-boring). The ref links are also clickable, and they take you to the spot where the label is defined. You can enter ref links with completion. Press C-c C-l, type ref, press enter, and then press tab. You will get a list of the labels defined in the buffer you can choose from. There are many things you can make a ref to including a tblname, a label link, an explicit \label{}, and an org-mode #+label: line. (tab-boring)

There is an eqref link that is used for equations. You must use LaTeX labels in the equation for this.

\[e^x = 4 \label{eq-exp} \]

You can see in (eq-exp) the problem to solve.

There are two link types for generating a LateX list of tables and list of figures. These links are clickable, and they open a temporary buffer with a list of the tables or figures that you can click on. They export to \listoftables and \listoffigures

You can run these as commands, org-ref-list-of-tables and org-ref-list-of-figures if you do not want a list of those things in your exported document.

This covers most of the basic org-ref functionality. There are also several utility functions for interacting with org-buffers and bibtex files that will be described later.

See http://screencast.com/t/bxfafVydE for a screencast of using org-ref.

http://screencast.com/t/bxfafVydE

Each snippet definition belongs in a file in a directory. The main directory is called "snippets". Since I anticipate using these snippets in org-mode, each snippet is defined in a directory within snippets called "org-mode". First, we make the directory here. I also want to use the snippets in python mode, so we also create a python-mode directory here. We do not have to duplicate the snippets. We can create a file called .yas-parents , with one line in it containing "org-mode".

mkdir -p snippets/org-mode
mkdir -p snippets/python-mode
echo "org-mode" > snippets/python-mode/.yas-parents

Each snippet is defined in a src block with a :tangle header. So, we can extract them all in one command here.

(org-babel-tangle)

We also need to add our new directory to yasnippets. This is done by adding the directory to the yas-snippet-dirs variable. You could add this to your init.el file to permanently add these snippets.

(add-to-list 'yas-snippet-dirs "c:/Users/jkitchin/Dropbox/blogofile-jkitchin.github.com/_blog/snippets")

Finally, we reload all the snippet definitions, so our new definitions are ready to use.

(yas-reload-all)

[yas] Reloaded everything (snippets will load just-in-time)... (some errors, check *Messages*).

Alternatively, you might just load this directory.

(yas-load-directory "./snippets")

Each of these snippets is for a python phrase, but I usually write my python blocks in org-mode. You would use these by typing the shortcut name, and then pressing tab. Below I show what each shortcut expands to.

wjl → with jasp('') as calc:

wjn → with jasp('',) as calc: calc.calculate(atoms)

cc → calc.calculate(atoms)

cga → atoms = calc.get_atoms()

atm → Atom('', )

atms → atoms = Atoms([], cell)=

ape → atoms.get_potential_energy()

agf → atoms.get_forces()

avw → from ase.visualize import view view(atoms)

awt → from ase.io import write write('.png', atoms, show_unit_cell=2)

npa → np.array()

pp → plt.plot(, )

pxl → plt.xlabel()

pyl → plt.ylabel()

pl → plt.legend()

ij → from jasp import *

inp → import numpy as np

imp → import matplotlib.pyplot as plt

iase → from ase import Atom, Atoms

What other snippets would be handy?