From 9384e067f736c1b9d4a93f71f8a6db8a741f2de0 Mon Sep 17 00:00:00 2001 From: Frank Austin Nothaft Date: Sun, 5 Mar 2017 15:20:39 -0800 Subject: [PATCH 1/3] Adding citation information to README. --- README.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/README.md b/README.md index 47b4aa7b94..8853f4e016 100644 --- a/README.md +++ b/README.md @@ -370,3 +370,40 @@ ADAM is released under an [Apache 2.0 license](LICENSE.txt). [Spark]: https://spark.apache.org/ [Parquet]: https://parquet.apache.org/ [releases]: https://github.com/bigdatagenomics/adam/releases + +# Citing ADAM + +ADAM has been described in two manuscripts. The first, [a tech +report](https://www2.eecs.berkeley.edu/Pubs/TechRpts/2013/EECS-2013-207.pdf), +came out in 2013 and described the rationale behind using schemas for genomics, +and presented an early implementation of some of the preprocessing algorithms. +To cite this paper, please cite: + +``` +@techreport{massie13, + title={{ADAM}: Genomics Formats and Processing Patterns for Cloud Scale Computing}, + author={Massie, Matt and Nothaft, Frank and Hartl, Christopher and Kozanitis, Christos and Schumacher, Andr{\'e} and Joseph, Anthony D and Patterson, David A}, + year={2013}, + institution={UCB/EECS-2013-207, EECS Department, University of California, Berkeley} +} +``` + +The second, [a conference paper](http://dl.acm.org/ft_gateway.cfm?ftid=1586788&id=2742787), +appeared in the SIGMOD 2015 Industrial Track. This paper described how ADAM's +design was influenced by database systems, expanded upon the concept of a stack +architecture for scientific analyses, presented more results comparing ADAM to +state-of-the-art single node genomics tools, and demonstrated how the +architecture generalized beyond genomics. To cite this paper, please cite: + +``` +@inproceedings{nothaft15, + title={Rethinking Data-Intensive Science Using Scalable Analytics Systems}, + author={Nothaft, Frank A and Massie, Matt and Danford, Timothy and Zhang, Zhao and Laserson, Uri and Yeksigian, Carl and Kottalam, Jey and Ahuja, Arun and Hammerbacher, Jeff and Linderman, Michael and Franklin, Michael and Joseph, Anthony D. and Patterson, David A.}, + booktitle={Proceedings of the 2015 International Conference on Management of Data (SIGMOD '15)}, + year={2015}, + organization={ACM} +} +``` + +We prefer that you cite both papers, but if you can only cite one paper, we +prefer that you cite the SIGMOD 2015 manuscript. \ No newline at end of file From fe83be639417739daf50a10d54aa6e0b1ff18ae7 Mon Sep 17 00:00:00 2001 From: Frank Austin Nothaft Date: Sat, 4 Mar 2017 15:13:41 -0800 Subject: [PATCH 2/3] [ADAM-1368] Add markdown docs for the GenomicRDD.pipe interface. Resolves #1368. Also adds docs for ADAMContext and GenomicRDD. --- docs/source/60_building_apps.md | 330 ++++++++++++++++++++++++++++++++ docs/source/70_algorithms.md | 8 +- docs/source/bibliography.bib | 11 +- 3 files changed, 344 insertions(+), 5 deletions(-) diff --git a/docs/source/60_building_apps.md b/docs/source/60_building_apps.md index f7b47a4cbe..c44f31e751 100644 --- a/docs/source/60_building_apps.md +++ b/docs/source/60_building_apps.md @@ -284,3 +284,333 @@ class MyCommandKryoRegistrator extends KryoRegistrator { } } ``` + +## Using ADAM as a library {#library} + +The `adam-core` and `adam-apis` modules are designed to be used as a library in +downstream applications. Scala apps should use `adam-core`, while Java +applications should also depend on `adam-apis`. The main entrypoint to ADAM is +the [ADAMContext](#adam-context), which allows genomic data to be loaded in to +Spark as [GenomicRDD](#genomic-rdd). GenomicRDDs can be transformed using ADAM's +built in [pre-processing algorithms](#algorithms), [Spark's RDD +primitives](#transforming), and ADAM's [pipe](#pipes) APIs. + +### Accessing pre-built libraries + +These libraries are available from [Maven Central](http://search.maven.org) with +the following coordinates: + +``` + + org.bdgenomics.adam + adam-core${binary.version} + ${adam.version} + + + org.bdgenomics.adam + adam-apis${binary.version} + ${adam.version} + +``` + +For each release, we support four `${binary.version}`s: + +* `_2.10`: Spark 1.6.x on Scala 2.10 +* `_2.11`: Spark 1.6.x on Scala 2.11 +* `-spark2_2.10`: Spark 2.x on Scala 2.10 +* `-spark2_2.11`: Spark 2.x on Scala 2.11 + +Additionally, we push nightly SNAPSHOT releases of ADAM to the +[Sonatype snapshot repo](https://oss.sonatype.org/content/repositories/snapshots/org/bdgenomics/adam/), +for developers who are interested in working on top of the latest changes in +ADAM. + +### Loading data with the ADAMContext {#adam-context} + +The ADAMContext is the main entrypoint to using ADAM. The ADAMContext wraps +an existing [SparkContext](http://spark.apache.org/docs/latest/api/scala/index.html#org.apache.spark.SparkContext) +to provide methods for loading genomic data. In Scala, we provide an implicit +conversion from a `SparkContext` to an `ADAMContext`. To use this, import the +implicit, and call an `ADAMContext` method: + +```scala +import org.apache.spark.SparkContext + +// the ._ at the end imports the implicit from the ADAMContext companion object +import org.bdgenomics.adam.rdd.ADAMContext._ +import org.bdgenomics.adam.rdd.read.AlignmentRecordRDD + +def loadReads(filePath: String, sc: SparkContext): AlignmentRecordRDD = { + sc.loadAlignments(filePath) +} +``` + +In Java, instantiate a JavaADAMContext, which wraps an ADAMContext: + +```java +import org.apache.spark.apis.java.JavaSparkContext; +import org.bdgenomics.adam.apis.java.JavaADAMContext +import org.bdgenomics.adam.rdd.ADAMContext; +import org.bdgenomics.adam.rdd.read.AlignmentRecordRDD; + +class LoadReads { + + public static AlignmentRecordRDD loadReads(String filePath, + JavaSparkContext jsc) { + // create an ADAMContext first + ADAMContext ac = new ADAMContext(jsc.sc()); + + // then wrap that in a JavaADAMContext + JavaADAMContext jac = new JavaADAMContext(ac); + + return jac.loadAlignments(filePath); + } +} +``` + +With an `ADAMContext`, you can load: + +* Single reads as an `AlignmentRecordRDD`: + * From SAM/BAM/CRAM using `loadBam` (Scala only) + * Selected regions from an indexed BAM/CRAM using `loadIndexedBam` (Scala + only) + * From FASTQ using `loadFastq`, `loadPairedFastq`, and `loadUnpairedFastq` + (Scala only) + * From Parquet using `loadParquetAlignments` (Scala only) + * The `loadAlignments` method will load from any of the above formats, and + will autodetect the underlying format (Scala and Java, also supports loading + reads from FASTA) +* Paired reads as a `FragmentRDD`: + * From interleaved FASTQ using `loadInterleavedFastqAsFragments` (Scala only) + * From Parquet using `loadParquetFragments` (Scala only) + * The `loadFragments` method will load from either of the above formats, as + well as SAM/BAM/CRAM, and will autodetect the underlying file format. If the + file is a SAM/BAM/CRAM file and the file is queryname sorted, the data will + be converted to fragments without performing a shuffle. (Scala and Java) +* VCF lines as a `VariantContextRDD` from VCF/BCF1 using `loadVcf` (Scala only) +* Selected lines from a tabix indexed VCF using `loadIndexedVcf` (Scala only) +* Genotypes as a `GenotypeRDD`: + * From Parquet using `loadParquetGenotypes` (Scala only) + * From either Parquet or VCF/BCF1 using `loadGenotypes` (Scala and Java) +* Variants as a `VariantRDD`: + * From Parquet using `loadParquetVariants` (Scala only) + * From either Parquet or VCF/BCF1 using `loadVariants` (Scala and Java) +* Genomic features as a `FeatureRDD`: + * From BED using `loadBed` (Scala only) + * From GFF3 using `loadGff3` (Scala only) + * From GFF2/GTF using `loadGtf` (Scala only) + * From NarrowPeak using `loadNarrowPeak` (Scala only) + * From IntervalList using `loadIntervalList` (Scala only) + * From Parquet using `loadParquetFeatures` (Scala only) + * Autodetected from any of the above using `loadFeatures` (Scala and Java) +* Fragmented contig sequence as a `NucleotideContigFragmentRDD`: + * From FASTA with `loadFasta` (Scala only) + * From Parquet with `loadParquetContigFragments` (Scala only) + * Autodetected from either of the above using `loadSequences` (Scala and Java) +* Coverage data as a `CoverageRDD`: + * From Parquet using `loadParquetCoverage` (Scala only) + * From Parquet or any of the feature file formats using `loadCoverage` (Scala + only) +* Contig sequence as a broadcastable `ReferenceFile` using `loadReferenceFile`, + which supports 2bit files, FASTA, and Parquet (Scala only) + +The methods labeled "Scala only" may be usable from Java, but may not be +convenient to use. + +The `JavaADAMContext` class provides Java-friendly methods that are equivalent +to the `ADAMContext` methods. Specifically, these methods use Java types, and do +not make use of default parameters. In addition to the load/save methods +described above, the `ADAMContext` adds the implicit methods needed for using +[ADAM's Pipe API](#pipes). + +### Working with genomic data using GenomicRDDs {#genomic-rdd} + +As described in the section on using the [ADAMContext}(#adam-context), ADAM +loads genomic data into a `GenomicRDD` which is specialized for each datatype. +This `GenomicRDD` wraps Apache Spark's Resilient Distributed Dataset (RDD, +[@zaharia12]) API with genomic metadata. The `RDD` abstraction presents an +array of data which is distributed across a cluster. `RDD`s are backed by +a computational lineage, which allows them to be recomputed if a node fails and +the results of a computation are lost. `RDD`s are processed by running +functional [transformations]{#transforming} across the whole dataset. + +Around an `RDD`, ADAM adds metadata which describes the genome, samples, or +read group that a dataset came from. Specifically, ADAM supports the following +metadata: + +* `GenomicRDD` base: A sequence dictionary, which describes the reference + assembly that data is aligned to, if it is aligned. Applies to all types. +* `MultisampleGenomicRDD`: Adds metadata about the samples in a dataset. + Applies to `GenotypeRDD`. +* `ReadGroupGenomicRDD`: Adds metadata about the read groups attached to a + dataset. Applies to `AlignmentRecordRDD` and `FragmentRDD`. + +Additionally, `GenotypeRDD`, `VariantRDD`, and `VariantContextRDD` store the +VCF header lines attached to the original file, to enable a round trip between +Parquet and VCF. + +`GenomicRDD`s can be transformed several ways. These include: + +* The [core preprocessing](#algorithms) algorithms in ADAM: + * Reads: + * Reads to coverage + * [Recalibrate base qualities](#bqsr) + * [INDEL realignment](#realignment) + * [Mark duplicate reads](#duplicate-marking) + * Fragments: + * [Mark duplicate fragments](#duplicate-marking) +* [RDD transformations](#transforming) +* [By using ADAM to pipe out to another tool](#pipes) + +#### Transforming GenomicRDDs {#transforming} + +Although `GenomicRDD`s do not extend Apache Spark's `RDD` class, `RDD` +operations can be performed on them using the `transform` method. Currently, +we only support `RDD` to `RDD` transformations that keep the same type as +the base type of the `GenomicRDD`. To apply an `RDD` transform, use the +`transform` method, which takes a function mapping one `RDD` of the base +type into another `RDD` of the base type. For example, we could use `transform` +on an `AlignmentRecordRDD` to filter out reads that have a low mapping quality, +but we cannot use `transform` to translate those reads into `Feature`s showing +the genomic locations covered by reads. + +#### Using ADAM's Pipe API {#pipes} + +ADAM's `GenomicRDD` API provides support for piping the underlying genomic data +out to a single node process through the use of a `pipe` API. This builds off of +Apache Spark's `RDD.pipe` API. However, `RDD.pipe` prints the objects as +strings to the pipe. ADAM's pipe API adds several important functions: + +* It supports on-the-fly conversions to widely used genomic file formats +* It doesn't require input/output type matching (i.e., you can pipe reads in + and get variants back from the pipe) +* It adds the ability to set environment variables and to make local files + (e.g., a reference genome) available to the run command +* If the data is aligned, we ensure that each subcommand runs over a contiguious + section of the reference genome, and that data is sorted on this chunk. We + provide control over the size of any flanking region that is desired. + +The method signature of a pipe command is below: + +```scala +def pipe[X, Y <: GenomicRDD[X, Y], V <: InFormatter[T, U, V]](cmd: String, + files: Seq[String] = Seq.empty, + environment: Map[String, String] = Map.empty, + flankSize: Int = 0)(implicit tFormatterCompanion: InFormatterCompanion[T, U, V], + xFormatter: OutFormatter[X], + convFn: (U, RDD[X]) => Y, + tManifest: ClassTag[T], + xManifest: ClassTag[X]): Y +``` + +`X` is the type of the records that are returned (e.g., for reads, +`AlignmentRecord`) and `Y` is the type of the `GenomicRDD` that is returned +(e.g., for reads, `AlignmentRecordRDD`). As explicit parameters, we take: + +* `cmd`: The command to run. +* `files`: Files to make available locally to each running command. These files + can be referenced from `cmd` by using `$#` syntax, where `#` is the number + of the file in the `files` sequence (e.g., `$0` is the head of the list, + `$1` is the second file in the list, and so on). +* `environment`: Environment variable/value pairs to set locally for each + running command. +* `flankSize`: The number of base pairs to flank each partition by, if piping + genome aligned data. + +Additionally, we take several important implicit parameters: + +* `tFormatter`: The `InFormatter` that converts the data that is piped into the + run command from the underlying `GenomicRDD` type. +* `xFormatter`: The `OutFormatter` that converts the data that is piped out of + the run command back to objects for the output `GenomicRDD`. +* `convFn`: A function that applies any necessary metadata conversions and + creates a new `GenomicRDD`. + +The `tManifest` and `xManifest` implicit parameters are [Scala +ClassTag](http://www.scala-lang.org/api/2.10.3/index.html#scala.reflect.ClassTag)s +and will be provided by the compiler. + +What are the implicit parameters used for? For each of the genomic datatypes in +ADAM, we support multiple legacy genomic filetypes (e.g., reads can be saved to +or read from BAM, CRAM, FASTQ, and SAM). The `InFormatter` and `OutFormatter` +parameters specify the format that is being read into or out of the pipe. We +support the following: + +* `AlignmentRecordRDD`: + * `InFormatter`s: `SAMInFormatter` and `BAMInFormatter` write SAM or BAM out + to a pipe. + * `OutFormatter`: `AnySAMOutFormatter` supports reading SAM and BAM from a + pipe, with the exact format autodetected from the stream. + * We do not support piping CRAM due to complexities around the reference-based + compression. +* `FragmentRDD`: + * `InFormatter`: `InterleavedFASTQInFormatter` writes FASTQ with the reads + from a paired sequencing protocol interleaved in the FASTQ stream to a pipe. +* `VariantContextRDD`: + * `InFormatter`: `VCFInFormatter` writes VCF to a pipe. + * `OutFormatter`: `VCFOutFormatter` reads VCF from a pipe. + +The `convFn` implementations are provided as implicit values in the +[ADAMContext](#adam-context). These conversion functions are needed to adapt +the metadata stored in a single `GenomicRDD` to the type of a different +`GenomicRDD` (e.g., if piping an `AlignmentRecordRDD` through a command that +returns a `VariantContextRDD`, we will need to convert the `AlignmentRecordRDD`s +`RecordGroupDictionary` into an array of `Sample`s for the `VariantContextRDD`). +We provide four implementations: + +* `ADAMContext.sameTypeConversionFn`: For piped commands that do not change the + type of the `GenomicRDD` (e.g., `AlignmentRecordRDD` → `AlignmentRecordRDD`). +* `ADAMContext.readsToVCConversionFn`: For piped commands that go from an + `AlignmentRecordRDD` to a `VariantContextRDD`. +* `ADAMContext.fragmentsToReadsConversionFn`: For piped commands that go from a + `FragmentRDD` to an `AlignmentRecordRDD`. + +To put everything together, here's an example command. Here, we will run a +command `my_variant_caller`, which accepts one argument `-R .fa`, +SAM on standard input, and outputs VCF on standard output: + +```scala +// import RDD load functions and conversion functions +import org.bdgenomics.adam.rdd.ADAMContext._ + +// import functionality for piping SAM into pipe +import org.bdgenomics.adam.rdd.read.SAMInFormatter + +// import functionality for reading VCF from pipe +import org.bdgenomics.adam.converters.DefaultHeaderLines +import org.bdgenomics.adam.rdd.variant.{ + VariantContextRDD, + VCFOutFormatter +} + +// load the reads +val reads = sc.loadAlignments("hdfs://mynamenode/my/read/file.bam") + +// define implicit informatter for sam +implicit val tFormatter = SAMInFormatter + +// define implicit outformatter for vcf +// attach all default headerlines +implicit val uFormatter = new VCFOutFormatter(DefaultHeaderLines.allHeaderLines) + +// run the piped command +// providing the explicit return type (VariantContextRDD) will ensure that +// the correct implicit convFn is selected +val variantContexts: VariantContextRDD = reads.pipe("my_variant_caller -R $0", + files = Seq("hdfs://mynamenode/my/reference/genome.fa")) + +// save to vcf +variantContexts.saveAsVcf("hdfs://mynamenode/my/variants.vcf") +``` + +In this example, we assume that `my_variant_caller` is on the PATH on each +machine in our cluster. We suggest several different approaches: + +* Install the executable on the local filesystem of each machine on your + cluster. +* Install the executable on a shared file system (e.g., NFS) that is accessible + from every machine in your cluster, and make sure that necessary prerequisites + (e.g., python, dynamically linked libraries) are installed across each node on + your cluster. +* Run the command using a container system such as [Docker](https://docker.io) + or [Singularity](http://singularity.lbl.gov/). \ No newline at end of file diff --git a/docs/source/70_algorithms.md b/docs/source/70_algorithms.md index 4222b36dad..3ef9d0ad76 100644 --- a/docs/source/70_algorithms.md +++ b/docs/source/70_algorithms.md @@ -1,4 +1,4 @@ -# Core Algorithms +# Core Algorithms {#algorithms} ## Read Preprocessing Algorithms @@ -43,7 +43,7 @@ mishandled if the two reads in the pair overlap. In the rest of this section, we discuss the high level implementations of these algorithms. -### BQSR Implementation +### BQSR Implementation {#bqsr} Base quality score recalibration seeks to identify and correct correlated errors in base quality score estimates. At a high level, this is done by associating sequenced bases with possible error covariates, and estimating the @@ -112,7 +112,7 @@ $$ After these probabilities are estimated, we go back across the input read dataset and reconstruct the quality scores of the read by using the covariate assigned to the read to look into the covariate table. -### Indel Realignment Implementation +### Indel Realignment Implementation {#realignment} Although global alignment will frequently succeed at aligning reads to the proper region of the genome, the local alignment of the read may be incorrect. Specifically, the error models used by aligners may penalize local alignments @@ -232,7 +232,7 @@ consensus has a log-odds ratio (LOD) that is greater than $5.0$ with respect to reads. This is done by recomputing the CIGAR and MDTag for each new alignment. Realigned reads have their mapping quality score increased by 10 in the Phred scale. -### Duplicate Marking Implementation +### Duplicate Marking Implementation {#duplicate-marking} Reads may be duplicated during sequencing, either due to clonal duplication via PCR before sequencing, or due to optical duplication while on the sequencer. To identify duplicated reads, we apply a heuristic algorithm diff --git a/docs/source/bibliography.bib b/docs/source/bibliography.bib index e976efad0b..92bdcfa7f1 100644 --- a/docs/source/bibliography.bib +++ b/docs/source/bibliography.bib @@ -73,4 +73,13 @@ @inproceedings{vavilapalli13 pages={5}, year={2013}, organization={ACM} -} \ No newline at end of file +} + +@inproceedings{zaharia12, + title={Resilient distributed datasets: {A} fault-tolerant abstraction for in-memory cluster computing}, + author={Zaharia, Matei and Chowdhury, Mosharaf and Das, Tathagata and Dave, Ankur and Ma, Justin and McCauley, Murphy and Franklin, Michael and Shenker, Scott and Stoica, Ion}, + booktitle={Proceedings of the Conference on Networked Systems Design and Implementation (NSDI '12)}, + pages={2}, + year={2012}, + organization={USENIX Association} +} From 6ec6749a562e81f7069f7659443f1179f5e83fc4 Mon Sep 17 00:00:00 2001 From: devin-petersohn Date: Mon, 6 Feb 2017 09:41:05 -0800 Subject: [PATCH 3/3] Added ShuffleRegionJoin usage docs --- docs/source/60_building_apps.md | 61 +++++++++++++++++++++++++++++- docs/source/img/join_examples.png | Bin 0 -> 87381 bytes 2 files changed, 60 insertions(+), 1 deletion(-) create mode 100644 docs/source/img/join_examples.png diff --git a/docs/source/60_building_apps.md b/docs/source/60_building_apps.md index c44f31e751..187807de0f 100644 --- a/docs/source/60_building_apps.md +++ b/docs/source/60_building_apps.md @@ -293,7 +293,8 @@ applications should also depend on `adam-apis`. The main entrypoint to ADAM is the [ADAMContext](#adam-context), which allows genomic data to be loaded in to Spark as [GenomicRDD](#genomic-rdd). GenomicRDDs can be transformed using ADAM's built in [pre-processing algorithms](#algorithms), [Spark's RDD -primitives](#transforming), and ADAM's [pipe](#pipes) APIs. +primitives](#transforming), the [region join](#join) primitive, and ADAM's +[pipe](#pipes) APIs. ### Accessing pre-built libraries @@ -474,6 +475,64 @@ on an `AlignmentRecordRDD` to filter out reads that have a low mapping quality, but we cannot use `transform` to translate those reads into `Feature`s showing the genomic locations covered by reads. +#### Using ADAM’s RegionJoin API {#join} + +Another useful API implemented in ADAM is the RegionJoin API, which joins two +genomic datasets that contain overlapping regions. This primitive is useful for +a number of applications including variant calling (identifying all of the reads +that overlap a candidate variant), coverage analysis (determining the coverage +depth for each region in a reference), and INDEL realignment (identify INDELs +aligned against a reference). + +There are two overlap join implementations available in ADAM: +BroadcastRegionJoin and ShuffleRegionJoin. The result of a ShuffleRegionJoin +is identical to the BroadcastRegionJoin, however they serve different +purposes depending on the content of the two datasets. + +The ShuffleRegionJoin is at its core a distributed sort-merge overlap join. +To ensure that the data is appropriately colocated, we perform a copartition +on the right dataset before the each node conducts the join locally. The +BroadcastRegionJoin performs an overlap join by broadcasting a copy of the +entire left dataset to each node. ShuffleRegionJoin should be used if the right +dataset is too large to send to all nodes and both datasets have low +cardinality. The BroadcastRegionJoin should be used when you are joining a +smaller dataset to a larger one and/or the datasets in the join have high +cardinality. + +Another important distinction between ShuffleRegionJoin and +BroadcastRegionJoin is the join operations available in ADAM. See the table +below for an exact list of what joins are available for each type of +RegionJoin. + +To perform a ShuffleRegionJoin, add the following to your ADAM script: + +```dataset1.shuffleRegionJoin(dataset2)``` + +To perform a BroadcastRegionJoin, add the following to your ADAM script: + +```dataset1.broadcastRegionJoin(dataset2)``` + +Where dataset1 and dataset2 are GenomicRDDs. If you used the ADAMContext to +read a genomic dataset into memory, this condition is met. + +ADAM has a variety of ShuffleRegionJoin types that you can perform on your +data, and all are called in a similar way: + +![Joins Available] +(img/join_examples.png) + + +Join call | action | Availability +----------|--------| +```dataset1.shuffleRegionJoin(dataset2) ``` ```dataset1.broadcastRegionJoin(dataset2)```| perform an inner join | ShuffleRegionJoin BroadcastRegionJoin +```dataset1.fullOuterShuffleRegionJoin(datset2)```|perform an outer join | ShuffleRegionJoin +```dataset1.leftOuterShuffleRegionJoin(dataset2)```|perform a left outer join | ShuffleRegionJoin +```dataset1.rightOuterShuffleRegionJoin(dataset2)``` ```dataset1.rightOuterBroadcastRegionJoin(dataset2)```|perform a right outer join | ShuffleRegionJoin BroadcastRegionJoin +```dataset1.shuffleRegionJoinAndGroupByLeft(dataset2)``` |perform an inner join and group joined values by the records on the left | ShuffleRegionJoin +```dataset1.broadcastRegionJoinnAndGroupByRight(dataset2)``` | perform an inner join and group joined values by the records on the right | ShuffleRegionJoin +```dataset1.rightOuterShuffleRegionJoinAndGroupByLeft(dataset2)```|perform a right outer join and group joined values by the records on the left | ShuffleRegionJoin +```rightOuterBroadcastRegionJoinAndGroupByRight``` | perform a right outer join and group joined values by the records on the right | BroadcastRegionJoin + #### Using ADAM's Pipe API {#pipes} ADAM's `GenomicRDD` API provides support for piping the underlying genomic data diff --git a/docs/source/img/join_examples.png b/docs/source/img/join_examples.png new file mode 100644 index 0000000000000000000000000000000000000000..6ac2ddb3aaf8efb99ea1ce0c0c1300017f17d37f GIT binary patch literal 87381 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 literal 0 HcmV?d00001