## ----setup, include=FALSE-----------------------------------------------------
knitr::opts_chunk$set(collapse=TRUE)

## ----schemes------------------------------------------------------------------
library(gdscloud)
gdsCloudSchemes()

## ----quickstart---------------------------------------------------------------
library(gdscloud)

# Open a GDS file from S3 — transparent via openfn.gds()
gds <- openfn.gds("s3://gds-stat/download/hapmap/hapmap_r23a.gds")
gds

table(read.gdsn(index.gdsn(gds, "chromosome")))

summary(read.gdsn(index.gdsn(gds, "position")))

closefn.gds(gds)

## ----keyring, eval=FALSE------------------------------------------------------
# # one-time, interactive: store the secret in the OS keychain
# keyring::key_set("gdscloud", "aws_secret_access_key")
# 
# # later, in a script: retrieve without exposing it in history
# gdsCloudConfigS3(
#     aws_access_key_id     = keyring::key_get("gdscloud", "aws_access_key_id"),
#     aws_secret_access_key = keyring::key_get("gdscloud", "aws_secret_access_key"),
#     region                = "us-east-1"
# )

## ----open-http-public, eval=FALSE---------------------------------------------
# gds <- gdsCloudOpen("https://example.com/path/to/file.gds")
# closefn.gds(gds)

## ----auth-http----------------------------------------------------------------
gdsCloudConfigHTTP(bearer_token = "your_bearer_token")

# URL-specific token for a private server
gdsCloudConfigHTTP(
    bearer_token = "token_for_private_server",
    url = "https://private.example.com/"
)

## ----open-http, eval=FALSE----------------------------------------------------
# gds <- gdsCloudOpen("https://private.example.com/data/file.gds")
# closefn.gds(gds)

## ----auth-s3------------------------------------------------------------------
gdsCloudConfigS3(
    aws_access_key_id = "your_key",
    aws_secret_access_key = "your_secret",
    region = "us-east-1"
)

## ----open-s3, eval=FALSE------------------------------------------------------
# gds <- gdsCloudOpen("s3://my-bucket/path/to/file.gds")
# # ... work with the file ...
# closefn.gds(gds)

## ----auth-gcs-----------------------------------------------------------------
gdsCloudConfigGCS(access_token = "your_oauth2_token")

## ----open-gcs, eval=FALSE-----------------------------------------------------
# gds <- gdsCloudOpen("gs://my-bucket/path/to/file.gds")
# closefn.gds(gds)

## ----auth-azure---------------------------------------------------------------
gdsCloudConfigAzure(
    account_name = "mystorageaccount",
    account_key = "base64encodedkey=="
)
# Or with SAS token:
gdsCloudConfigAzure(
    account_name = "mystorageaccount",
    sas_token = "sv=2021-06-08&ss=b&srt=co&sp=r..."
)

## ----open-azure, eval=FALSE---------------------------------------------------
# gds <- gdsCloudOpen("az://my-container/path/to/file.gds")
# closefn.gds(gds)

## ----auth-url-----------------------------------------------------------------
# Different keys for two S3 buckets
gdsCloudConfigS3(
    aws_access_key_id = "KEY_A",
    aws_secret_access_key = "SECRET_A",
    url = "s3://bucket-a/"
)
gdsCloudConfigS3(
    aws_access_key_id = "KEY_B",
    aws_secret_access_key = "SECRET_B",
    url = "s3://bucket-b/"
)

# You can also scope credentials to a sub-prefix within a bucket
gdsCloudConfigS3(
    aws_access_key_id = "KEY_SHARED",
    aws_secret_access_key = "SECRET_SHARED",
    url = "s3://bucket-a/shared/"
)

# Remove a previously registered URL-specific entry
gdsCloudConfigS3(url = "s3://bucket-a/")

## ----cache--------------------------------------------------------------------
# Set the default cache size for new streams (in MB)
gdsCloudCacheSize(128)

# Clear all cached data
gdsCloudCacheClear()

# Display cache statistics
gdsCloudCacheInfo()

# List all open cloud streams
gdsCloudList()

## ----seqarray, eval=FALSE-----------------------------------------------------
# library(SeqArray)
# library(gdscloud)
# 
# # Open a SeqArray GDS file from S3
# gds <- seqOpen("s3://gds-stat/download/1000g/2022/1kGP_high_coverage_Illumina.allchr.filtered.SNV_INDEL_SV_phased_panel.gds")
# gds
# ## File: s3://gds-stat/download/1000g/2022/1kGP_high_coverage_Illumina.allchr.filtered.SNV_INDEL_SV_phased_panel.gds (2.4G)
# ## +    [  ] *
# ## |--+ description   [  ] *
# ## |--+ sample.id   { Str8 3202 LZMA_ra(6.61%), 1.7K } *
# ## |--+ variant.id   { Int32 73554796 LZMA_ra(2.36%), 6.6M } *
# ## |--+ position   { Int32 73554796 LZMA_ra(27.9%), 78.4M } *
# ## |--+ chromosome   { Str8 73554796 LZMA_ra(0.01%), 25.3K } *
# ## |--+ allele   { Str8 73554796 LZMA_ra(15.8%), 51.4M } *
# ## |--+ genotype   [  ] *
# ## |  |--+ data   { Bit2 2x3202x73554796 LZMA_ra(1.77%), 1.9G } *
# ## |  |--+ extra.index   { Int32 3x0 LZMA_ra, 18B } *
# ## |  \--+ extra   { Int16 0 LZMA_ra, 18B }
# ## |--+ phase   [  ]
# ## |  |--+ data   { Bit1 3202x73554796 LZMA_ra(0.01%), 4.1M } *
# ## |  |--+ extra.index   { Int32 3x0 LZMA_ra, 18B } *
# ## |  \--+ extra   { Bit1 0 LZMA_ra, 18B }
# ## |--+ annotation   [  ]
# ## |  |--+ id   { Str8 73554796 LZMA_ra(17.2%), 186.3M } *
# ## |  |--+ qual   { Float32 73554796 LZMA_ra(0.01%), 42.0K } *
# ## |  |--+ filter   { Int32,factor 73554796 LZMA_ra(0.01%), 42.0K } *
# ## |  |--+ info   [  ]
# ## |  |  |--+ AF   { Float32 73554796 LZMA_ra(23.6%), 66.3M } *
# ## |  |  |--+ AC   { Int32 73554796 LZMA_ra(22.3%), 62.5M } *
# ## |  |  |--+ CM   { Float32 73554796 LZMA_ra(6.08%), 17.1M } *
# ## |  |  |--+ AN   { Int32 73554796 LZMA_ra(0.01%), 42.0K } *
# ## |  |  \--+ SVTYPE   { Str8 73554796 LZMA_ra(0.33%), 240.0K } *
# ## |  \--+ format   [  ]
# ## \--+ sample.annotation   [  ]
# 
# seqSummary(gds)
# ## File: s3://gds-stat/download/1000g/2022/1kGP_high_coverage_Illumina.allchr.filtered.SNV_INDEL_SV_phased_panel.gds
# ## Format Version: v1.0
# ## Reference: unknown
# ## Ploidy: 2
# ## Number of samples: 3,202
# ## Number of variants: 73,554,796
# ## Chromosomes:
# ##     chr1 : 5759060, chr2 : 6088598, chr3 : 4983185, chr4 : 4875465, chr5 : 4536819, chr6 : 4315217
# ##     chr7 : 4137254, chr8 : 3886222, chr9 : 3165513, chr10: 3495473, chr11: 3423341, chr12: 3332788
# ##     chr13: 2509179, chr14: 2290400, chr15: 2109285, chr16: 2362361, chr17: 2073624, chr18: 1963845
# ##     chr19: 1670692, chr20: 1644384, chr21: 1002753, chr22: 1066557, chrX : 2862781
# ## ...
# 
# seqClose(gds)

## ----pkg, echo=FALSE----------------------------------------------------------
library(gdscloud, quietly=TRUE)

## ----session------------------------------------------------------------------
sessionInfo()