updating Parcellation docs

docs/src/index.md

@@ -13,69 +13,4 @@ In this package we implement two types:
 * [Parcellation](@ref parcellation)
 * [Connectome](@ref connectome)
 
-See their doc pages for more on how to work with and plot each type.
-<!-- 
-Connectomes.jl comes with a connectome and parcellation. The file path can be found 
-with the function: 
-
-```@example getting-started
-using JSServe # hide
-Page(exportable=true, offline=true) # hide
-using WGLMakie # hide
-
-using Connectomes
-
-connectome_path = Connectomes.connectome_path()
-```
-
-From this path, two datatypes can be loaded: a `Parcellation` or a `Connectome`. A 
-parcellation underlies a connectome, so let's start with that. By default, we use 
-the Desikan-Killiany-Tourville (DKT) atlas. A parcellation is simply a
-collection of `Regions`.
-
-```
-struct Parcellation
-    regions::Vector{Region}
-end
-```
-Where `Regions` comprise pertinent information relating to a given region.
-```
-struct Region
-    ID::Int                 # DKT region ID number
-    Label::String           # Region name
-    Region::String          # Cortical or Subcortical
-    Lobe::String            # Lobe the region belongs to
-    Hemisphere::String      # Hemisphere the region belongs to
-    x::Float64              # x coordinate 
-    y::Float64              # y coordinate
-    z::Float64              # z coordinate
-end
-```
-The parcellation can be loaded from the `connectome_path` in the following way.
-
-```@example getting-started
-parc = Parcellation(connectome_path)
-```
-
-`parc` can be numerically indexed to retrieve regions, either as a `Int`
-```@example getting-started
-parc[1]
-
-```
-or a `Vector{Int}`, which will return a new `Parcellation`.
-```@example getting-started
-parc[[1, 2, 3]]
-```
-
-If we load a `Makie` backend, we can conveniently plot the parcellation. Let's say, we 
-just want to plot the left side of the connectome. We can do the following.
-
-```@example getting-started
-using WGLMakie
-Makie.inline!(true) # hide
-
-left_parc = filter(x -> get_hemisphere(x) == "left", parc)
-
-plot_parc(left_parc; resolution=(500, 350), view=:left)
-```
- -->
+See their doc pages for more on how to work with and plot each type.

docs/src/parcellation.md

@@ -3,6 +3,10 @@
 
 One of the main components of a Connectome is the Parcellation, which comprises a list of regions over which fibre tracts are summarised. 
 
+```@docs
+Parcellation
+```
+
 By default we use the Desikan-Killiany-Tourville (DKT) atlas, provided as standard by FreeSurfer. The parcellation is included within the main connectome file that ships with Connectomes.jl. We can load it like so:
 ```@example getting-started
 using JSServe # hide
@@ -60,4 +64,18 @@ Makie.inline!(true) # hide
 left_parc = filter(x -> get_hemisphere(x) == "left", parc)
 
 plot_parc(left_parc; resolution=(500, 350), view=:left)
+```
+
+# API
+
+```@docs
+Region
+get_node_id
+get_label
+get_cortex 
+get_lobe
+get_hemisphere
+get_coords
+Base.getindex
+Base.length
 ```

src/Connectomes.jl

@@ -21,7 +21,7 @@ import SimpleWeightedGraphs: adjacency_matrix, degree_matrix, laplacian_matrix
 
 include("parcellation.jl")
 export Parcellation, Region
-export get_node_id, get_label, get_region, get_lobe, get_hemisphere, get_coords
+export get_node_id, get_label, get_cortex, get_lobe, get_hemisphere, get_coords
 
 include("graphs.jl")
 export Connectome

src/graphs.jl

@@ -11,15 +11,18 @@ Main type introduced by Connectomes.jl,
 
 ```julia
 struct Connectome
-    parc::DataFrame
-    graph::SimpleWeightedGraph{Int64, Float64}
-    n_matrix::Matrix{Float64}
-    l_matrix::Matrix{Float64}
+        parc::Parcellation
+        graph::SimpleWeightedGraph{Int64, Float64}
+        n_matrix::Matrix{Float64}
+        l_matrix::Matrix{Float64}
+        weight_function::Function
 end
 ```
-where `parc` is the parcellation atlas, graph is a 
+where `parc` is a `Parcellation`, `graph` is a 
 `SimpleWeightedGraph` encoding a weighted Connectome, `n_matrix` is 
-the length matrix and `l_matrix` is the length matrix.
+the length matrix and `l_matrix` is the length matrix and 
+`weight_function` defines the weighting of (n, l) that is used 
+to construct the graph. 
 
 # Example
 

src/parcellation.jl

@@ -1,38 +1,174 @@
+"""
+    Struct
+        ID::Int
+        Label::String
+        Cortex::String
+        Lobe::String
+        Hemisphere::String
+        x::Float64
+        y::Float64
+        z::Float64
+    end
+"""
 struct Region
     ID::Int
     Label::String
-    Region::String
+    Cortex::String
     Lobe::String
     Hemisphere::String
     x::Float64
     y::Float64
     z::Float64
 end
 
+"""
+    Parcellation(path::String)
+
+A `Parcellation` type containing information about the underlying parcellation used in a `Connectome`. 
+It is simply a collection of `Region` types. 
+```julia
+struct Parcellation
+    regions::Vector{Region}
+end
+```
+# Example 
+
+```julia
+julia> parc = Parcellation(Connectomes.connectome_path())
+Parcellation with 83 regions
+```
+"""
 struct Parcellation
     regions::Vector{Region}
 end
 
-function Parcellation(ids, labels, regions, lobes, hemispheres, xs, ys, zs)
-    Parcellation([Connectomes.Region(ids[i], labels[i], regions[i], lobes[i], hemispheres[i], xs[i], ys[i], zs[i])
+function Parcellation(ids, labels, cortex, lobes, hemispheres, xs, ys, zs)
+    Parcellation([Connectomes.Region(ids[i], labels[i], cortex[i], lobes[i], hemispheres[i], xs[i], ys[i], zs[i])
      for i in eachindex(ids)])
 end
 
 function Parcellation(path::String)
     Parcellation(load_parcellation(path)...)
 end
 
+"""
+    get_node_id(roi::Region)
+
+Return the `ID` of a `Region`. 
+
+# Example 
+
+```julia
+julia>get_node_id(parc[1])
+1
+```
+"""
 get_node_id(roi::Region) = roi.ID
+
+"""
+    get_label(roi::Region)
+
+Return the `Label` of a `Region`. 
+
+# Example 
+
+```julia
+julia>get_label(parc[1])
+"lateralorbitofrontal"
+```
+"""
 get_label(roi::Region) = roi.Label
-get_region(roi::Region) = roi.Region
+
+"""
+    get_cortex(roi::Region)
+
+Return the `Cortex` of a `Region`. 
+
+# Example 
+
+```julia
+julia>get_label(parc[1])
+""cortical""
+```
+"""
+get_cortex(roi::Region) = roi.Cortex
+
+
+"""
+    get_lobe(roi::Region)
+
+Return the `Lobe` of a `Region`. 
+
+# Example 
+
+```julia
+julia>get_lobe(parc[1])
+""frontal""
+```
+"""
 get_lobe(roi::Region) = roi.Lobe
+
+
+"""
+    get_hemisphere(roi::Region)
+
+Return the `Hemisphere` of a `Region`. 
+
+# Example 
+
+```julia
+julia>get_hemisphere(parc[1])
+""right""
+```
+"""
 get_hemisphere(roi::Region) = roi.Hemisphere
+
+
+"""
+    get_coords(roi::Region)
+    get_coords(parc::Parcellation)
+
+Return a `Vector{Float64}` of ``(x, y, z)`` coordinates of a `Region`.
+
+# Example 
+
+```julia
+>get_coords(parc[1])
+3-element Vector{Float64}:
+  25.00574653668548
+  33.4624935864546
+ -16.65079527963058
+```
+
+Return a `Matrix{Float64}` of coordinates for all `Regions` in the `Parcellation`.
+
+# Example
+
+```
+>get_coords(parc)
+83×3 Matrix{Float64}:
+ 25.0057  33.4625  -16.6508
+  ⋮   
+```
+"""
 get_coords(roi::Region) = [roi.x, roi.y, roi.z]
 
 function get_coords(parc::Parcellation)
-    transpose(reduce(hcat, get_coords.(parc)))
+    Array(transpose(reduce(hcat, get_coords.(parc))))
 end
 
+"""
+    Base.length(parc::Parcellation)
+
+Return the number of regions in the `Parcellation`
+
+# Example 
+
+```julia
+julia> length(parc)
+83
+```
+"""
 function Base.length(parc::Parcellation)
     length(parc.regions)
 end
@@ -45,6 +181,28 @@ function Base.show(io::IO, roi::Region)
     print(io, "Region $(roi.ID): $(roi.Hemisphere) $(roi.Label)")
 end
 
+"""
+    Base.getindex(parc::Parcellation, idx::Int)
+    Base.getindex(parc::Parcellation, idx::Vector{Int})
+
+Index the `Parcellation` by `idx::Int`` and return the corresponding `Region`
+
+# Example 
+
+```julia
+julia> parc[1]
+Region 1: right lateralorbitofrontal
+```
+
+Slice the `Parcellation` by into subregions given by the idxs.
+
+# Example 
+
+```julia
+julia> parc[[1, 2, 3]]
+Parcellation with 3 regions
+```
+"""
 function Base.getindex(parc::Parcellation, idx::Int)
     return parc.regions[idx]
 end