Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation for JLD2 I/O #3365

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions docs/src/man/importing_and_exporting.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,56 @@ As you can see the code required to transform `iris` into a proper input to the
format is not easy. Therefore CSV.jl is the preferred package to write CSV files
for data stored in data frames.

## JLD2 Files

JLD2 is a HDF5-compatible file format that allows reading and writing data frames.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
JLD2 is a HDF5-compatible file format that allows reading and writing data frames.
[JLD2](https://github.com/JuliaIO/JLD2.jl) is a HDF5-compatible file format that allows
reading and writing data frames (and any Julia object).

A valuable feature of JLD2 format is that it preserves custom column types of the stored data frame.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A valuable feature of JLD2 format is that it preserves custom column types of the stored data frame.
A valuable feature of the JLD2 format is that it preserves custom column types of the stored data frame.


The `save` and `load` functions, provided by FileIO.jl, allow to read/write a data frame from/to a JLD2 file.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `save` and `load` functions, provided by FileIO.jl, allow to read/write a data frame from/to a JLD2 file.
The `save` and `load` functions, provided by [FileIO.jl](https://github.com/JuliaIO/FileIO.jl/),
provides convenience functions to read/write objects from/to a JLD2 file.


A data frame can be saved as a JLD2 file output.jld2 using

Comment on lines +123 to +124
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A data frame can be saved as a JLD2 file output.jld2 using

If you have not used the FileIO and JLD2 packages before then you may need to install it first:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If you have not used the FileIO and JLD2 packages before then you may need to install it first:
If you have not used the FileIO and JLD2 packages before then you may need to install them first:

```julia
using Pkg;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
using Pkg;
using Pkg

Pkg.add("FileIO")
Pkg.add("JLD2")
Comment on lines +128 to +129
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will typically be faster:

Suggested change
Pkg.add("FileIO")
Pkg.add("JLD2")
Pkg.add(["FileIO", "JLD2"])

```

The FileIO and JLD2 functions are not loaded automatically and must be imported into the session.
```julia
using FileIO
alex-s-gardner marked this conversation as resolved.
Show resolved Hide resolved
using JLD2
Comment on lines +134 to +135
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
using FileIO
using JLD2
using FileIO, JLD2

```

We can now create a simple data frame and save it as a jld2 file using `save`. `save`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
We can now create a simple data frame and save it as a jld2 file using `save`. `save`
We can now create a simple data frame and save it as a JLD2 file using `save`. `save`

accepts an AbstractDict yielding the key/value pairs, where the key is a string representing
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
accepts an AbstractDict yielding the key/value pairs, where the key is a string representing
accepts an `AbstractDict` yielding the key/value pairs, where the key is a string representing

the name of the dataset and the value represents its contents:

```julia
df = DataFrame(x=1, y=2)
save("output.jld2", Dict("df" => df))
```

A jld2 file can be read in using `load`. If `load` is called with a single dataset name,
load returns the contents of that dataset from the file:
Comment on lines +147 to +148
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A jld2 file can be read in using `load`. If `load` is called with a single dataset name,
load returns the contents of that dataset from the file:
A JLD2 file can be read in using `load`. If `load` is called with a single dataset name,
it returns the contents of that dataset from the file:

```julia
df = load("output.jld2", "df")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
df = load("output.jld2", "df")
julia> df = load("output.jld2", "df")

1×2 DataFrame
Row │ x y
│ Int64 Int64
─────┼──────────────
1 │ 1 2
```

If `load` is called with a filename argument only, the load function loads all datasets
from the given file into a Dict:
Comment on lines +158 to +159
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If `load` is called with a filename argument only, the load function loads all datasets
from the given file into a Dict:
If `load` is called with a filename argument only, it loads all objects
from the given file into a `Dict`:

```julia
df = load("output.jld2")
Dict{String, Any} with 1 entry:
"df" => 1×2 DataFrame…
Comment on lines +161 to +163
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
df = load("output.jld2")
Dict{String, Any} with 1 entry:
"df" => 1×2 DataFrame…
julia> dict = load("output.jld2")
Dict{String, Any} with 1 entry:
"df" => 1×2 DataFrame…
julia> df = dict.df
1×2 DataFrame
Row │ x y
│ Int64 Int64
─────┼──────────────
1 │ 1 2

```

## Other formats

Other data formats are supported for reading and writing in the following packages
Expand Down
Loading