---
title: "nemoR quick start"
author: "Maciej Pietrzak"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 2
vignette: >
  %\VignetteIndexEntry{1. nemoR quick start}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Introduction

`nemoR` helps R users discover and fetch open-access files from the
Neuroscience Multi-Omic Archive (NeMO). The package is intended as a data-access
layer for neuroscience and single-cell genomics workflows: search NeMO by
biological metadata, build a reproducible manifest, inspect the planned
download, and then download files when ready.

This task-oriented vignette focuses on the parts of the workflow that are safe
to run during package checks. Examples that would download real NeMO data are
shown in unevaluated chunks.

## Installation

After CRAN release, install with:

```{r install-cran, eval=FALSE}
install.packages("nemoR")
```

For a local development install with browsable vignettes, use:

```{r install-local, eval=FALSE}
devtools::install("nemoR", build_vignettes = TRUE)
browseVignettes("nemoR")
```

Load the package after installation:

```{r load}
library(nemoR)
```

## Discover available metadata values

Facet helpers list values that can be used as search filters. These calls query
the NeMO portal, so the chunk handles temporary network failures without
stopping the vignette build.

```{r discover}
safe_portal_call <- function(expr) {
  tryCatch(
    expr,
    error = function(error) {
      message("NeMO portal query skipped: ", conditionMessage(error))
      NULL
    }
  )
}

species <- safe_portal_call(nemo_species())
if (!is.null(species)) {
  head(species)
}
```

```{r discover-file-formats}
formats <- safe_portal_call(nemo_file_formats(taxon = "house mouse", access = "open"))
if (!is.null(formats)) {
  head(formats)
}
```

## Search NeMO records

`nemo_search()` returns portal records and stores pagination metadata in an
attribute. The example asks for only one row to keep the query light.

```{r search}
results <- safe_portal_call(
  nemo_search(
    taxon = "house mouse",
    file_format = "h5ad",
    access = "open",
    target = "files",
    size = 1
  )
)

if (!is.null(results)) {
  results
  attr(results, "pagination")
}
```

## Build a reproducible manifest without downloading

A manifest records file identifiers, file names, formats, URLs, local paths,
query provenance, and download status. Here we use direct example URLs so the
chunk is fully local and reproducible.

```{r manifest}
manifest <- nemo_manifest_from_urls(
  urls = c(
    "https://example.com?file=sample-a.h5ad",
    "https://example.com?file=sample-b.h5ad"
  ),
  collection_id = "example-neuro-study"
)

manifest$size <- c(1024^2, 2 * 1024^2)
manifest
```

## Inspect a planned download

Before downloading, summarize the manifest size and file types.

```{r plan}
nemo_download_plan(manifest, max_size_gb = 1)
```

## Save and restore the manifest

Manifests are intended to be kept with an analysis so that the file list and
search provenance can be reproduced.

```{r write-read}
path <- tempfile(fileext = ".tsv")
nemo_write_manifest(manifest, path)
restored <- nemo_read_manifest(path)
restored[, c("collection_id", "file_name", "download_status")]
```

## Download when ready

Downloading is intentionally not run in this vignette. In an interactive
analysis, use a project-specific folder and keep the saved manifest. NeMO files
can be large, especially raw sequencing data, so inspect the download plan and
set `max_size_gb` deliberately before starting a transfer.

```{r download, eval=FALSE}
downloaded <- nemo_download(
  manifest,
  destdir = "nemo_downloads",
  max_size_gb = 5,
  verify_checksum = TRUE
)
```

The high-level helper can also search and preview a workflow without
downloading:

```{r fetch-dry-run, eval=FALSE}
preview <- nemo_fetch(
  destdir = "nemo_downloads",
  taxon = "house mouse",
  file_format = "h5ad",
  access = "open",
  max_files = 3,
  dry_run = TRUE
)

attr(preview, "download_plan")
```

## Session information

```{r session-info}
sessionInfo()
```