wiki/org-mode-babel.org

#+TITLE: Org-mode: Babel
#+ROAM_TAGS: reproducible-research
#+PROPERTIES: header-args :session  :exports both


Org-babel is the framework that enables [[file:org-mode.org][Org-mode]] to insert output of the code from programming languages.
It is also the one thing that makes Org-mode to be used as a tool for [[file:reproducible-research.org][Reproducible research]].
As of 2020-06-08, [[https://orgmode.org/worg/org-contrib/babel/languages.html][Babel supports more than 50 languages]] with the possibility of adding of other languages that are not supported yet.




* The fundamental concepts

Here's an example of a code block executed with the shell.

#+BEGIN_SRC sh
echo "HELLO WORLD"
#+END_SRC

#+RESULTS:
: HELLO WORLD

To execute the code block, simply run ~org-babel-execute-src-block~ (by default, this is mapped in ~<C-c> <C-c>~).
The results will be printed into a result block.

Each of the supported language may also have an exclusive option with each language suitable for certain processes.

For example, with Python 3, you can pretty print it in accordance to Org-mode display.
An array will create a table, for instance with ~:results value~ [[https://orgmode.org/manual/Using-Header-Arguments.html#Using-Header-Arguments][header argument]].

#+BEGIN_SRC python  :results value
[["Item", "Value"], ["Baseball bat", 123], ["Baseball glove", 25], ["Printed shirt", 42]]
#+END_SRC

#+RESULTS:
: None

You can also export graphics with tools such as [[http://gnuplot.info/][Gnuplot]], [[https://www.gnu.org/software/octave/][GNU Octave]], [[https://www.r-project.org/][R]], and even [[https://www.latex-project.org/][LaTeX]].
With it, you can export the graphics into a file (commonly with ~:file <PATH>~).

#+BEGIN_SRC gnuplot  :exports both  :file wooosh.png
unset arrow
unset label
set grid
splot x**2+y**2, x**2-y**2
#+END_SRC

#+RESULTS:
[[file:wooosh.png]]

With Org-babel, you can share either the output, the code used to generate the output, or both.
This is commonly set with the ~:exports~ header argument.
[fn:: Again, this varies whether export options are available for each Babel-supported lanaguages.]

Here's an example where I decided to show only the output with ~:exports results~.

#+BEGIN_SRC gnuplot  :exports results  :file threeeeeeD.png
set title "3D gnuplot demo"
unset grid
splot x*y with points
#+END_SRC

#+RESULTS:
[[file:threeeeeeD.png]]




* Sessions

Each of the source code block runs on an individual session.
However, you can connect source code blocks (with the supported languages) in the same session with ~:session <SESSION NAME>~.

Let's start with a simple example where we want to demonstrate some Python shenanigans.
Here's one Python code block.

#+BEGIN_SRC python  :results output  :session python-example
x = 35
print(x)
#+END_SRC

#+RESULTS:
: 35

Then here's another code block in the same session.

#+BEGIN_SRC python  :results output  :session python-example
for i in range(5):
  x += 5
  print(x)
#+END_SRC

#+RESULTS:
: 40
: 45
: 50
: 55
: 60

In certain code where the output can still change (for example, try executing the previous code block again), this may not be the desired behavior.
To correct this, simply execute ~org-babel-execute-buffer~.




* Integrating between different programming languages

You can also pass Org-mode variables (from ~#+NAME: <VAR>~) [fn:: Technically called an internal link (https://orgmode.org/org.html#Internal-Links).] into the source code blocks with the ~:var <NAMEC>=<DATA>~ (though, this may vary among Babel runtimes).

#+NAME: example_string
This is the string.

#+BEGIN_SRC python  :var example=example_string  :results value
example
#+END_SRC

#+RESULTS:
: None

This is the source code from the document, for reference.

#+BEGIN_SRC org  :exports code  :results silent
,#+NAME: example_string
This is the string.

,#+BEGIN_SRC python  :var example=example_string  :outputs value
example
,#+END_SRC

,#+RESULTS:
,: This is the string.
#+END_SRC

Org-mode variables does capture an element as its input.
This has a lot of implications of passing data between different sessions and even different languages.

For example, we could still capture the ~x~ variable from the previous Python code blocks.

#+NAME: var_from_other_lang
#+BEGIN_SRC python  :results silent  :session python-example  :exports value
x # Which should be 60 at this point.
#+END_SRC

Then, pass it to some other Org-mode blocks with the variable.
(Since the captured variable are always going to be a string, we have to convert it into the appropriate type.)

#+BEGIN_SRC R  :results output  :var python_var=var_from_other_lang
as.numeric(python_var) + 2
#+END_SRC

#+RESULTS:
: [1] 62