finished docs for data translators

brain-bican · Oct 4, 2024 · 2c4d144 · 2c4d144
1 parent 02c6d57
commit 2c4d144
Show file tree

Hide file tree

Showing 4 changed files with 79 additions and 21 deletions.
diff --git a/docs/genome_annotation.rst b/docs/genome_annotation.rst
@@ -64,6 +64,7 @@ Example 1: NCBI GFF3 file
 
 .. code-block:: bash
 
+    # Run gff2jsonld command
     $ bkbit gff2jsonld 'https://ftp.ncbi.nlm.nih.gov/genomes/all/annotation_releases/9823/106/GCF_000003025.6_Sscrofa11.1/GCF_000003025.6_Sscrofa11.1_genomic.gff.gz' > output.jsonld
 
 
@@ -72,4 +73,5 @@ Example 2: ENSEMBL GFF3 file
 
 .. code-block:: bash
 
+    # Run gff2jsonld command
     $ bkbit gff2jsonld -a 'GCF_003339765.1' 'https://ftp.ensembl.org/pub/release-104/gff3/macaca_mulatta/Macaca_mulatta.Mmul_10.104.gff3.gz' > output.jsonld
diff --git a/docs/index.rst b/docs/index.rst
@@ -14,7 +14,7 @@ This package contains tools to use the BICAN Knowledgebase Data Models.
    install
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 1
    :caption: DATA TRANSLATORS
 
    specimen_file_manifest

diff --git a/docs/specimen_file_manifest.rst b/docs/specimen_file_manifest.rst
@@ -2,3 +2,67 @@
 
 Specimen File Manifest
 ----------------------
+
+Overview
+.........
+
+Generates a JSON-LD file containing specimen file data using the BICAN Library Generation Schema. 
+
+Command Line
+.............
+
+``bkbit filemanifest2jsonld``
+,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
+
+.. code-block:: bash
+
+    $ bkbit filemanifest2jsonld [OPTIONS] FILE_MANIFEST_CSV
+
+**Options**
+
+    ``--list_library_aliquots``
+        A boolean flag that, when provided, generates a list of unique library aliquots contained in the given file manifest and saves output in file called 'file_manifest_library_aliquots.txt'. 
+        If this flag is not set (DEFAULT), then only the JSON-LD output will be generated.
+
+**Arguments**
+
+    ``FILE_MANIFEST_CSV``
+        Required argument. 
+        FILE_MANIFEST_CSV can be optained from Brain Knowledge Platform and **must** contains the following columns:
+
+            - Project ID	
+            - Specimen ID	
+            - File Name	
+            - Checksum	
+            - File Type	
+            - Archive	
+            - Archive URI
+
+Examples
+.........
+
+Example 1: Only generate JSON-LD output
+,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
+
+.. code-block:: bash
+
+    # Run filemanifest2jsonld command 
+    $ bkbit filemanifest2jsonld file_manifest.csv > output.jsonld
+
+Example 2: Generate JSON-LD output and list of library aliquots
+,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
+
+.. code-block:: bash
+
+    # Run filemanifest2jsonld command 
+    $ bkbit filemanifest2jsonld --list_library_aliquots file_manifest.csv > output.jsonld
+
+    # Generated output files 
+    $ ls .
+    output.jsonld
+    file_manifest_library_aliquots.txt
+
+    # Contents of file_manifest_library_aliquots.txt
+    $ cat file_manifest_library_aliquots.txt
+    LP-123
+    LP-345
diff --git a/docs/specimen_metadata.rst b/docs/specimen_metadata.rst
@@ -30,26 +30,6 @@ Command Line
         The NHASH_ID of the specimen or a file containing a list of NHASH_IDs. 
         If a file is provided, the file should contain one NHASH_ID per line.
 
-``filemanifest2jsonld``
-,,,,,,,,,,,,,,,,,,,,,
-
-.. code-block:: bash
-
-    $ bkbit specimen2jsonld [OPTIONS] NHASH_ID_OR_FILE
-
-**Options**
-
-    ``-d, --decendants``
-        A boolean flag that, when provided, generates BICAN objects for the given NHASH_ID and all of its descendants. 
-        If this flag is not set (DEFAULT), then the ancestors will be processed.
-
-**Arguments**
-
-    ``NHASH_ID_OR_FILE``
-        The NHASH_ID of the specimen or a file containing a list of NHASH_IDs. 
-        If a file is provided, the file should contain one NHASH_ID per line.
-
-
 Environment Variables 
 .............
 
@@ -70,6 +50,9 @@ Example 1: Parse a single record and its ancestors
 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 
 .. code-block:: bash
+    
+    # If first time running specimen2jsonld or if token is expired, set jwt_token environment variable
+    $ export jwt_token=specimen_portal_personal_api_token
 
     # Run specimen2jsonld command 
     $ bkbit specimen2jsonld 'LP-CVFLMQ819998' > output.jsonld
@@ -79,6 +62,9 @@ Example 2: Parse a single record and its descendants
 
 .. code-block:: bash
 
+    # If first time running specimen2jsonld or if token is expired, set jwt_token environment variable
+    $ export jwt_token=specimen_portal_personal_api_token
+
     # Run specimen2jsonld command. Important: include '--descendants' flag
     $ bkbit specimen2jsonld -d 'DO-GICE7463' > output.jsonld
 
@@ -87,6 +73,9 @@ Example 3: Parse a file containing record(s) and their respective ancestors
 
 .. code-block:: bash
 
+    # If first time running specimen2jsonld or if token is expired, set jwt_token environment variable
+    $ export jwt_token=specimen_portal_personal_api_token
+
     # Contents of input file 
     $ cat input_nhash_ids.txt
     LA-TZWCWB265559FVVNTS329147
@@ -107,6 +96,9 @@ Example 4: Parse a file containing record(s) and their respective descendants
 
 .. code-block:: bash
 
+    # If first time running specimen2jsonld or if token is expired, set jwt_token environment variable
+    $ export jwt_token=specimen_portal_personal_api_token
+
     # Contents of input file 
     $ cat input_nhash_ids.txt
     DO-XIQQ6047