Cleaned up old files and reorganized navigation order.
authorPeter Amstutz <peter.amstutz@clinicalfuture.com>
Tue, 10 Dec 2013 21:18:15 +0000 (16:18 -0500)
committerPeter Amstutz <peter.amstutz@clinicalfuture.com>
Tue, 10 Dec 2013 21:18:15 +0000 (16:18 -0500)
14 files changed:
doc/user/api-tokens.textile
doc/user/intro-git.md
doc/user/intro-jobs.textile
doc/user/intro-keep.md [deleted file]
doc/user/old/api-tokens.md [deleted file]
doc/user/old/index.md [deleted file]
doc/user/old/ssh-access.md [deleted file]
doc/user/sdk-cli.textile
doc/user/ssh-access.textile
doc/user/tutorial-gatk-variantfiltration.textile
doc/user/tutorial-job-debug.textile
doc/user/tutorial-job1.textile
doc/user/tutorial-new-pipeline.textile
doc/user/tutorial-trait-search.textile

index 483b8e0cbf5579948c527ff29d8bdf1a12bcc542..03cea0b9558dc97f9806bb3bac85cf375aa0a4ea 100644 (file)
@@ -1,8 +1,8 @@
 ---
 layout: default
 navsection: userguide
-title: Getting an API token
-navorder: 1
+title: "Reference: Getting an API token"
+navorder: 20
 ---
 
 h1. Getting an API token
index 37e847e9594c71cfea6e7ac05ae9cefaecf86a7d..efcea587f414fc9537542ce4acc319bf4be0ae8d 100644 (file)
@@ -1,8 +1,8 @@
 ---
 layout: default
 navsection: userguide
-title: "Intro: git"
-navorder: 4
+title: "Reference: git"
+navorder: 23
 ---
 
 # Intro: git
index 431caca838072c260d7c3ccae2ed6a18245a456d..a466c57a8c78a367e1cf1859d30845b431b33c6e 100644 (file)
@@ -1,8 +1,8 @@
 ---
 layout: default
 navsection: userguide
-title: "Intro: Jobs"
-navorder: 8
+title: "Reference: Jobs"
+navorder: 22
 ---
 
 h1. Intro: Jobs
diff --git a/doc/user/intro-keep.md b/doc/user/intro-keep.md
deleted file mode 100644 (file)
index a4a479a..0000000
+++ /dev/null
@@ -1,129 +0,0 @@
----
-layout: default
-navsection: userguide
-title: "Intro: Keep"
-navorder: 3
----
-
-# Intro: Keep
-
-Keep is a content-addressable storage system. Its semantics are
-inherently different from the POSIX-like file systems you're used to.
-
-> Explain what "content-addressable" means more specifically.
-> Define "locator"
-
-Using Keep looks like this:
-
-1. Write data.
-2. Receive locator.
-3. Use locator to retrieve data.
-4. Tag the locator with a symbolic name.
-
-By contrast, using POSIX looks like this:
-
-1. Choose locator (*i.e.*, filename).
-2. Write data to locator.
-3. Use locator to retrieve data.
-
-Content addressing provides various benefits, including:
-
-* Reduction of unnecessary data duplication
-* Prevention of race conditions (a given locator always references the same data)
-* Systematic client- and server-side verification of data integrity
-* Provenance reporting (when combined with Arvados MapReduce jobs)
-
-### Vocabulary
-
-Keep arranges data into **collections** and **data blocks**.
-
-A collection is analogous to a directory tree in a POSIX
-filesystem. It contains subdirectories and filenames, and indicates
-where to find the data blocks which comprise the files. It is encoded
-in plain text.
-
-> Can a collection contain sub-collections?
-> The "plain text" encoding is JSON, right?  Either be specific or
-> remove it because the user doesn't really need to know about the encoding
-> at this level.
-
-A data block contains between 1 byte and 64 MiB of data. Its locator
-is the MD5 checksum of the data, followed by a plus sign and its size
-in bytes (encoded as a decimal number).
-
-`acbd18db4cc2f85cedef654fccc4a4d8+3`
-
-> What does this locator encode?  Give an example so the astute
-> reader could use "md5" herself to construct the id.
-
-A locator may include additional "hints" to help the Keep store find a
-data block more quickly. For example, in the locator
-`acbd18db4cc2f85cedef654fccc4a4d8+3+K@{{ site.arvados_api_host }}` the
-hint "+K@{{ site.arvados_api_host }}" indicates that the data block is
-stored in the Keep instance called *{{ site.arvados_api_host }}*. The
-hints are not necessary for Keep to locate a data block -- only the
-MD5 hash is -- but they help improve performance.
-
-Keep distributes data blocks among the available disks. It also stores
-multiple copies of each block, so a single disk or node failure does
-not cause any data to become unreachable.
-
-### No "delete"
-
-One of the side effects of the Keep write semantics is the lack of a
-"delete" operation. Instead, Keep relies on garbage collection to
-delete unneeded data blocks.
-
-### Tagging valuable data
-
-> Now this goes from background introduction to tutorial,
-> so this should probably be split up
-
-Valuable data must be marked explicitly by creating a Collection in
-Arvados. Otherwise, the data blocks will be deleted during garbage
-collection.
-
-Use the arv(1) program to create a collection. For example:
-
-    arv collection create --uuid "acbd18db4cc2f85cedef654fccc4a4d8+3"
-
-> What does this actually do?
-
-## Getting started
-
-Write three bytes of data to Keep.
-
-    echo -n foo | whput -
-
-> What does "wh" stand for in the program name?
-
-Output:
-
-    acbd18db4cc2f85cedef654fccc4a4d8+3+K@arv01
-
-> Explain that this is the locator that Keep has stored the data under
-
-Retrieve the data.
-
-    whget acbd18db4cc2f85cedef654fccc4a4d8+3+K@arv01
-
-Output:
-
-    foo
-
-
-{% include alert-stub.html %}
-
-### Writing a collection
-
-### Reading a file from a collection
-
-### Adding a collection to Arvados
-
-### Tagging a collection
-
-### Mounting Keep as a read-only POSIX filesystem
-
-### Mounting a single collection as a POSIX filesystem
-
-> Needs a yellow "this web page under construction" sign with a guy shoveling dirt.
diff --git a/doc/user/old/api-tokens.md b/doc/user/old/api-tokens.md
deleted file mode 100644 (file)
index 1e1d664..0000000
+++ /dev/null
@@ -1,55 +0,0 @@
----
-layout: default
-navsection: userguide
-title: Getting an API token
-navorder: 1
----
-
-h1. Getting an API token
-
-The Arvados API token is a secret key that enables the command line
-client to access arvados with the proper permissions.
-
-Open a browser and point it to the Workbench URL for your site. It
-will look something like this:
-
-`https://workbench.{{ site.arvados_api_host }}/`
-
-Log in, if you haven't done that already.
-
-Click the "API tokens" link.
-
-> Need to indicate that "API Tokens" is underneath "Access"
-
-At the top of the "API tokens" page, you will see a few lines like this.
-
-    ### Pasting the following lines at a shell prompt will allow Arvados SDKs
-    ### to authenticate to your account, youraddress@example.com
-    
-    read ARVADOS_API_TOKEN <<EOF
-    2jv9kd1o39t0pcfu7aueem7a1zjxhak73w90tzq3gx0es7j1ld
-    EOF
-    export ARVADOS_API_TOKEN ARVADOS_API_HOST=qr1hi.arvadosapi.com
-
-Paste those lines into your terminal window to set up your
-terminal. This effectively copies your credentials from your browser
-to your terminal session.
-
-Now, `arv -h user current` will display your account info in JSON
-format.
-
-> What does `-h` mean?
-
-Optionally, copy those lines to your .bashrc file so you don't have to
-repeat this process each time you log in.
-
-### SSL + development mode
-
-> This section should go somewhere else, it is confusing to a new user.
-
-If you are using a local development server with a self-signed
-certificate, you might need to bypass certificate verification. Don't
-do this if you are using a production service.
-
-    export ARVADOS_API_HOST_INSECURE=yes
-
diff --git a/doc/user/old/index.md b/doc/user/old/index.md
deleted file mode 100644 (file)
index 921a3d5..0000000
+++ /dev/null
@@ -1,83 +0,0 @@
----
-layout: default
-navsection: userguide
-title: Getting started (old)
-navorder: 0
----
-
-> I'd like to see the user guide consist of the following sections:
-> 1. background (general architecture/theory of operation from the user's perspective)
-> 2. getting started / tutorials
-> 3. how to (in depth topics)
-> 4. tools reference (command line, workbench, etc)
-> Currently the user guide is mostly just 2.
-
-# Getting started
-
-As a new user, you should take a quick tour of Arvados environment.
-
-
-### Log in to Workbench
-
-Open a browser and point it to the Workbench URL for your site. It
-will look something like this:
-
-`https://workbench.{{ site.arvados_api_host }}/`
-
-Depending on site policy, a site administrator might have to activate
-your account before you see any more good stuff.
-
-> "Good stuff" is vague.
-
-### Browse shared data angd pipelines
-
-On the Workbench home page, you should see some datasets, programs,
-jobs, and pipelines that you can explore.
-
-> This would be a great place for a screenshot or at least a little
-> more guidance on where to look (these things are all accessed
-> through the menu bar)
-
-### Install the command line SDK on your workstation
-
-(Optional)
-
-> Is this really optional?  All the tutorials are about how to use
-> the command line SDK
-
-Most of the functionality in Arvados is exposed by the REST API. This
-means (depending on site policy and firewall) that you can do a lot of
-stuff with the command line client and other SDKs running on your own
-computer.
-
-> "A lot of stuff" is vague.
-
-Technically you can make all API calls using a generic web client like
-[curl](http://curl.haxx.se/docs/) but you will have a more enjoyable
-experience with the Arvados CLI client.
-
-> I would mention this somewhere else, a new user isn't going to be using
-> curl.
-
-See [command line SDK](sdk-cli.html) for installation instructions.
-
-### Request a virtual machine
-
-> The purpose of this whole section is confusing, because after explaning that you
-> can access arvados from your workstation with the client SDK, it then
-> implies that you actually need to go and log into an arvados VM instance
-> instead.
-
-It's more fun to do stuff with a virtual machine, especially if you
-know about [screen](http://www.gnu.org/software/screen/).
-
-> Screen is cool, but not relevant here.
-
-In order to get access to an Arvados VM, you need to:
-
-1. Upload an SSH public key ([learn how](ssh-access.html))
-1. Request a new VM (or access to a shared VM)
-
-> Needs some kind of discussion on how to request a new VM or discover
-> the hostname of the shared VM
-
diff --git a/doc/user/old/ssh-access.md b/doc/user/old/ssh-access.md
deleted file mode 100644 (file)
index 48059ba..0000000
+++ /dev/null
@@ -1,184 +0,0 @@
----
-layout: default
-navsection: userguide
-title: Setting up SSH access (old)
-navorder: 2
----
-
-# Setting up SSH access
-
-Arvados uses SSH public key authentication for two things:
-
-* logging in to a VM, and
-* pushing code to a git repository.
-
-### Generate a public/private SSH key pair
-
-If you don't already have an SSH key pair (or you don't know whether
-you do), there are lots of tutorials out there to help you get
-started:
-
-* [github SSH key
-tutorial](https://www.google.com/search?q=github+ssh+key+help)
-
-### Associate your SSH public key with your Arvados Workbench account
-
-> Maybe mention that the "Add a new authorized key" button will be at the bottom of the page
-
-
-Go to the `Keys` page in Arvados Workbench (under the `Access` tab) and click the
-
-<p style="margin-left: 4em"><span class="btn btn-primary disabled">Add a new authorized key</span></p>
-
-button. Then click on 'none' in the public_key column, and copy and paste your public key:
-
-![Screen shot of the ssh public key box]({{ site.baseurl }}/images/ssh-adding-public-key.png)
-
-Click on the checkmark button to save your public key.
-
-### Set up your ssh client (Unix-like systems only)
-
-{% include notebox-begin.html %}
-
-If you are using an Arvados site other than {{ site.arvados_api_host }}, replace "{{ site.arvados_api_host }}" with the appropriate Arvados API hostname in these examples.
-
-{% include notebox-end.html %}
-
-On your workstation, add the following section to your `~/.ssh/config`
-file:
-
-    Host *.arvados
-      ProxyCommand ssh -p2222 turnout@switchyard.{{ site.arvados_api_host }} -x -a $SSH_PROXY_FLAGS %h
-
-> This needs to be explained that it is adding an alias to make it easier to log into an
-> arvados server on port 2222.  This is not actually necessary if the user doesn't mind some typing.
-> Actually, it might make sense to show the regular command line first, and then mention later that
-> it can be shortened using ~/.ssh/config. 
-
-If you have access to an account `foo` on a VM called `blurfl` then
-you can log in like this:
-
-    ssh foo@blurfl.arvados
-
-Some other convenient configuration options are `User` and
-`ForwardAgent`:
-
-    Host *.a
-      ProxyCommand ssh -p2222 turnout@switchyard.{{ site.arvados_api_host }} -x -a $SSH_PROXY_FLAGS %h
-      User foo
-         ForwardAgent yes
-
-> This shortened *.arvados to *.a
-> This should be consistent
-
-Adding `User foo` will log you in to the VM as user `foo` by default,
-so you can just `ssh blurfl.a`. The `ForwardAgent yes` option turns on
-the `ssh -A` option to forward your SSH credentials (if you are
-using ssh-agent), which becomes important if you use git to
-synchronize files between your workstation and the VM.
-
-Then you can log in to the `blurfl` VM as `foo` like this:
-
-    ssh blurfl.a
-
-Arvados Workbench will show you a list of VMs you have access to and
-what your account name is for each one: click "VMs" in the "Access"
-menu.
-
-### Windows: Setup instructions for PuTTY
-
-PuTTY is a free (MIT-licensed) Win32 Telnet and SSH client. PuTTy includes all the tools a windows user needs to set up Private Keys and to set up and use SSH connections to your virtual machines in the Arvados Cloud. 
-
-You can use PuTTY to create public/private keys, which are how you’ll ensure that that access to Arvados cloud is secure. You can also use PuTTY as an SSH client to access your virtual machine in an Arvados cloud and work with the Arvados Command Line Interface (CLI) client. 
-
-PuTTY is an open source project and you download it [here](http://www.putty.org/).
-
-Arvados uses Public-key encryption to secure access to your virtual machines in the Arvados cloud. this is a very standard approach. It’s secure, and easy to use. 
-
-(Make sure to download the .zip file containing all the binaries, not each one individually)
-
-__Step 1 - Adding PuTTY to the PATH__
-
-1. After downloading PuTTY and unzipping it, you should have a PuTTY folder in C:\Program Files (x86)\ . If the folder is somewhere else, you can change the PATH in step X or move the folder to that directory.
-
-2. In the Start menu, right click Windows and select Properties
-
-3. Select Advanced System Settings, and choose Environment Variables
-
-4. Under system variables, find and edit Path.
-
-5. Add the following to the end of Path (make sure to include semi colon and quotation marks): 
-
-       ;\"C:\Program Files (x86)\PuTTY\"
-
-6. Click through the OKs to close all the dialogs you’ve opened
-
-__Step 2 - Creating a Public Key__
-
-1. Open PuTTYgen from the Start Menu
-
-2. At the bottom of the window, make sure the ‘Number of bits in a generated key’ field is set to 4096
-
-3. Click Generate and follow the instructions to generate a key
-
-4. Click to save the Public Key 
-
-5. Click to save the Private Key (we recommend using a strong passphrase) 
-
-6. Select the Public Key text in the box and copy (for next step) 
-
-Now your key is successfully generated. 
-
-__Step 3 - Load Your Public Key in to your Arvados Account through Workbench__
-
-1. Open Workbench on the cloud where you have an arvados account
-
-2. Go to Access > Keys in the menu 
-
-3. Click to create a new key 
-
-4. In the last column “public key” click on the text that says “none” and paste the public key from PuTTYgen into the box. 
-
-Your public key is now registered with the Arvados cluster. 
-
-__Step 4 - Set up Pageant__
-
-1. Start Pageant from the PuTTY folder in the start menu 
-
-2. Pageant will now be running in the system tray. Click the icon to configure. 
-
-3. Choose Add Key and add the private which corresponds with the public key you loaded in your Arvados account through work bench. 
-
-Pageant is now configured. It will run in the background as a system service. 
-
-Note: Pageant is a PuTTY utility that manages private keys which makes repeatedly logging in through SSH less of a hassle. 
-
-__Step 5 - Set up PuTTY__
-
-1. Open PuTTY from the Start Menu
-
-2. On the Session screen set the Host Name (or IP address) to “shell” 
-
-3. On the Session screen set the Port to “22”
-4. On the Connection > Data screen set the Auto-login username to your VM’s Login,. You can find your login name in Workbench under Access > VMs last column on the table. 
-
-5. On the Connection > Proxy screen set the Proxy Type to “Local” 
-
-6. On the Connection > Proxy screen in the “Telnet command, or local proxy command” box enter “plink -P 2222 turnout@switchyard.qr1hi.arvadosapi.com %host”. Make sure you remove the “\n” from the end of the line.
-
-7. Return to the Session screen. In the Saved Sessions box, enter a name for this configuration and hit Save. 
-
-
-__Step 6 - Launch an SSH Session__
-
-1. Open PuTTY 
-
-2. Click on the Saved Session name you created in Step 5
-
-3. Click Load to load those saved session settings
-
-4. Click Open and that will open the SSH window at the command prompt. You will now be logged in to your virtual machine. 
-
-_Note: We recommend you do not delete the “Default” Saved Session._
-
index 55e477db576a77bd39de05c2738be08a3f0ee267..76d069fdee92633feec48f53842fd8929832d90c 100644 (file)
@@ -1,8 +1,8 @@
 ---
 layout: default
 navsection: userguide
-title: "Intro: Command line SDK"
-navorder: 10
+title: "Reference: Command line SDK"
+navorder: 21
 ---
 
 {% include alert-stub.html %}
index cd2af2179d4b874b60a9fe11723685917b24a046..40c9e0066057cac9d938ebd092be8f990fd7a0a9 100644 (file)
@@ -2,7 +2,7 @@
 layout: default
 navsection: userguide
 title: Accessing Arvados over ssh
-navorder: 2
+navorder: 1
 ---
 
 h1. Accessing Arvados over ssh
index 0a5a9a4e5e45c3a49ec09aa0009e35a84081a031..552d2349006c751ad775e6c26c073331461a2bc7 100644 (file)
@@ -1,11 +1,11 @@
 ---
 layout: default
 navsection: userguide
-title: "Tutorial: GATK VariantFiltration"
-navorder: 22
+title: "Tutorial 6: GATK VariantFiltration"
+navorder: 16
 ---
 
-h1. Tutorial: GATK VariantFiltration
+h1. Tutorial 6: GATK VariantFiltration
 
 Here you will use the GATK VariantFiltration program to assign pass/fail scores to variants in a VCF file.
 
index 09e160cf0681853dd1aac1a4f237b93bd844d823..b52a372589c193f35a8c9e840eab515b376229a9 100644 (file)
@@ -1,11 +1,11 @@
 ---
 layout: default
 navsection: userguide
-title: "Tutorial: Debug a crunch script"
-navorder: 25
+title: "Tutorial 3: Debug a crunch script"
+navorder: 13
 ---
 
-h1. Tutorial: Debug a crunch script
+h1. Tutorial 3: Debug a crunch script
 
 The commit-push-submit cycle is too slow for developing and debugging crunch scripts.
 
index b58e7c9b15876bef2a520c3502f0c8cd41b6f1ca..866f1dd6d1c3d7e66527a65cb712e6fd09838d80 100644 (file)
@@ -2,7 +2,7 @@
 layout: default
 navsection: userguide
 title: "Tutorial 1: Introduction to Keep and your first Crunch job"
-navorder: 20
+navorder: 11
 ---
 
 h1. Tutorial 1: Introduction to Keep and your first crunch job
@@ -65,19 +65,19 @@ In Keep, information is stored in *data blocks*.  Data blocks are normally betwe
 
 In order to reassemble the file, Keep stores a *collection* data block which lists in sequence the data blocks that make up the original file.  A collection data block may store the information for multiple files, including a directory structure.
 
-In this example we will use @33a9f3842b01ea3fdf27cc582f5ea2af@ which is already available on {{ site.arvados_api_host }}.  First let us examine the contents of this collection using @arv-get@:
+In this example we will use @33a9f3842b01ea3fdf27cc582f5ea2af@ which is already available on {{ site.arvados_api_host }}.  First let us examine the contents of this collection using @arv keep get@:
 
 <pre>
-$ arv-get 33a9f3842b01ea3fdf27cc582f5ea2af
+$ arv keep get 33a9f3842b01ea3fdf27cc582f5ea2af
 . 204e43b8a1185621ca55a94839582e6f+67108864+K@qr1hi b9677abbac956bd3e86b1deb28dfac03+67108864+K@qr1hi fc15aff2a762b13f521baf042140acec+67108864+K@qr1hi 323d2a3ce20370c4ca1d3462a344f8fd+25885655+K@qr1hi 0:227212247:var-GS000016015-ASM.tsv.bz2
 </pre>
 
-@arv-get@ fetches the contents of the locator @33a9f3842b01ea3fdf27cc582f5ea2af@.  This is a locator for a collection data block, so it fetches the contents of the collection.  In this example, this collection consists of a single file @var-GS000016015-ASM.tsv.bz2@ which is 227212247 bytes long, and is stored using four sequential data blocks, @204e43b8a1185621ca55a94839582e6f+67108864+K@qr1hi@ , @b9677abbac956bd3e86b1deb28dfac03+67108864+K@qr1hi@ , @fc15aff2a762b13f521baf042140acec+67108864+K@qr1hi@ , @323d2a3ce20370c4ca1d3462a344f8fd+25885655+K@qr1hi@ .
+@arv keep get@ fetches the contents of the locator @33a9f3842b01ea3fdf27cc582f5ea2af@.  This is a locator for a collection data block, so it fetches the contents of the collection.  In this example, this collection consists of a single file @var-GS000016015-ASM.tsv.bz2@ which is 227212247 bytes long, and is stored using four sequential data blocks, <code>204e43b8a1185621ca55a94839582e6f+67108864+K@qr1hi</code>, <code>b9677abbac956bd3e86b1deb28dfac03+67108864+K@qr1hi</code>, <code>fc15aff2a762b13f521baf042140acec+67108864+K@qr1hi</code>, <code>323d2a3ce20370c4ca1d3462a344f8fd+25885655+K@qr1hi</code>.
 
-Let's use @arv-get@ to download the first datablock:
+Let's use @arv keep get@ to download the first datablock:
 
 <pre>
- $ arv-get 204e43b8a1185621ca55a94839582e6f+67108864+K@qr1hi > block1
+ $ arv keep get 204e43b8a1185621ca55a94839582e6f+67108864+K@qr1hi > block1
 </pre>
 
 Let's look at the size and compute the md5 hash of @block1@:
@@ -89,17 +89,17 @@ Let's look at the size and compute the md5 hash of @block1@:
  204e43b8a1185621ca55a94839582e6f  block1
 </pre>
 
-Notice that the block identifer @204e43b8a1185621ca55a94839582e6f+67108864+K@qr1hi@ consists of:
+Notice that the block identifer <code>204e43b8a1185621ca55a94839582e6f+67108864+K@qr1hi</code> consists of:
 * the md5 hash @204e43b8a1185621ca55a94839582e6f@
 * a size hint @67108864@
-* a location hint @K@qr1hi@
+* a location hint <code>K@qr1hi</code>
 
 In fact, _only_ the md5 hash is required to find the block.
 
-Next, let's use @arv-get@ to download and reassemble @var-GS000016015-ASM.tsv.bz2@ using the following command:
+Next, let's use @arv keep get@ to download and reassemble @var-GS000016015-ASM.tsv.bz2@ using the following command:
 
 <pre>
- $ arv-get 33a9f3842b01ea3fdf27cc582f5ea2af/var-GS000016015-ASM.tsv.bz2 .
+ $ arv keep get 33a9f3842b01ea3fdf27cc582f5ea2af/var-GS000016015-ASM.tsv.bz2 .
 </pre>
 
 This downloads the file @var-GS000016015-ASM.tsv.bz2@ described by collection @33a9f3842b01ea3fdf27cc582f5ea2af@ from Keep and places it into the local directory.  Now that we have the file, we can compute the md5 hash of the complete file:
@@ -116,10 +116,12 @@ In the previous section, we downloaded a file from Keep and computed the md5 has
 * Very large files may exceed the scratch space of the local disk.
 * We are only able to use the local CPU to process the file.
 
-The Arvados "crunch" framework is designed to support processing very large data batches (gigabytes to terabytes) efficiently, based on the following techniques:
-* Computation is preferentially sent to nodes that store the files locally, to avoid network and disk bottlenecks in sending files around.
-* Computation acts on file streams, avoiding the need to store the entire file contents in one place.
-* Computation can be distributed among many nodes in a cluster by acting on many files or parts of a single file in parallel.
+The Arvados "crunch" framework is designed to support processing very large data batches (gigabytes to terabytes) efficiently, and provides the following benefits:
+* Increase concurrency by running tasks asynchronously, using many CPUs and network interfaces at once (especially beneficial for CPU-bound and I/O-bound tasks respectively).
+* Track inputs, outputs, and settings so you can verify that the inputs, settings, and sequence of programs you used to arrive at an output is really what you think it was.
+* Ensure that your programs and workflows are repeatable with different versions of your code, OS updates, etc.
+* Interrupt and resume long-running jobs consisting of many short tasks.
+* Maintain timing statistics automatically, so they're there when you want them.
 
 For your first job, you will run the "hash" crunch script using the Arvados system.  The "hash" script computes the md5 hash of each file in a collection.
 
@@ -138,13 +140,13 @@ $ read -d $'\000' the_job <<EOF
 EOF
 </pre>
 
-* @read@ is a bash builtin that stores the first line of standard input into the local shell variable @the_job@
+* @read@ is a shell builtin that stores the first line of standard input into the local shell variable @the_job@
 * @-d $'\000'@ changes the line delimiter character from newline to null so that the entire input will be considered a single line.
 * @"script"@ specifies the name of the script to run.  The script is searched for in the "crunch_scripts/" subdirectory of the @git@ checkout specified by @"script_version"@.
 * @"script_version"@ specifies the version of the script that you wish to run.  This can be in the form of an explicit @git@ revision hash, or in the form "repository:branch" (in which case it will take the HEAD of the specified branch).  Arvados logs the script version that was used in the run, enabling you to go back and re-run any past job with the guarantee that the exact same code will be used as was used in the previous run.  You can access a list of available @git@ repositories on the Arvados workbench through _Access %(rarr)&rarr;% Repositories_.
 * @"script_parameters"@ are provided to the script.  In this case, the input is the locator for the collection that we inspected in the previous section.
 
-Use the @arv@ command to actually submit the job.  It should print out a JSON object which describes the newly created job:
+Use @arv job create@ to actually submit the job.  It should print out a JSON object which describes the newly created job:
 
 <pre>
 $ arv -h job create --job "$the_job"
@@ -210,7 +212,7 @@ This will run until the job finishes or is @curl@ is canceled with control-C.
 
 h3. Inspect the job output
 
-You can access the job output under the *output* column of the _Compute %(rarr)&rarr;% Jobs_ page.  Alternately, you can use the command line to access a JSON object describing the output:
+You can access the job output under the *output* column of the _Compute %(rarr)&rarr;% Jobs_ page.  Alternately, you can use @arv job get@ to access a JSON object describing the output:
 
 <pre>
 $ arv -h job get --uuid _value_of_uuid_from_arv_job_create_
@@ -258,20 +260,20 @@ $ arv -h job get --uuid _value_of_uuid_from_arv_job_create_
 
 * @"output"@ is the unique identifier for this specific job's output.  This is a Keep collection.
 
-List the files in the collection:
+Now you can list the files in the collection:
 
 <pre>
-$ arv-get _value_of_output_from_arv_job_get_
+$ arv keep get _value_of_output_from_arv_job_get_
 . 78b268d1e03d87f8270bdee9d5d427c5+61 0:61:md5sum.txt
 </pre>
 
-This collection consists of the md5sum.txt file.  Use @arv-get@ to show the contents of the md5sum.txt file:
+This collection consists of the md5sum.txt file.  Use @arv keep get@ to show the contents of the md5sum.txt file:
 
 <pre>
-$ arv-get 880b55fb4470b148a447ff38cacdd952+54+K@qr1hi/md5sum.txt
+$ arv keep get 880b55fb4470b148a447ff38cacdd952+54+K@qr1hi/md5sum.txt
 44b8ae3fde7a8a88d2f7ebd237625b4f var-GS000016015-ASM.tsv.bz2
 </pre>
 
-This md5 hash value should match the md5 hash which we computed by hand.
+This md5 hash matches the md5 hash which we computed earlier.
 
 This concludes the first tutorial.  In the next tutorial, "we will inspect how the hash script works.":tutorial-firstscript.html
index 1dca21f78bb0cd7296d972c4c85611f1504fa471..0f0102dcce30054023ce77bcf8e8550314395e90 100644 (file)
@@ -1,11 +1,11 @@
 ---
 layout: default
 navsection: userguide
-title: "Tutorial: Construct a new pipeline"
-navorder: 24
+title: "Tutorial 5: Construct a new pipeline"
+navorder: 15
 ---
 
-h1. Tutorial: Construct a new pipeline
+h1. Tutorial 5: Construct a new pipeline
 
 Here you will write two new crunch scripts, incorporate them into a new pipeline template, run the new pipeline a couple of times using different parameters, and compare the results. One of the new scripts will use the Arvados API to look up trait&rarr;human&rarr;data relations and use this information to compile a collection of data to analyze.
 
index d98ba2efd55473cd70d47a35042c23d624cce240..da6083a35ad73cde0a2e24905da4f3ee0a710cfc 100644 (file)
@@ -1,11 +1,11 @@
 ---
 layout: default
 navsection: userguide
-title: "Tutorial: Search PGP data by trait"
-navorder: 23
+title: "Tutorial 4: Search PGP data by trait"
+navorder: 14
 ---
 
-h1. Tutorial: Search PGP data by trait
+h1. Tutorial 4: Search PGP data by trait
 
 Here you will use the Python SDK to find public WGS data for people who have a certain medical condition.