README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = ""
)
library(neurobase)
library(dplyr)
library(tidyr)
library(readr)
```

# Multiple Sclerosis Lesion Data

The data in this repository is from the Laboratory of Imaging Technologies (http://lit.fe.uni-lj.si/tools.php?lang=eng).

## Cross-sectional data

The cross-sectional data is from the "3D MR image database of Multiple Sclerosis patients with white matter lesion segmentations" section of the website.  

The database is released under the Creative-Commons 
Attribution (CC-BY) license. Please cite the references 
below in any published work that uses this database.

![](https://mirrors.creativecommons.org/presskit/buttons/88x31/svg/by.svg)

### References 
The data is described in:
Lesjak, Žiga, et al. "A novel public MR image dataset of multiple sclerosis patients with lesion segmentations based on multi-rater consensus." Neuroinformatics (2017): 1-13.

### Demographics

```{r, echo=FALSE, message=FALSE}
cs_demog = read_csv("cross_sectional/patient_info.csv")
remove_na = function(x) {
  x[ x %in% "N/A"] = NA
  x
}
cs_demog = rename(cs_demog, id = patient_id)
cs_demog$id = sprintf("patient%02.0f", cs_demog$id)
cs_demog$ms_type = remove_na(cs_demog$ms_type)
cs_demog$edss = remove_na(cs_demog$edss)
cs_demog$criteria = remove_na(cs_demog$criteria)
cs_demog$edss = as.numeric(cs_demog$edss)

cn_order = c("id", "age", "sex", "ms_type")
cn = colnames(cs_demog)
in_order = cn %in% cn_order
cn = cn[ c(which(in_order), which(!in_order)) ]
cs_demog = cs_demog[, cn]

save(cs_demog, file = "cs_demog.rda", compress = "xz")
knitr::kable(cs_demog)
```

### Raw Data

```{r, echo=FALSE, message=FALSE}
x = list.files(
  path = "cross_sectional/raw", pattern = ".nii.gz", 
  recursive = TRUE, full.names = TRUE)
bn = basename(dirname(x))
x = x[grepl("patient", bn)]
mods = nii.stub(x, bn = TRUE)
mods = recode(mods, "consensus_gt" = "Gold_Standard",
       T1W = "T1", T1WKS = "T1Post", T2W = "T2")
df = tibble(file = x, mod = mods, id = basename(dirname(x)))
cs_raw = as.data.frame(df)

save(cs_raw, file = "cs_raw.rda", compress = "xz")
df = df %>%
  mutate(file = paste0("[", mod, "](", file, ")"))
df = spread(df, key = mod, value = file)
knitr::kable(df, col.names = rep("", ncol(df)))
```


### Slightly Processed/Coregistered Data

These images were co-registered to the FLAIR and bias corrected and include a brain mask (in the FLAIR space.)
```{r, echo=FALSE, message=FALSE}
x = list.files(
  path = "cross_sectional/coregistered/", pattern = ".nii.gz", 
  recursive = TRUE, full.names = TRUE)
mods = nii.stub(x, bn = TRUE)
mods = recode(mods, "consensus_gt" = "Gold_Standard",
              brainmask = "Brain_Mask",
       T1W = "T1", T1WKS = "T1Post", T2W = "T2")
df = tibble(file = x, mod = mods, id = basename(dirname(x)))
cs_coreg = as.data.frame(df)
save(cs_coreg, file = "cs_coreg.rda", compress = "xz")
df = df %>%
  mutate(file = paste0("[", mod, "](", file, ")"))
df = spread(df, key = mod, value = file)
knitr::kable(df, col.names = rep("", ncol(df)))
```


### Processed + Resampled

These images were are the slightly processed data, but resampled to 1x1x1mm isotropic voxel sizes.  The images were interpolated using a linear interpolator and the binary images (mask and brain mask) were done using a nearest neighbor interpolator.

```{r, echo=FALSE, message=FALSE}
x = list.files(
  path = "cross_sectional/coregistered_resampled/", pattern = ".nii.gz", 
  recursive = TRUE, full.names = TRUE)
mods = nii.stub(x, bn = TRUE)
mods = recode(mods, "consensus_gt" = "Gold_Standard",
              brainmask = "Brain_Mask",
       T1W = "T1", T1WKS = "T1Post", T2W = "T2")
df = tibble(file = x, mod = mods, id = basename(dirname(x)))
df = df %>%
  mutate(file = paste0("[", mod, "](", file, ")"))
df = spread(df, key = mod, value = file)
knitr::kable(df, col.names = rep("", ncol(df)))
```


### Process, Registered to MNI

These images were are the processed data, and registered to an MNI template.  The images were processed using the following methodology:

1. N4 bias field correction
2. Neck removal
3. Reduced the dimensions of the image to non-zero images.
4. Winsorization using the 99.9th percentile
6. Registration to the FLAIR image.
7. Brain extraction using MALF.
8. N4 bias field correction on the brain only.
9. Registration to the MNI brain template

```{r, echo=FALSE, message=FALSE}
x = list.files(
  path = "cross_sectional/MNI", pattern = ".nii.gz", 
  recursive = TRUE, full.names = TRUE)
mods = nii.stub(x, bn = TRUE)
mods = sub("_N4.*", "", mods)
mods = recode(mods, "GOLD_STANDARD" = "Gold_Standard",
              brainmask = "Brain_Mask",
       T1 = "T1", T1POST = "T1Post", T2 = "T2")
df = tibble(file = x, mod = mods, id = basename(dirname(x)))
df = df %>%
  mutate(file = paste0("[", mod, "](", file, ")"))
df = spread(df, key = mod, value = file)
knitr::kable(df, col.names = rep("", ncol(df)))
```


## Longitudinal data

The longitudinal data is from the "Longitudinal MR image database of Multiple Sclerosis patients with white matter lesion change segmentation" section of the website.  

This archive contains longitudinal Magnetic Resonance (MR) images of patients with Multiple Sclerosis (MS) with corresponding
ground truth segmentations of white matter lesion changes. Each patient has been imaged twice on two separate occasions. The
images are grouped intro folders for each of the patients. 

The database is released under the Creative-Commons 
Attribution (CC-BY) license. Please cite the references 
below in any published work that uses this database.

![](https://mirrors.creativecommons.org/presskit/buttons/88x31/svg/by.svg)

### Description
This archive contains longitudinal Magnetic Resonance (MR) images 
of Multiple Sclerosis (MS) patients with corresponding ground 
truth segmentations of white matter lesion changes. Each patient 
has been imaged twice on two separate occasions. The images are 
grouped into folders for each of the patients. Each patient's 
folder consists of:

- Co-registered and N4 corrected T1-weighted, T2-weighted and FLAIR images for both MR studies 
- Brain mask 
- White matter lesion change mask
- RAW images in their original space 
- Intra-study transform parameters and transform parameters from RAW to common space

### Demographics

```{r, echo=FALSE, message=FALSE}
long_demog = read_csv("longitudinal/patient_info.csv")
long_demog = rename(long_demog, id = patient_id)
long_demog$id = sprintf("patient%02.0f", long_demog$id)
cn = colnames(long_demog)
in_order = cn %in% cn_order
cn = cn[ c(which(in_order), which(!in_order)) ]
long_demog = long_demog[, cn]

save(long_demog, file = "long_demog.rda", compress = "xz")
knitr::kable(long_demog)
```

### Raw Data

```{r, echo=FALSE, message=FALSE}
x = list.files(
  path = "longitudinal/raw", pattern = ".nii.gz", 
  recursive = TRUE, full.names = TRUE)
x = x[ !grepl("gt[.]nii", x)]
mods = nii.stub(x, bn = TRUE)
mods = gsub("study\\d_", "", mods)
mods = recode(mods, 
              "gt" = "Gold_Standard",
       T1W = "T1", T1WKS = "T1Post", T2W = "T2")
df = tibble(file = x, mod = mods, 
                id = basename(dirname(x)),
                study = sub(".*study(\\d).*", "\\1", x))
df = df %>% 
  mutate(Gold_Standard = file.path(dirname(file), "gt.nii.gz"))
long_raw = as.data.frame(df)
save(long_raw, file = "long_raw.rda", compress = "xz")
df = df %>%
  mutate(file = paste0("[", mod, "](", file, ")"),
         Gold_Standard = paste0("[Gold_Standard](", Gold_Standard, ")"))
df = spread(df, key = mod, value = file)
knitr::kable(df, col.names = rep("", ncol(df)))
```


### Slightly Processed/Coregistered Data

```{r, echo=FALSE, message=FALSE}
x = list.files(
  path = "longitudinal/coregistered/", pattern = ".nii.gz", 
  recursive = TRUE, full.names = TRUE)
x = x[ !grepl("(gt|brainmask)[.]nii", x)]
mods = nii.stub(x, bn = TRUE)
mods = gsub("study\\d_", "", mods)
mods = recode(mods, 
              "gt" = "Gold_Standard",
              brainmask = "Brain_Mask",
       T1W = "T1", T1WKS = "T1Post", T2W = "T2")
df = tibble(file = x, mod = mods, 
                id = basename(dirname(x)),
                study = sub(".*study(\\d).*", "\\1", x))
df = df %>% 
  mutate(Gold_Standard = file.path(dirname(file), "gt.nii.gz"),
         Brain_Mask = file.path(dirname(file), "brainmask.nii.gz"))
long_coreg = as.data.frame(df)
save(long_coreg, file = "long_coreg.rda", compress = "xz")
df = df %>%
  mutate(file = paste0("[", mod, "](", file, ")"),
         Gold_Standard = paste0("[Gold_Standard](", Gold_Standard, ")"),
         Brain_Mask = paste0("[Brain_Mask](", Brain_Mask, ")"))
df = spread(df, key = mod, value = file)
knitr::kable(df, col.names = rep("", ncol(df)))
```

### References 
The data is described in:
Lesjak, Žiga, Franjo Pernuš, Boštjan Likar, and Žiga Špiclin. "Validation of White Matter Lesion Change Detection Methods on a Novel Publicly Available MRI Image Database." Neuroinformatics (2016): 1-18.