uses.org: Reproducible Research demo added
[worg.git] / org-contrib / babel / uses.org
1 #+OPTIONS:    H:3 num:nil toc:1 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:nil skip:nil d:(HIDE) tags:not-in-toc
2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) 
5 #+TITLE:      Source Code Blocks: Uses
6 #+AUTHOR:     Thomas S. Dye
7 #+EMAIL:      tsd at tsdye dot com
8 #+LANGUAGE:   en
9 #+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
10 #+STYLE:      <style type="text/css">#table-of-contents{ max-width:100%; }</style>
11 #+LINK_UP:  index.php
12 #+LINK_HOME: http://orgmode.org/worg/
13 #+EXPORT_SELECT_TAGS: export
14 #+EXPORT_EXCLUDE_TAGS: noexport
15
16 * Introduction
17
18   This page collects examples of using source code blocks in a variety
19   of contexts.  Contributions of further examples from Org Mode users are
20   very welcome.
21
22
23 * Using Multiple Languages
24
25 ** [[file:examples/data-collection-analysis.org][Data Collection and Analysis]]
26    (raw file available at [[http://orgmode.org/w/?p%3Dworg.git%3Ba%3Dblob_plain%3Bf%3Dorg-contrib/babel/examples/data-collection-analysis.org%3Bhb%3DHEAD][data-collection-analysis.org]])
27
28    This example uses Babel to automate a repeated data-collection
29    and analysis task.  A Ruby code block is used to scrape data from
30    the output of a computational experiment.  This data is then written
31    to an Org-mode table.  A block of R code reads from this table and
32    calculates lines of fit.  Finally a block of gnuplot code is used to
33    graph the results of both the raw data and the R analysis.  By
34    performing all of these steps within an Org-mode document working
35    notes, discussion, and TODOs can be naturally interspersed with the
36    code, and the results can easily be published to HTML or PDF for
37    distribution.
38
39 * Integrations with R
40 ** [[file:how-to-use-Org-Babel-for-R.org][Tutorial Org/Babel/R by Feiming Chen]]                            :noexport:
41
42 ** [[http://www.stats.ox.ac.uk/~davison/software/org-babel/drift.org.html][Teaching Evolution Using R]]
43    This example is a tutorial on simulating evolution in R. It contains
44    examples of diagrams generated with =ditaa=, LaTeX, and graphics
45    generated with R.
46
47    A good way to see how org-babel functions to create the tutorial is to
48    view the [[http://www.stats.ox.ac.uk/~davison/software/org-babel/drift.org.html][htmlized org buffer]]. This also provides an example of how
49    images and latex-generated mathematical notation can be viewed inline
50    in emacs. The HTML export version is [[file:examples/drift.org][here]].
51
52 ** [[file:examples/ascii.org][An Example Using the Ascii Package]]
53    (raw file available at [[http://orgmode.org/w/?p%3Dworg.git%3Ba%3Dblob_plain%3Bf%3Dorg-contrib/babel/examples/ascii.org%3Bhb%3DHEAD][ascii.org]])
54  
55    This example shows how to use Org Mode source code blocks with =R=
56    and the =ascii= package.  The =ascii= package is useful for
57    retrieving non-tabular =R= data structures in Org Mode.
58
59 ** [[http://orgmode.org/w/?p%3Dworg.git%3Ba%3Dblob%3Bf%3Dorg-contrib/babel/examples/foo.org.html%3Bh%3D3d157d2ac1b361eea9afc71436a3b0a23a5f1070%3Bhb%3DHEAD][/An Babel Demo/ -- A Comparison to Sweave]]
60   :PROPERTIES:
61   :CUSTOM_ID: foo
62   :END:
63
64 [[http://www.stat.umn.edu/~charlie/][Charlie Geyer]] created an excellent short demonstration of Sweave entitled
65 /An Sweave Demo/ available at [[http://www.stat.umn.edu/~charlie/Sweave/][his Sweave page]].  There is now an Babel
66 version of this demonstration entitled /An Babel Demo/ which matches
67 Charlie's document word for word (as much as possible) and figure for
68 figure with all the examples implemented using Babel instead of Sweave.
69
70 Compare the two side-by-side.
71
72 |        | source                                  | pdf     |
73 |--------+-----------------------------------------+---------|
74 | Sweave | [[http://www.stat.umn.edu/~charlie/Sweave/foo.Rnw][foo.Rnw]]                                 | [[http://www.stat.umn.edu/~charlie/Sweave/foo.pdf][foo.pdf]] |
75 | Babel  | [[http://orgmode.org/w/?p%3Dworg.git%3Ba%3Dblob_plain%3Bf%3Dorg-contrib/babel/examples/foo.org%3Bhb%3DHEAD][foo.org]] ([[http://orgmode.org/w/?p%3Dworg.git%3Ba%3Dblob_plain%3Bf%3Dorg-contrib/babel/examples/foo.org.html%3Bhb%3DHEAD][foo.org.html]] as seen in Emacs) | [[http://orgmode.org/w/?p%3Dworg.git%3Ba%3Dblob_plain%3Bf%3Dorg-contrib/babel/examples/foo.pdf%3Bhb%3DHEAD][foo.pdf]] |
76
77 ** [[file:examples/Rpackage.org][R Package Development Headers]]
78 This document contains  
79  - tools useful for writing R extensions called /packages/
80  - source code to create a simple R package
81
82  [[http://repo.or.cz/w/Worg.git/blob_plain/HEAD:/org-contrib/babel/examples/Rpackage.org][Download]] the =.org= version of this document and place it in either
83  an R package source directory or in a clean directory to get started.
84
85 ** Tutorial on Emacs+ESS and Org+R by Stephen Eglen
86
87 See [[http://article.gmane.org/gmane.emacs.orgmode/45777][this message]] from Stephen Eglen:
88
89 : I gave a 3 hour tutorial on Emacs Speaks Statistics on Monday; this
90 : included mostly Emacs and ESS, but also introduced org-mode for R users.
91 : If anyone is interested, the slides and material are available at:
92
93 http://www.damtp.cam.ac.uk/user/sje30/ess11
94
95 * Integrations with LaTeX
96 ** [[file:examples/latex-form.org][A LaTeX Form]]
97    (raw file available at [[http://orgmode.org/w/?p%3Dworg.git%3Ba%3Dblob_plain%3Bf%3Dorg-contrib/babel/examples/latex-form.org%3Bhb%3DHEAD][latex-form.org]])
98
99    This example uses Babel as a user interface for a LaTeX form
100    that might be used by the members of an organization.  It uses the
101    literate programming facility of Babel to isolate the user from
102    the sometimes arcane LaTeX constructs needed to create a
103    highly-structured form.  Babel can tangle multiple documents in
104    a single Org-mode file, and this ability is used to create a
105    distribution version of the form separate from one designed for the
106    file cabinet.
107
108 ** [[file:examples/short-report.org][A Standardized Short Report]]
109    (raw file available at [[http://orgmode.org/w/?p%3Dworg.git%3Ba%3Dblob_plain%3Bf%3Dorg-contrib/babel/examples/short-report.org%3Bhb%3DHEAD][short-report.org]])
110
111    This example is similar to the previous one, but here the users are
112    expected to write substantial content.  This type of workflow might
113    be used by a small organization whose employees regularly produce
114    standard documents and where the writing tasks for any one document
115    are divided among the authors.  
116
117    The HTML export facility of Org-mode is used to produce a guide to
118    writing the standardized short report.  This HTML file can be used
119    to train new authors.  The Org-mode content also supplies
120    substantial direction to experienced authors as they write.
121    Org-mode keywords and tags are used to keep track of writing
122    assignments and progress.  Babel's literate programming facility
123    makes it possible to present writing tasks to the authors in an order
124    different from which they appear in the report.
125
126 ** [[file:examples/article-class.org][A Literate Article Class for Org Mode LaTeX Export]]              :noexport:
127
128 This project is no longer supported.  It eventually became the [[http://orgmode.org/worg/org-tutorials/org-latex-export.html][LaTeX
129 export tutorial.]]  It is included here as a historical curiosity.
130
131 This example is a literate program that tangles an article class for
132 Org-mode LaTeX export.  The class supports numerous options that
133 control the look and feel of the resulting pdf file.  It provides
134 several facilities: 
135
136   - Default packages :: Options to keep individual LaTeX packages from
137        loading make it somewhat easier to modify which LaTeX packages
138        are loaded during the processing of LaTeX code exported by
139        Org-mode.
140   - Semantic markup :: A facility for semantic markup is implemented,
141        which makes it possible to markup according to arbitrary LaTeX
142        styles, such as the ones distributed by journals and book publishers.
143   - Fonts :: The package also implements several choices of fonts and
144              takes steps to ensure that the fonts don't clash with the
145              symbol font files that Org-mode depends upon to typeset
146              =org-entities=.
147   - Listing themes :: The class provides pre-defined themes for
148                       formatting source code listings, which can be
149                       used as is, or used as a basis for minor modifications.
150   - Compact lists :: A facility to typeset lists with less vertical
151                      space is provided.
152   - Double spacing :: An option is provided to set lines double spaced.
153   - Table of contents :: The table of contents depth can be set
154        independently of section numbering depth.
155   - Section numbering :: Section numbering depth can specified
156        independently of the table of contents depth.
157
158 * Financial Applications
159 ** [[file:examples/finances.org][Tracking Finances]]
160 :PROPERTIES:
161 :Author: Jason Dunsmore
162 :CUSTOM_ID: tracking-finances
163 :END:
164
165 An Emacs lisp function in a Babel source block aggregates entries in
166 an Org-mode table, which can be useful in tracking finances.
167  
168 ** Using Ledger to Track Finances
169
170 Instead of writing functions to track finances entered in Org-mode
171 tables, Babel makes it possible to use Org-mode and Ledger to track
172 finances.  A [[file:languages/ob-doc-ledger.org][short tutorial]] illustrates how to insert ledger entries
173 in an Org-mode file and how to generate financial reports from those
174 entries using Babel to call Ledger.
175
176 * Reproducible Research Examples
177 ** [[https://github.com/tsdye/hawaii-colonization][A Reproducible Research Paper Written in Org Mode]]
178
179 This git repository contains Org-mode source and data files for the
180 paper "A Model-based Age Estimate for the Polynesian Colonization of
181 Hawai`i," which was published in the journal [[http://sydney.edu.au/arts/publications/oceania/arch_oceaniacrnt.htm][Archaeology in
182 Oceania]].
183
184 The repo includes a README file with system requirements and
185 instructions to make a pdf version of the paper.  Also included is a
186 Makefile that automates the process of compiling the paper to pdf.
187
188 The pdf file represents the initial submittal to the journal.
189 [[http://sydney.edu.au/arts/publications/oceania/arch_oceaniacrnt.htm][Archaeology in Oceania]] requires a Word file at the end of the review
190 process.  This was created from the Org-mode LaTeX export with the
191 late Eitan Gurari's [[http://www.tug.org/applications/tex4ht/mn.html][tex4ht]] software, followed by numerous tweaks with
192 Word (graciously executed by a colleague who knows how to use that
193 application).
194
195 Archaeologists and other scientists who work with radiocarbon dating
196 might be interested in the R code for plotting multiple sets of
197 results from the [[http://bcal.shef.ac.uk/top.html][BCal software.]]
198
199 ** [[https://github.com/tsdye/LKFS][Another Reproducible Research Paper Written in Org Mode]]
200
201 This git repository contains Org-mode source and data files for the
202 paper "The Tempo of Change in the Leeward Kohala Field System," which
203 was published in the [[http://islandheritage.org/wordpress/?page_id%3D295][Rapa Nui Journal]].
204
205 The repo includes a README file with system requirements and
206 instructions to make a pdf version of the paper.  Also included is a
207 Makefile that automates the process of compiling the paper to pdf.
208
209 Archaeologists might be interested in the code that creates a
210 graphical representation of the Harris matrix from an adjacency matrix
211 of stratigraphic relations, which is included as an Org-mode table.  A
212 Python source block reads the adjacency matrix and outputs GraphViz
213 code.  This is used as input to the =tred= utility, which eliminates
214 transitive relations.  The output of the =tred= utility is passed to
215 =dot=, which prepares Figure 2 in the paper.
216
217 ** [[https://github.com/novoid/orgmode-iKNOW2012][Reproducible Research Demo Paper: from Org to ACM]]
218
219 In Summer 2012, Karl Voit and Tom Dye produced a demo paper for the
220 [[http://i-know.tugraz.at/][i-KNOW conference]] in Graz, Austria. This demo uses the new LaTeX
221 exporter to generate a ready-to-submit ACM paper from raw CSV files
222 and an Org-mode file.
223
224 This is a proof-of-concept demo which might need some improvement
225 here and there because the new LaTeX exporter is still a moving
226 target. The basic concept and methods could be re-used for other
227 papers that use a similar paper-generating approach.
228
229 It is related to [[https://github.com/novoid/orgmode-ACM-template][orgmode-ACM-template]] which is also hosted on
230 github. Please fork and send improvements!
231
232 * Source Code Blocks in Org Mode
233 ** [[file:examples/org-check.org][Checking Your Org Mode Configuration]]
234    (raw file available at [[http://orgmode.org/w/?p%3Dworg.git%3Ba%3Dblob_plain%3Bf%3Dorg-contrib/babel/examples/org-check.org%3Bhb%3DHEAD][org-check.org]])
235
236    This example runs some diagnostic checks to see if your system and
237    Org-mode are configured to accomplish various tasks.  It is
238    currently a stub placed here in the hope that the Org-mode community
239    will augment and enhance it.  It was created in response to a thread
240    on the mailing list on how to ease the learning curve for new
241    Org-mode users.
242
243 ** [[file:examples/fontify-src-code-blocks.org][Pretty Fontification of Code Blocks]]
244
245 The article about [[file:examples/fontify-src-code-blocks.org][pretty fontification of code blocks]] shows the user how to
246 customize a couple of Emacs faces in order to enhance his Babel experience,
247 and get much nicer visual separation between code and text.
248
249 ** [[file:examples/lob-table-operations.org][Some generic Operations on Org Mode Tables]]
250
251    (raw file available at [[http://orgmode.org/w/?p%3Dworg.git%3Ba%3Dblob_plain%3Bf%3Dorg-contrib/babel/examples/lob-table-operations.org%3Bhb%3DHEAD][lob-table-operations.org]])
252
253    [[file:examples/lob-table-operations.org][This]] babel-file contains examples, documentation and
254    implementation of four generic operations on tables:
255    - Filtering the rows of a single table: keeping or removing rows
256    - Combining two tables into one: merging or intersecting tables
257    You may apply these operations readily to your own tables.
258