A user guide to the geophysical tutorials
|This tutorial originally appeared as a featured article in The Leading Edge in February 2016 — see issue.|
Every other month since February 2014, The Leading Edge has published a geophysical tutorial. The dozen installments so far have spanned a wide range of topics, from basics such as well ties to more involved subjects such as compressed sensing — and everything in between.
The tutorials are popular with readers, and I get lots of e-mails about them. The most common questions are: “How do I run the accompanying computer programs?” and “Can I write a tutorial?” I thought I would answer those questions for everyone today. The column also has some unusual features that you might not have noticed — it is reproducible and open access. If those words mean nothing to you, that's OK. I'll address them too.
What does "open access" mean?You might have noticed that the tutorials have a small OA symbol next to them in the online edition of TLE. This means “open access” … but what does that mean?
The tutorials are a great experiment in open-access publishing for TLE. (Authors occasionally choose to pay for their material in Geophysics and Interpretation to be open access.) One of the reasons for publishing them with an open-access license was to enable the tutorials to be repurposed “as is” in SEG Wiki — all of the content in the SEG Wiki carries an open license, just like most of the content in Wikipedia.
The gist of open licenses is that people can reuse the content without permission if they meet the terms of the license. In the case of the tutorial, there are two important terms: You agree to identify the author of the work, and you agree to publish any derivative work under the same type of license. The license is free and, crucially, already granted, so there is no need to ask.
You can read more about Creative Commons licenses, the most common open-access license in publishing, in a blog post of mine at http://ageo.co/CC-post.
What does "reproducible" mean?
The open license would be impossible or at least rather complicated if there were other proprietary content in the tutorials. Hence, I ask authors to use only openly available and reusable data. This might seem like a big request, but such data sets do exist — for example, see open data.
But we don't stop at open access and open data. Virtually every figure in the tutorials is fully reproducible by you, the reader, using the computer code the authors provide with their tutorials. Rather than being a full piece of software, the code is usually a more informal sequence of steps, a sort of script containing the minimal set of commands to reproduce the figures in the tutorial. We use only high-level languages such as Python and Octave (a free and open-source MATLAB clone) that many geophysicists will have used or at least heard of, and we try to make the code as easy to follow as possible.
The idea is that you should be able to read a tutorial, then sit down and reproduce everything in it from scratch.
How do I use the notebooks or other code?
Most of the tutorials so far have been accompanied by Jupyter notebooks (formerly IPython notebooks). These unique documents combine formatted text and inline images with executable code blocks and their output. You can even include interactive widgets. They also have the advantage of running code written in any of more than 40 languages, including Python, Octave (or MATLAB), Julia, R, C#, C++, Haskell, and Scala. At least for relative newcomers to scientific computing, Jupyter notebooks seem to be useful tools. Find out more about them at http://jupyter.org.
You can read the notebooks online at http://github.com/seg/tutorials — look for the .ipynb files. To run them yourself, however, you will need to get them onto your system. If you have git installed, you can clone the tutorials repo with the commands:
git clone http://github.com/seg/tutorials segtutorials
git clone http://github.com/seg/tutorials-2017 tutorials-2017
git clone http://github.com/seg/tutorials-2016 tutorials-2016
git clone http://github.com/seg/tutorials-2015 tutorials-2015
git clone http://github.com/seg/tutorials-2014 tutorials-2014
Alternatively, you can download a zip file containing the tutorials directly from the GitHub link. Put the unzipped folder where you will find it again.
Because most of the code we have published has been in Python, I recommend starting with a Python distribution. If you are starting from scratch, your best bet is to install Continuum's free Anaconda product. This greatly simplifies the process of installing Python and its various supporting packages. To get it, visit http://continuum.io/downloads and follow the instructions there.
Once you have Anaconda installed, start the Anaconda launcher (on Mac or Windows) and look for the notebook or launch the notebook directly from the command line with the command jupyter notebook. The notebook has access only to files in the working directory or its subfolders, so start it from the directory where your files are. Once it is started, you can click on the notebooks in the browser, and they will open.
Inside the notebook, you can execute a code block by pressing shift + enter. You can change anything you like — this is your own copy. Use the interface for other commands or learn the hot keys. Exploring the notebooks is a great way to get started with Python programming.
Can I write a tutorial?
You definitely can! I would welcome contributions on any technical topic of interest to seismic interpreters, applied geophysicists, and earth scientists in general. Something you have learned only recently yourself is often a good subject.
You can probably learn more about the required pitch and length from the existing articles than from me. The column is relatively informal and should be accessible to any numerate person. If you can put together 1500 words or so and two or three figures (see Figure 1), that's a good start. Add a bit of code to help people along or find a coder to collaborate with, and you will have a great tutorial.
The column is ongoing, so deadlines do not really come into it. If you have something, we can probably find a slot for it. Drop me a line at
mattagilegeoscience.com if you want to talk about a specific idea.