Simplify README (#14)

* Update README.md * Update README.md * Copy changes to README.qmd * Render README * Update CHANGELOG --------- Co-authored-by: Luke Zappia <[email protected]>
laminlabs · Oct 7, 2024 · 384b6d7 · 384b6d7
1 parent f20f977
commit 384b6d7
Show file tree

Hide file tree

Showing 3 changed files with 47 additions and 66 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,10 @@
   - Linting action.
   - Commands for roxygenizing (`/document`) and restyling the source code (`/style`).
 
+## MINOR CHANGES
+
+* Update `README` with new set up instructions and simplify (PR #14)
+
 ## BUG FIXES
 
 * Fixed the parsing of the env files in `~/.lamin` due to changes in the lamindb-setup Python package (PR #12).

diff --git a/README.md b/README.md
@@ -1,51 +1,44 @@
-# LaminDB interface in R
+# LaminR: Work with LaminDB instances in R
 
 
+<!-- The README.md file is created by rendering README.qmd using `quarto render README.qmd`. -->
+<!-- DO NOT edit README.md directly, instead all changes should be made to README.qmd. -->
 <!-- badges: start -->
 
 [![R-CMD-check](https://github.com/laminlabs/laminr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/laminlabs/laminr/actions/workflows/R-CMD-check.yaml)
 <!-- badges: end -->
 
-This package provides an interface to the LaminDB database. It allows
-you to query the database and download data from it.
+This package allows you to query and download data from LaminDB
+instances.
 
-## Installation
+## Setup
 
-You can install the development version from GitHub with:
+Install the development version from GitHub:
 
 ``` r
 # install.packages("remotes")
 remotes::install_github("laminlabs/laminr")
 ```
 
-## Set up environment
-
-For this package to work, we first need to run the following commands in
-the terminal:
+Install the Lamin CLI and authenticate:
 
 ``` bash
-pip install lamindb
+pip install lamin-cli
 lamin login
-lamin load laminlabs/cellxgene
 ```
 
 ## Usage
 
+Load the library
+
 ``` r
 library(laminr)
 ```
 
-## Instance
-
-### Connect to a LaminDB instance
+## Database instance
 
 ``` r
 db <- connect("laminlabs/cellxgene")
-```
-
-### Print a LaminDB instance
-
-``` r
 db
 ```
 
@@ -74,7 +67,7 @@ db
         .module_classes: list
         .settings: InstanceSettings, R6
 
-### Get module
+### Schema module
 
 ``` r
 db$get_module("core")
@@ -138,7 +131,7 @@ db$bionty
         .module_name: bionty
         .registry_classes: list
 
-## Registry
+### Registry
 
 ``` r
 db$Artifact
@@ -192,17 +185,12 @@ db$bionty$CellLine
         .record_class: R6ClassGenerator
         .registry_name: cellline
 
-## Record
+### Record
 
-### Get artifact
+#### Get artifact
 
 ``` r
 artifact <- db$Artifact$get("KBW89Mf7IGcekja2hADu")
-```
-
-### Print artifact
-
-``` r
 artifact
 ```
 
@@ -286,7 +274,7 @@ artifact
         .registry: Registry, R6
         get_value: function (key) 
 
-### Print simple fields
+#### Print simple fields
 
 ``` r
 artifact$id
@@ -306,7 +294,7 @@ artifact$key
 
     [1] "cell-census/2024-07-01/h5ads/fe52003e-1460-4a65-a213-2bb1a508332f.h5ad"
 
-### Print related fields
+#### Print related fields
 
 ``` r
 artifact$storage
@@ -467,7 +455,7 @@ artifact$experimental_factors
         .registry: Registry, R6
         get_value: function (key) 
 
-### Cache artifact
+### Download and cache an artifact
 
 > [!NOTE]
 >
@@ -479,9 +467,9 @@ artifact$cache()
 
     Warning: Data is missing expected fields: run_id, created_by_id
 
-    ℹ 's3://cellxgene-data-public/cell-census/2024-07-01/h5ads/fe52003e-1460-4a65-a213-2bb1a508332f.h5ad' already exists at '/home/rcannood/.cache/lamindb/cellxgene-data-public/cell-census/2024-07-01/h5ads/fe52003e-1460-4a65-a213-2bb1a508332f.h5ad'
+    ℹ 's3://cellxgene-data-public/cell-census/2024-07-01/h5ads/fe52003e-1460-4a65-a213-2bb1a508332f.h5ad' already exists at '/home/luke/.cache/lamindb/cellxgene-data-public/cell-census/2024-07-01/h5ads/fe52003e-1460-4a65-a213-2bb1a508332f.h5ad'
 
-### Load artifact
+### Load an artifact
 
 > [!NOTE]
 >
@@ -493,7 +481,7 @@ artifact$load()
 
     Warning: Data is missing expected fields: run_id, created_by_id
 
-    ℹ 's3://cellxgene-data-public/cell-census/2024-07-01/h5ads/fe52003e-1460-4a65-a213-2bb1a508332f.h5ad' already exists at '/home/rcannood/.cache/lamindb/cellxgene-data-public/cell-census/2024-07-01/h5ads/fe52003e-1460-4a65-a213-2bb1a508332f.h5ad'
+    ℹ 's3://cellxgene-data-public/cell-census/2024-07-01/h5ads/fe52003e-1460-4a65-a213-2bb1a508332f.h5ad' already exists at '/home/luke/.cache/lamindb/cellxgene-data-public/cell-census/2024-07-01/h5ads/fe52003e-1460-4a65-a213-2bb1a508332f.h5ad'
 
     AnnData object with n_obs × n_vars = 51552 × 36398
         obs: 'donor_id', 'Predicted_labels_CellTypist', 'Majority_voting_CellTypist', 'Manually_curated_celltype', 'assay_ontology_term_id', 'cell_type_ontology_term_id', 'development_stage_ontology_term_id', 'disease_ontology_term_id', 'self_reported_ethnicity_ontology_term_id', 'is_primary_data', 'organism_ontology_term_id', 'sex_ontology_term_id', 'tissue_ontology_term_id', 'suspension_type', 'tissue_type', 'cell_type', 'assay', 'disease', 'organism', 'sex', 'tissue', 'self_reported_ethnicity', 'development_stage', 'observation_joinid'

diff --git a/README.qmd b/README.qmd
@@ -1,64 +1,58 @@
 ---
-title: LaminDB interface in R
+title: "LaminR: Work with LaminDB instances in R"
 format: gfm
 ---
 
+<!-- The README.md file is created by rendering README.qmd using `quarto render README.qmd`. -->
+<!-- DO NOT edit README.md directly, instead all changes should be made to README.qmd. -->
+
+
 <!-- badges: start -->
 [![R-CMD-check](https://github.com/laminlabs/laminr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/laminlabs/laminr/actions/workflows/R-CMD-check.yaml)
 <!-- badges: end -->
 
-This package provides an interface to the LaminDB database. It allows you to query the database and download data from it.
+This package allows you to query and download data from LaminDB instances.
 
-## Installation
+## Setup
 
-You can install the development version from GitHub with:
+Install the development version from GitHub:
 
 ```R
 # install.packages("remotes")
 remotes::install_github("laminlabs/laminr")
 ```
 
-## Set up environment
-
-
-For this package to work, we first need to run the following commands in the terminal:
+Install the Lamin CLI and authenticate:
 
 ```bash
-pip install lamindb
+pip install lamin-cli
 lamin login
-lamin load laminlabs/cellxgene
 ```
 
 ## Usage
 
+Load the library
+
 ```{r setup}
 library(laminr)
 ```
 
-## Instance
-
-### Connect to a LaminDB instance
+## Database instance
 
 ```{r connect}
 db <- connect("laminlabs/cellxgene")
-```
-
-
-### Print a LaminDB instance
-
-```{r print_instance}
 db
 ```
 
-### Get module
+### Schema module
 
 ```{r get_module}
 db$get_module("core")
 
 db$bionty
 ```
 
-## Registry
+### Registry
 
 ```{r get_artifact_registry}
 db$Artifact
@@ -68,21 +62,16 @@ db$Artifact
 db$bionty$CellLine
 ```
 
-## Record
+### Record
 
-### Get artifact
+#### Get artifact
 
 ```{r get_artifact}
 artifact <- db$Artifact$get("KBW89Mf7IGcekja2hADu")
-```
-
-### Print artifact
-
-```{r print_artifact}
 artifact
 ```
 
-### Print simple fields
+#### Print simple fields
 
 ```{r print_simple_fields}
 artifact$id
@@ -92,7 +81,7 @@ artifact$uid
 artifact$key
 ```
 
-### Print related fields
+#### Print related fields
 
 ```{r print_related_fields}
 artifact$storage
@@ -102,7 +91,7 @@ artifact$created_by
 artifact$experimental_factors
 ```
 
-### Cache artifact
+### Download and cache an artifact
 
 :::{.callout-note}
 Only S3 storage is supported at the moment.
@@ -112,7 +101,7 @@ Only S3 storage is supported at the moment.
 artifact$cache()
 ```
 
-### Load artifact
+### Load an artifact
 
 :::{.callout-note}
 Only S3 storage and AnnData accessors are supported at the moment.