From 198d10d826fb4b0ae5b6de747136a0dd654a5d3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20O=27Mara?= Date: Fri, 5 Jul 2019 01:24:24 +1000 Subject: [PATCH] Tweak README --- README.md | 41 +++++++++++++++++------------------------ 1 file changed, 17 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 13204e3..2c83baa 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,11 @@ ## Overview -This package provides load and save support for [Bedgraph files](https://github.com/CiaranOMara/Bedgraph.jl) -under the [FileIO.jl](https://github.com/JuliaIO/FileIO.jl) package. - -This package is largely -- if not completely -- inspired by the work of [David Anthoff](https://github.com/davidanthoff). +This package provides load and save support for [Bedgraph](https://github.com/CiaranOMara/Bedgraph.jl) +under the [FileIO](https://github.com/JuliaIO/FileIO.jl) package, and also implements the [IterableTables](https://github.com/davidanthoff/IterableTables.jl) interface for easy conversion between tabular data structures. ## Installation -Install BedgraphFiles from the Julia REPL: +You can install BedgraphFiles from the Julia REPL: ```julia using Pkg add("BedgraphFiles") @@ -23,21 +21,20 @@ add("BedgraphFiles") ## Usage -### Loading a Bedgraph file - -To load a Bedgraph file into a ``Vector{Bedgraph.Record}``, use the following Julia code: +### Loading bedGraph files +To load a bedGraph file into a ``Vector{Bedgraph.Record}``, use the following Julia code: ````julia using FileIO, BedgraphFiles, Bedgraph records = Vector{Bedgraph.Record}(load("data.bedgraph")) ```` -### Saving a Bedgraph file +### Saving bedGraph files > **Note:** saving on top of an existing file will overwrite metadata/header information with a minimal working header. -The following example saves a ``Vector{Bedgraph.Record}`` to a Bedgraph file: +The following example saves a ``Vector{Bedgraph.Record}`` to a bedGraph file: ````julia using FileIO, BedgraphFiles, Bedgraph @@ -47,18 +44,16 @@ save("output.bedgraph", records) ```` ### IterableTables -The call to ``load`` returns a ``struct`` that is an [IterableTable.jl](https://github.com/davidanthoff/IterableTables.jl), so it can be passed to any function that can handle iterable tables, i.e. all the sinks in [IterableTable.jl](https://github.com/davidanthoff/IterableTables.jl). - -To load a Bedgraph file into a `DataFrame`, use the following Julia code: +The execution of ``load`` returns a ``struct`` that adheres to the [IterableTables](https://github.com/davidanthoff/IterableTables.jl) interface, and can be passed to any function that also implements the interface, i.e. all the sinks in [IterableTable.jl](https://github.com/davidanthoff/IterableTables.jl). +The following code shows an example of loading a bedGraph file into a [DataFrame](https://github.com/JuliaData/DataFrames.jl): ```julia using FileIO, BedgraphFiles, DataFrames df = DataFrame(load("data.bedgraph")) ``` -Here are some examples of materialising a Bedgraph file into data structures that are not a `DataFrame`: - +Here are some more examples of materialising a bedGraph file into other data structures: ```julia using FileIO, BedgraphFiles, DataTables, IndexedTables, Gadfly @@ -69,10 +64,10 @@ dt = DataTable(load("data.bedgraph")) it = IndexedTable(load("data.bedgraph")) # Plot directly with Gadfly -plot(load("data.bedgraph"), x=:a, y=:b, Geom.line) +plot(load("data.bedgraph"), xmin=:leftposition, xmax=:rightposition, y=:value, Geom.line) ``` -The following code saves any iterable table as a Bedgraph file: +The following code saves any compatible source as a bedGraph file: ```julia using FileIO, BedgraphFiles @@ -85,8 +80,7 @@ This will work as long as `it` is any of the types supported as sources in [Iter ### Using the pipe syntax -Both `load` and `save` also support the pipe syntax. For example, to load a Bedgraph file into a `DataFrame`, one can use the following code: - +Both `load` and `save` also support the pipe syntax. For example, to load a bedGraph file into a `DataFrame`, one can use the following code: ```julia using FileIO, BedgraphFiles, DataFrame @@ -94,24 +88,23 @@ df = load("data.bedgraph") |> DataFrame ``` To save an iterable table, one can use the following form: - ```julia using FileIO, BedgraphFiles, DataFrame -df = # Aquire a DataFrame somehow +df = # Aquire a DataFrame somehow. df |> save("output.bedgraph") ``` The `save` method returns the data provided or `Vector{Bedgraph.Record}`. This is useful when periodically saving your work during a sequence of operations. - ```julia records = some sequence of operations |> save("output.bedgraph") ``` -The pipe syntax is especially useful when combining it with [Query.jl](https://github.com/davidanthoff/Query.jl) queries. For example, one can easily load a Bedgraph file, pipe it into a query, then pipe it to the `save` function to store the results in a new file. - +The pipe syntax is especially useful when combining it with [Query.jl](https://github.com/davidanthoff/Query.jl) queries. For example, one can easily load a bedGraph file, pipe its data into a query, and then store the query result by piping it to the `save` function. ```julia using FileIO, BedgraphFiles, Query load("data.bedgraph") |> @filter(_.chrom == "chr19") |> save("data-chr19.bedgraph") ``` +## Acknowledgements +This package is largely -- if not completely -- inspired by the work of [David Anthoff](https://github.com/davidanthoff). Other influences are from the [BioJulia](https://github.com/BioJulia) community.