---
title: "Getting Started with xnatR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with xnatR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE,
  message = FALSE,

  warning = FALSE
)
```

You have neuroimaging data sitting in an XNAT archive and you need to get it
into R — browse what's available, find specific sessions, and download scans
to disk. xnatR gives you a tidy, pipe-friendly interface to the XNAT REST API
so you can do all of that without leaving your R session.

## Connect and explore in 30 seconds

```{r quickstart}
library(xnatR)

client <- xnat_connect(
  base_url = "https://central.xnat.org",
  username = "myuser",
  password = "mypass",
  use_jsession = TRUE
)

list_projects(client = client)
#> ── XNAT Projects ──────────────────────────────
#> 42 projects
#> # A tibble: 42 × 3
#>    ID              name                    description
#>    <chr>           <chr>                   <chr>
#>  1 CENTRAL_OASIS   Central OASIS Project   Cross-sectional MRI…
#>  2 ABIDE           ABIDE                   Autism Brain Imaging…
#>    …
```

That's the pattern: **connect once, then use `list_*` functions to navigate
the data hierarchy.** Every function accepts an optional `client` argument; if
you omit it, xnatR falls back to a global session set up with
`authenticate_xnat()`.

## The XNAT data hierarchy

XNAT organises imaging data in a tree:

```
Project
└── Subject
    └── Experiment (imaging session)
        └── Scan (e.g., T1, BOLD, DWI)
            └── Resource (DICOM, NIFTI, …)
                └── Files
```

Each level has a corresponding `list_*()` function that returns a tibble.
You drill down by passing IDs from the level above.

## How do I find my project?

If you know the project ID, skip ahead. Otherwise, search by keyword:

```{r find-project}
search_projects("OASIS", client = client)
#> ── XNAT Projects ──────────────────────────────
#> 2 projects
#> # A tibble: 2 × 3
#>   ID              name                  description
#>   <chr>           <chr>                 <chr>
#> 1 CENTRAL_OASIS   Central OASIS Project Cross-sectional MRI…
#> 2 OASIS3          OASIS-3               Longitudinal MRI…
```

## Who is in the project?

```{r list-subjects}
subjects <- list_subjects("CENTRAL_OASIS", client = client)
subjects
#> ── XNAT Subjects ──────────────────────────────
#> Project: "CENTRAL_OASIS"
#> 416 subjects
#> # A tibble: 416 × 4
#>   ID         label    project         gender
#>   <chr>      <chr>    <chr>           <chr>
#> 1 OAS1_0001  OAS1_0001 CENTRAL_OASIS  F
#> 2 OAS1_0002  OAS1_0002 CENTRAL_OASIS  M
#>   …
```

For large projects, use `limit` and `offset` for pagination:

```{r paginate-subjects}
first_50 <- list_subjects("CENTRAL_OASIS", limit = 50, client = client)
next_50  <- list_subjects("CENTRAL_OASIS", limit = 50, offset = 50, client = client)
```

## What sessions exist?

`list_experiments()` returns sessions for a project. Pass `subject_id` to
scope to a single subject, or omit it to get everything:

```{r list-sessions}
# All sessions in the project
all_sessions <- list_experiments("CENTRAL_OASIS", client = client)

# Sessions for one subject
subj_sessions <- list_experiments(
  "CENTRAL_OASIS",
  subject_id = "OAS1_0001",
  client = client
)
subj_sessions
#> ── XNAT Experiments ───────────────────────────
#> Project: "CENTRAL_OASIS"
#> Subject: "OAS1_0001"
#> 2 experiments
#> # A tibble: 2 × 4
#>   ID          label        xsiType              date
#>   <chr>       <chr>        <chr>                 <chr>
#> 1 E00001      MR1          xnat:mrSessionData    2005-09-02
#> 2 E00002      MR2          xnat:mrSessionData    2006-11-18
```

Want the most recent sessions? `list_recent_sessions()` sorts by date and
lets you cap the count:

```{r recent-sessions}
recent <- list_recent_sessions("CENTRAL_OASIS", n = 5, client = client)
recent
```

## What scans are in a session?

```{r list-scans}
scans <- list_scans(
  project_id    = "CENTRAL_OASIS",
  subject_id    = "OAS1_0001",
  experiment_id = "E00001",
  client        = client
)
scans
#> ── XNAT Scans ─────────────────────────────────
#> 4 scans
#> # A tibble: 4 × 4
#>   ID    type        quality   frames
#>   <chr> <chr>       <chr>     <chr>
#> 1 1     T1          usable    176
#> 2 2     T2          usable    176
#> 3 3     BOLD        usable    132
#> 4 4     DWI         usable    72
```

## How do I download data?

### Download all scans from a session

```{r download-all}
download_files(
  project_id    = "CENTRAL_OASIS",
  subject_id    = "OAS1_0001",
  experiment_id = "E00001",
  dest_dir      = "~/Downloads",
  client        = client
)
#> ℹ Downloading to CENTRAL_OASIS_OAS1_0001_E00001_ALL_ALL.zip
#> ✔ Downloaded to ~/Downloads/CENTRAL_OASIS_OAS1_0001_E00001_ALL_ALL.zip
```

### Download specific scans or resource types

```{r download-specific}
# Just the T1 and BOLD scans
download_files(
  project_id    = "CENTRAL_OASIS",
  subject_id    = "OAS1_0001",
  experiment_id = "E00001",
  scan_id       = c("1", "3"),
  dest_dir      = "~/Downloads",
  client        = client
)

# Only NIFTI resources
download_files(
  project_id    = "CENTRAL_OASIS",
  subject_id    = "OAS1_0001",
  experiment_id = "E00001",
  resource      = "NIFTI",
  dest_dir      = "~/Downloads",
  client        = client
)
```

### Download an entire subject

`download_subject()` grabs every session for a subject:

```{r download-subject}
download_subject(
  project_id = "CENTRAL_OASIS",
  subject_id = "OAS1_0001",
  dest_dir   = "~/Downloads",
  client     = client
)
#> ℹ Downloading 2 experiments for subject "OAS1_0001"
#> ✔ Downloaded all data for subject "OAS1_0001"
```

### Download a session by experiment ID alone

If you already have the experiment ID (e.g., from a search), you don't need
the full project/subject/experiment triple:

```{r download-experiment}
download_experiment(
  experiment_id = "E00001",
  format        = "zip",
  dest_dir      = "~/Downloads",
  extract       = TRUE,
  client        = client
)
```

## Credential management

The examples above used `xnat_connect()` with explicit credentials. For
real work, you'll want to keep passwords out of your scripts.

**Environment variables** (best for CI and shared scripts):

```{r auth-envvar}
# In your .Renviron file:
# XNATR_HOST=https://central.xnat.org
# XNATR_USER=myuser
# XNATR_PASS=mypass

# Then just:
client <- xnat_connect()
```

**Config file** (best for interactive use on your own machine):

```{r auth-config}
initialize_config()
# Creates ~/.xnatR_config.yml — edit it with your credentials, then:
client <- xnat_connect()
```

**`.netrc` file** (if you already use one for curl/wget):

```
machine central.xnat.org login myuser password mypass
```

```{r auth-netrc}
client <- xnat_connect(base_url = "https://central.xnat.org")
```

For servers with self-signed SSL certificates, pass `ssl_verify = FALSE`.

## Clean up

Always log out when you're done, especially with JSESSION connections:

```{r logout}
xnat_logout(invalidate_session = TRUE, client = client)
```

## Next steps

- `vignette("workflows")` — common task recipes: batch downloads,
  finding recent sessions, searching by scan parameters
- `?xnat_search_builder` — the fluent search API for complex queries
- `?xnat_token_issue` — alias tokens for temporary or shared access