Merge pull request #124 from JuliaML/cl/docs4

change dataset[] to dataset[:]

Author: CarloLucibello

README.md

@@ -16,7 +16,7 @@ Its functionality is built on top of the package
 ## Available Datasets
 
 **Warning**: this package is under heavy redesign. The link belows point to the documentation for the yet to be released version. 
-For the tagged version instead, please consult the [stable docs](https://JuliaML.github.io/MLDatasets.jl/stable) 
+For the tagged version instead, please consult the [stable docs](https://JuliaML.github.io/MLDatasets.jl/stable).
 
 Datasets are grouped into different categories. Click on the links below for a full list of datasets available in each category.
 

docs/src/datasets/graphs.md

@@ -1,5 +1,10 @@
 # Graphs Datasets
 
+A collection of datasets with an underlying graph structure.
+Some of these datasets contain a single graph, that can be accessed
+with `dataset[:]` or `dataset[1]`. Others contain many graphs, 
+accessed through `dataset[i]`. Graphs are represented by the [`MLDatasets.Graph`](@ref) type.
+
 ## Index
 
 ```@index

docs/src/index.md

@@ -38,7 +38,7 @@ Where possible, those types share a common interface (fields and methods).
 
 Once a dataset has been instantiated, e.g. by `dataset = MNIST()`,  
 an observation `i` can be retrieved using the indexing syntax `dataset[i]`.
-By indexing with no arguments, `dataset[]`, the whole set of observations is collected.
+By indexing with no arguments, `dataset[:]`, the whole set of observations is collected.
 The total number of observations is given by `length(dataset)`.
 
 For example you can load the training set of the [`MNIST`](@ref)
@@ -60,17 +60,17 @@ julia> trainset[1]  # return first observation as a NamedTuple
 (features = Float32[0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0; … ; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0], 
  targets = 5)
 
-julia> X_train, y_train = trainset[] # return all observations
+julia> X_train, y_train = trainset[:] # return all observations
 (features = [0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0; … ; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0;;; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0; … ; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0;;; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0; … ; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0;;; … ;;; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0; … ; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0;;; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0; … ; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0;;; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0; … ; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0], 
  targets = [5, 0, 4, 1, 9, 2, 1, 3, 1, 4  …  9, 2, 9, 5, 1, 8, 3, 5, 6, 8])
 
 julia> summary(X_train)
 "28×28×60000 Array{Float32, 3}"
 ```
 
-Input features are commonly denoted by `features`, while classification labels or regression targets are denoted by `targets`.
+Input features are commonly denoted by `features`, while classification labels and regression targets are denoted by `targets`.
 
-```julia
+```julia-repl
 julia> iris = Iris()
 dataset Iris:
   metadata    =>    Dict{String, Any} with 4 entries

src/abstract_datasets.jl

@@ -4,13 +4,13 @@
 Super-type from which all datasets in MLDatasets.jl inherit.
 
 Implements the following functionality:
-- `getobs(d)` and `getobs(d, i)` falling back to `d[]` and `d[i]` 
+- `getobs(d)` and `getobs(d, i)` falling back to `d[:]` and `d[i]` 
 - Pretty printing.
 """
 abstract type AbstractDataset <: AbstractDataContainer end
 
 
-MLUtils.getobs(d::AbstractDataset) = d[]
+MLUtils.getobs(d::AbstractDataset) = d[:]
 MLUtils.getobs(d::AbstractDataset, i) = d[i]
 
 function Base.show(io::IO, d::D) where D <: AbstractDataset
@@ -45,7 +45,8 @@ end
 _summary(x) = x
 _summary(x::Symbol) = ":$x"
 _summary(x::Union{Dict, AbstractArray, DataFrame}) = summary(x)
-_summary(x::Union{Tuple, NamedTuple}) = map(summary, x)
+_summary(x::Union{Tuple, NamedTuple}) = map(_summary, x)
+_summary(x::BitVector) = "$(count(x))-trues BitVector"
 
 """
     SupervisedDataset <: AbstractDataset
@@ -57,11 +58,10 @@ a `features` and a `targets` fields.
 abstract type SupervisedDataset <: AbstractDataset end
 
 
-
 Base.length(d::SupervisedDataset) = numobs((d.features, d.targets))
 
 # We return named tuples
-Base.getindex(d::SupervisedDataset) = getobs((; d.features, d.targets)) 
+Base.getindex(d::SupervisedDataset, ::Colon) = getobs((; d.features, d.targets))
 Base.getindex(d::SupervisedDataset, i) = getobs((; d.features, d.targets), i)
 
 """
@@ -75,7 +75,7 @@ abstract type UnsupervisedDataset <: AbstractDataset end
 
 Base.length(d::UnsupervisedDataset) = numobs(d.features)
 
-Base.getindex(d::UnsupervisedDataset) = getobs(d.features) 
+Base.getindex(d::UnsupervisedDataset, ::Colon) = getobs(d.features)
 Base.getindex(d::UnsupervisedDataset, i) = getobs(d.features, i)
 
 
@@ -97,7 +97,7 @@ const FIELDS_SUPERVISED_TABLE = """
 
 const METHODS_SUPERVISED_TABLE = """
 - `dataset[i]`: Return observation(s) `i` as a named tuple of features and targets. 
-- `dataset[]`: Return all observations as a named tuple of features and targets.
+- `dataset[:]`: Return all observations as a named tuple of features and targets.
 - `length(dataset)`: Number of observations.
 """
 
@@ -116,6 +116,6 @@ const FIELDS_SUPERVISED_ARRAY = """
 
 const METHODS_SUPERVISED_ARRAY = """
 - `dataset[i]`: Return observation(s) `i` as a named tuple of features and targets. 
-- `dataset[]`: Return all observations as a named tuple of features and targets.
+- `dataset[:]`: Return all observations as a named tuple of features and targets.
 - `length(dataset)`: Number of observations.
 """

src/datasets/graphs/citeseer.jl

@@ -27,7 +27,8 @@ The dataset is retrieved from Ref. [2].
 
 # References
 
-[1]: [Deep Gaussian Embedding of Graphs: Unsupervised Inductive Learning via Ranking](https://arxiv.org/abs/1707.03815)
+[1]: [Deep Gaussian Embedding of Graphs: Unsupervised Inductive Learning via Ranking](https://arxiv.org/abs/1707.03815) 
+ 
 [2]: [Planetoid](https://github.com/kimiyoung/planetoid)
 """
 struct CiteSeer <: AbstractDataset
@@ -41,9 +42,8 @@ function CiteSeer(; dir=nothing, reverse_edges=true)
 end
 
 Base.length(d::CiteSeer) = length(d.graphs) 
-Base.getindex(d::CiteSeer) = d.graphs[1]
-Base.getindex(d::CiteSeer, i) = getindex(d.graphs, i)
-
+Base.getindex(d::CiteSeer, ::Colon) = d.graphs[1]
+Base.getindex(d::CiteSeer, i) = d.graphs[i]
 
 
 # DEPRECATED in v0.6.0

src/datasets/graphs/cora.jl

@@ -46,6 +46,7 @@ doesn't consider all nodes.
 # References
 
 [1]: [Deep Gaussian Embedding of Graphs: Unsupervised Inductive Learning via Ranking](https://arxiv.org/abs/1707.03815)
+
 [2]: [Planetoid](https://github.com/kimiyoung/planetoid
 """
 struct Cora <: AbstractDataset
@@ -59,7 +60,7 @@ function Cora(; dir=nothing, reverse_edges=true)
 end
 
 Base.length(d::Cora) = length(d.graphs) 
-Base.getindex(d::Cora) = d.graphs[1]
+Base.getindex(d::Cora, ::Colon) = d.graphs[1]
 Base.getindex(d::Cora, i) = getindex(d.graphs, i)
 
 

src/datasets/graphs/karateclub.jl

@@ -1,9 +1,9 @@
 export KarateClub
 
 """
-    Zachary's Karate Club
+    KarateClub()
 
-The Karate Club dataset originally appeared in Ref [1].
+The Zachary's karate club dataset originally appeared in Ref [1].
 
 The network contains 34 nodes (members of the karate club).
 The nodes are connected by 78 undirected and unweighted edges.
@@ -18,8 +18,11 @@ One node per unique label is used as training data.
 # References
 
 [1]: [An Information Flow Model for Conflict and Fission in Small Groups](http://www1.ind.ku.dk/complexLearning/zachary1977.pdf)
+
 [2]: [Semi-supervised Classification with Graph Convolutional Networks](https://arxiv.org/abs/1609.02907)
+
 [3]: [PyTorch Geometric Karate Club Dataset](https://pytorch-geometric.readthedocs.io/en/latest/_modules/torch_geometric/datasets/karate.html#KarateClub)
+
 [4]: [NetworkX Zachary's Karate Club Dataset](https://networkx.org/documentation/stable/_modules/networkx/generators/social.html#karate_club_graph)
 """
 struct KarateClub
@@ -59,12 +62,12 @@ function KarateClub()
                 0, 0, 2, 2, 0, 0, 2, 0, 0, 2, 0, 0]
 
     node_data = (; labels_clubs, labels_comm) 
-    g = Graph(; num_nodes=34, num_edges=156, edge_index=(src, target), node_data)
+    g = Graph(; num_nodes=34, edge_index=(src, target), node_data)
 
     metadata = Dict{String, Any}()
     return KarateClub(metadata, [g])
 end
 
 Base.length(d::KarateClub) = length(d.graphs) 
-Base.getindex(d::KarateClub) = d.graphs[1]
-Base.getindex(d::KarateClub, i) = getindex(d.graphs, i)
+Base.getindex(d::KarateClub, ::Colon) = d.graphs[1]
+Base.getindex(d::KarateClub, i) = d.graphs[i]