document aux enum and add advanced examples

Author: hasindu2008

docs/slow5_api/low_level_api/slow5_aux_get_enum.md

@@ -0,0 +1,93 @@
+# slow5\_aux\_get\_enum
+
+## NAME
+
+slow5\_aux\_get\_enum - fetches an auxiliary field of type enum from a SLOW5 record
+
+## SYNOPSYS
+
+```
+uint8_t slow5_aux_get_enum(const slow5_rec_t *read, const char *field, int *err)
+```
+
+
+## DESCRIPTION
+
+`slow5_aux_get_enum()` fetches the value of an auxiliary field of a enum datatype specified by the field name *field* from the slow5 record pointed by *read*.
+
+The argument *err* is an address of an integer which will be set inside the function call to indicate an error. Unless *err* is NULL, `slow5_aux_get_enum()` sets a non zero error code in **err* in case of failure.
+
+## RETURN VALUE
+
+Upon successful completion, `slow5_aux_get_enum()` returns the requested enum field value as a uint8_t. Otherwise, the SLOW5 missing value representation for the enum datatype is returned (`SLOW5_ENUM_NULL`) and `slow5_errno` is set to indicate the error. See notes below.
+
+
+## ERRORS
+
+In case of an error, `slow5_errno` or the non zero error code is set in *err* (unless *err* is NULL) are as follows.
+
+* `SLOW5_ERR_NOFLD`
+         The requested field was not found.
+* `SLOW5_ERR_NOAUX`
+         Auxiliary hash map for the record was not found (see notes below).
+* `SLOW5_ERR_ARG`
+         Invalid argument - read or field is NULL.
+* `SLOW5_ERR_TYPE`
+         Type conversion was not possible - an array data type field cannot be converted to a primitive type.
+
+
+## NOTES
+
+More error codes may be introduced in future. If the field value has been marked missing for an individual SLOW5 record ("." in SLOW5 ASCII and as `SLOW5_ENUM_NULL` in BLOW5), `SLOW5_ENUM_NULL` is returned and no error code is set (considered successful as the SLOW5 missing value representation is actually present in the file). This is typically the case when the field name is present in the SLOW5 header, but the field value for the particular record is missing. If the requested field is completely not present (not in the SLOW5 header as well), this is considered an error and `SLOW5_ERR_NOAUX` code is set.
+
+The enum value returned by `slow5_aux_get_enum()` can be used to obtain the corresponding enum label by using using as the index for the list returned by `slow5_get_aux_enum_labels()`.
+
+## EXAMPLES
+```
+#include <stdio.h>
+#include <stdlib.h>
+#include <slow5/slow5.h>
+
+#define FILE_PATH "examples/adv/example3.blow5"
+
+int main(){
+
+    slow5_file_t *sp = slow5_open(FILE_PATH,"r");
+    if(sp==NULL){
+        fprintf(stderr,"Error in opening file\n");
+        exit(EXIT_FAILURE);
+    }
+    slow5_rec_t *rec = NULL;
+    int ret=0;
+    ret = slow5_get_next(&rec,sp);
+    if(ret<0){
+        fprintf(stderr,"Error in slow5_get_next. Error code %d\n",ret);
+        exit(EXIT_FAILURE);
+    }
+
+    uint8_t num_label = 0;
+    char **labels = slow5_get_aux_enum_labels(sp->header, "end_reason", &num_label);
+    if(labels==NULL){
+        fprintf(stderr,"Error in getting list of enum labels\n");
+        exit(EXIT_FAILURE);
+    }
+
+    uint8_t end_reason = slow5_aux_get_enum(rec,"end_reason",&ret);
+    if(ret!=0){
+        fprintf(stderr,"Error in getting auxiliary attribute from the file. Error code %d\n",ret);
+        exit(EXIT_FAILURE);
+    }
+    if(end_reason != SLOW5_ENUM_NULL){
+        printf("end_reason = %s\n", labels[end_reason]);
+    } else{
+        printf("end_reason is missing for the record\n");
+    }
+
+    slow5_rec_free(rec);
+    slow5_close(sp);
+
+}
+```
+
+## SEE ALSO
+[`slow5_get_aux_enum_labels()`](slow5_get_aux_enum_labels.md).

docs/slow5_api/low_level_api/slow5_get_aux_enum_labels.md

@@ -0,0 +1,86 @@
+# slow5_get_aux_enum_labels
+
+## NAME
+
+slow5_get_aux_enum_labels - gets the list of labels for an enum data type
+
+## SYNOPSYS
+
+`char **slow5_get_aux_enum_labels(const slow5_hdr_t *header, const char *field, uint8_t *n)`
+
+## DESCRIPTION
+
+`slow5_get_aux_enum_labels()` gets the list of enum labels for a auxiliary field specified by *field* from a SLOW5 file header pointed by *header*. The number of enum labels will be set on the address specified by *n*.
+
+
+## RETURN VALUE
+
+`slow5_get_aux_enum_labels()` returns the list of enum labels as a *char*** pointer. On error NULL is returned and `slow5_errno` is set to indicate the error.
+
+## ERRORS
+
+In case of an error, `slow5_errno` is set as follows.
+
+* `SLOW5_ERR_NOAUX`
+         Auxiliary hash map for the record was not found.
+* `SLOW5_ERR_ARG`
+         Invalid argument - header or field is NULL.
+* `SLOW5_ERR_TYPE`
+         Field data type is not an enum type
+
+
+## NOTES
+
+The returned pointer is from an internal data structure and must NOT be freed by user.
+The order of the enum labels corresponds to the enum value, that is, an enum value can be used as the index on the returned pointer to access the corresponding enum label.
+
+## EXAMPLES
+
+```
+#include <stdio.h>
+#include <stdlib.h>
+#include <slow5/slow5.h>
+
+#define FILE_PATH "examples/adv/example3.blow5"
+
+int main(){
+
+    slow5_file_t *sp = slow5_open(FILE_PATH,"r");
+    if(sp==NULL){
+        fprintf(stderr,"Error in opening file\n");
+        exit(EXIT_FAILURE);
+    }
+    slow5_rec_t *rec = NULL;
+    int ret=0;
+    ret = slow5_get_next(&rec,sp);
+    if(ret<0){
+        fprintf(stderr,"Error in slow5_get_next. Error code %d\n",ret);
+        exit(EXIT_FAILURE);
+    }
+
+    uint8_t num_label = 0;
+    char **labels = slow5_get_aux_enum_labels(sp->header, "end_reason", &num_label);
+    if(labels==NULL){
+        fprintf(stderr,"Error in getting list of enum labels\n");
+        exit(EXIT_FAILURE);
+    }
+
+    uint8_t end_reason = slow5_aux_get_enum(rec,"end_reason",&ret);
+    if(ret!=0){
+        fprintf(stderr,"Error in getting auxiliary attribute from the file. Error code %d\n",ret);
+        exit(EXIT_FAILURE);
+    }
+    if(end_reason != SLOW5_ENUM_NULL){
+        printf("end_reason = %s\n", labels[end_reason]);
+    } else{
+        printf("end_reason is missing for the record\n");
+    }
+
+    slow5_rec_free(rec);
+    slow5_close(sp);
+
+}
+```
+
+## SEE ALSO
+[slow5_aux_get_enum()](slow5_aux_get_enum.md)

docs/slow5_api/slow5_aux_get.md

@@ -81,7 +81,7 @@ int main(){
     //------------------------------------------------------------------------
     //              get auxiliary values with primitive datatype
     //------------------------------------------------------------------------
-    ret=0;
+
     double median_before = slow5_aux_get_double(rec,"median_before",&ret);
     if(ret!=0){
         fprintf(stderr,"Error in getting auxiliary attribute from the file. Error code %d\n",ret);

docs/slow5_api/slow5_low_level_api.md

@@ -26,7 +26,10 @@ Low-level API allows much more efficient access to BLOW5 files compared to the h
       fetches the raw record (without decompressing or parsing) at the current file pointer of a SLOW5 file
 * [slow5_decode](low_level_api/slow5_decode.md)<br/>
   &nbsp;&nbsp;&nbsp;&nbsp;decodes a slow5 record
-
+* [slow5_aux_get_enum](low_level_api/slow5_aux_get_enum.md)<br/>
+  &nbsp;&nbsp;&nbsp;&nbsp;fetches an auxiliary field of type enum from a SLOW5 record
+* [slow5_get_aux_enum_labels](low_level_api/slow5_get_aux_enum_labels.md)<br/>
+  &nbsp;&nbsp;&nbsp;&nbsp;gets the list of labels for an enum data type
 
 ### Writing and editing
 

examples/.gitignore

@@ -16,3 +16,7 @@ example_write_append.slow5
 example_write_aux.blow5
 write
 append
+adv/auxiliary_field_enum
+adv/sequential_read_pthreads
+adv/sequential_read_openmp
+adv/get_all_read_ids

examples/README.md

@@ -12,4 +12,6 @@ This directory contains following examples.
 
 You can invoke [build.sh](build.sh) from slow5lib directory as `examples/build.sh` to compile the example programmes. Have a look at the script to see the commands used for compiling and linking. As an example, the command to compile [sequential_read.c](sequential_read.c) is `gcc -Wall -O2 -I include/ examples/sequential_read.c lib/libslow5.a  -o examples/sequential_read -lm -lz`. Make sure that you first call `make` so that `lib/libslow5.a` becomes available to be linked with. If you compiled *slow5lib* with *zstd* support enabled (`make zstd=1`), make sure you append `-lzstd` to the compilation commands.
 
-A public template repository is available at [https://github.com/hasindu2008/slow5-template] which you can directly use to setup your own repository that uses *slow5lib* to build a tool. Check the instructions and comments there.
+A public template repository is available at [https://github.com/hasindu2008/slow5-template] which you can directly use to setup your own repository that uses *slow5lib* to build a tool. Check the instructions and comments there.
+
+Some advanced examples that uses low-level API are available [here](adv/).

examples/adv/README.md

@@ -0,0 +1,10 @@
+# slow5lib Advanced Examples
+
+This directory contains following advanced examples that uses low-level API.
+- *auxiliary_field_enum.c* demonstrates how to fetch a auxiliary field of enum data type from a slow5/blow5 file.
+- *sequential_read_pthreads.c* demonstrates how to sequentially read raw SLOW5 records from a slow5/blow5 file using a single thread and then decode those in parallel using *pthreads*.
+- *sequential_read_openmp.c* demonstrates how to sequentially read raw SLOW5 records from a slow5/blow5 file using a single thread and then decode those in parallel using *openMP*.
+- *get_all_read_ids.c* demonstrates how to get the list of all read IDs from a slow5/blow5 file.
+
+You can invoke [build.sh](build.sh) from slow5lib directory as `examples/adv/build.sh` to compile the example programmes. Have a look at the script to see the commands used for compiling and linking. Also make sure you get familiar with the basic examples first, before trying these advanced examples.
+

examples/adv/auxiliary_field_enum.c

@@ -0,0 +1,49 @@
+// an example programme that uses slow5lib to obtain auxiliary field of enum type from a slow5/blow5 file
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <slow5/slow5.h>
+
+#define FILE_PATH "examples/adv/example3.blow5"
+#include <stdio.h>
+#include <stdlib.h>
+#include <slow5/slow5.h>
+
+int main(){
+
+    slow5_file_t *sp = slow5_open(FILE_PATH,"r");
+    if(sp==NULL){
+        fprintf(stderr,"Error in opening file\n");
+        exit(EXIT_FAILURE);
+    }
+    slow5_rec_t *rec = NULL;
+    int ret=0;
+    ret = slow5_get_next(&rec,sp);
+    if(ret<0){
+        fprintf(stderr,"Error in slow5_get_next. Error code %d\n",ret);
+        exit(EXIT_FAILURE);
+    }
+
+    uint8_t num_label = 0;
+    char **labels = slow5_get_aux_enum_labels(sp->header, "end_reason", &num_label);
+    if(labels==NULL){
+        fprintf(stderr,"Error in getting list of enum labels\n");
+        exit(EXIT_FAILURE);
+    }
+
+    uint8_t end_reason = slow5_aux_get_enum(rec,"end_reason",&ret);
+    if(ret!=0){
+        fprintf(stderr,"Error in getting auxiliary attribute from the file. Error code %d\n",ret);
+        exit(EXIT_FAILURE);
+    }
+    if(end_reason != SLOW5_ENUM_NULL){
+        printf("end_reason = %s\n", labels[end_reason]);
+    } else{
+        printf("end_reason is missing for the record\n");
+    }
+
+    slow5_rec_free(rec);
+    slow5_close(sp);
+
+    return 0;
+}

examples/adv/build.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+
+#exit on error
+set -x
+#prints the command to the console
+set -e
+gcc -Wall -O2 -I include/ examples/adv/auxiliary_field_enum.c lib/libslow5.a  -o examples/adv/auxiliary_field_enum -lm -lz
+gcc -Wall -O2 -I include/ examples/adv/sequential_read_openmp.c lib/libslow5.a  -o examples/adv/sequential_read_openmp -lm -lz -fopenmp
+gcc -Wall -O2 -I include/ examples/adv/sequential_read_pthreads.c lib/libslow5.a  -o examples/adv/sequential_read_pthreads -lm -lz -lpthread
+gcc -Wall -O2 -I include/ examples/adv/get_all_read_ids.c lib/libslow5.a  -o examples/adv/get_all_read_ids -lm -lz
+
+#append -lzstd to above commands if your slow5lib is built with zstd support