Merge branch 'master' into dev

Author: hasindu2008

.github/workflows/c-cpp.yml

@@ -105,9 +105,9 @@ jobs:
       run: make clean && make CC=icc -j8 zstd=1
     - name: test zstd
       run: make test zstd=1 CC=icc
-  os_x_10:
-    name: OSX 10
-    runs-on: macos-10.15
+  os_x_11:
+    name: OSX 11
+    runs-on: macos-11
     steps:
     - uses: actions/checkout@v2
     - name: build
@@ -116,9 +116,9 @@ jobs:
       run: make test
     - name: examples
       run: make examples
-  os_x_10_zstd:
-    name: OSX 10 zstd
-    runs-on: macos-10.15
+  os_x_11_zstd:
+    name: OSX 11 zstd
+    runs-on: macos-11
     steps:
     - uses: actions/checkout@v2
     - name: install packages

docs/slow5_api/slow5_aux_get.md

@@ -40,13 +40,13 @@ Upon successful completion, `slow5_aux_get_<primitive_datatype>()` returns the r
 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`
+* `SLOW5_ERR_NOFLD`
     &nbsp;&nbsp;&nbsp;&nbsp; The requested field was not found.
-`SLOW5_ERR_NOAUX`
+* `SLOW5_ERR_NOAUX`
     &nbsp;&nbsp;&nbsp;&nbsp; Auxiliary hash map for the record was not found (see notes below).
-`SLOW5_ERR_ARG`
+* `SLOW5_ERR_ARG`
     &nbsp;&nbsp;&nbsp;&nbsp; Invalid argument - read or field is NULL.
-`SLOW5_ERR_TYPE`
+* `SLOW5_ERR_TYPE`
     &nbsp;&nbsp;&nbsp;&nbsp; Type conversion was not possible - an array data type field cannot be converted to a primitive type.
 
 

docs/slow5_api/slow5_aux_get_array.md

@@ -40,13 +40,13 @@ Upon successful completion, `slow5_aux_get_<array_datatype>()` returns a pointer
 
 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`
+* `SLOW5_ERR_NOFLD`
     &nbsp;&nbsp;&nbsp;&nbsp; The requested field was not found.
-`SLOW5_ERR_NOAUX`
+* `SLOW5_ERR_NOAUX`
     &nbsp;&nbsp;&nbsp;&nbsp; Auxiliary hash map for the record was not found.
-`SLOW5_ERR_ARG`
+* `SLOW5_ERR_ARG`
     &nbsp;&nbsp;&nbsp;&nbsp; Invalid argument - read or field is NULL
-`SLOW5_ERR_TYPE`
+* `SLOW5_ERR_TYPE`
     &nbsp;&nbsp;&nbsp;&nbsp; Type conversion was not possible - a primitives data type field cannot be converted to an array type.
 
 ## NOTES

examples/README.md

@@ -0,0 +1,15 @@
+# slow5lib Examples
+
+This directory contains following examples.
+- *sequential_read.c* demonstrates how to read a slow5/blow5 file, sequentially from start to end.
+- *random_read.c* demonstrates how to fetch a given read ID from a slow5/blow5 file.
+- *header_attribute.c* demonstrates how to fetch a header data attribute from a slow5/blow5 file.
+- *auxiliary_field.c* demonstrates how to fetch a auxiliary field from a slow5/blow5 file.
+- *random_read_pthreads.c* demonstrates how to fetch given read IDs in parallel from a slow5/blow5 file using *pthreads*.
+- *random_read_openmp.c* demonstrates how to fetch given read IDs in parallel from a slow5/blow5 file using openMP.
+- *write.c* demonstrate how to write a new slow5/blow5 file.
+- *append.c* demonstrates how to append to an existing slow5/blow5 file.
+
+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.

examples/append.c

@@ -16,6 +16,7 @@ read_1	    0	        4096	        4	    12	    4000	        12	            0,1,2
 
 int main(){
 
+    //open the SLOW5 file for appending
     slow5_file_t *sp = slow5_open(FILE_PATH, "a");
     if(sp==NULL){
         fprintf(stderr,"Error opening file!\n");
@@ -81,13 +82,16 @@ int main(){
         exit(EXIT_FAILURE);
     }
 
+    //append the record to the file
     if(slow5_write(slow5_record, sp) < 0){
         fprintf(stderr,"Error writing record to file\n");
         exit(EXIT_FAILURE);
     }
 
+    //free the slow5 record
     slow5_rec_free(slow5_record);
 
+    //close the SLOW5 file
     slow5_close(sp);
 
     return 0;

examples/auxiliary_field.c

@@ -1,3 +1,5 @@
+// an example programme that uses slow5lib to obtain auxiliary field from a slow5/blow5 file
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <slow5/slow5.h>
@@ -6,50 +8,73 @@
 
 int main(){
 
+    //open the SLOW5 file
     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;
+
+    slow5_rec_t *rec = NULL; //slow5 record to be read
+    int ret=0; //for return value
+
+    //get the very first record
     ret = slow5_get_next(&rec,sp);
     if(ret<0){
         fprintf(stderr,"Error in slow5_get_next. Error code %d\n",ret);
         exit(EXIT_FAILURE);
     }
 
     //------------------------------------------------------------------------
-    //              get auxiliary values with primitive datatype
+    //   getting auxiliary fields whose values are primitive datatypes
     //------------------------------------------------------------------------
-    ret=0;
+
+    //median_before auxiliary field - double data type
     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);
         exit(EXIT_FAILURE);
     }
-    fprintf(stderr,"median_before = %f\n", median_before);
+    if(!isnan(median_before)){  //SLOW5_DOUBLE_NULL is the generic NaN value returned by nan("""") and thus median_before != SLOW5_DOUBLE_NULL is not correct
+        printf("median_before = %f\n", median_before);
+    } else {
+        printf("median_before is missing for the record\n");
+    }
 
+    //start_time auxiliary field - uint64 data type
     uint64_t start_time = slow5_aux_get_uint64(rec, "start_time", &ret);
     if(ret!=0){
         fprintf(stderr,"Error in getting auxiliary attribute from the file. Error code %d\n",ret);
         exit(EXIT_FAILURE);
     }
-    fprintf(stderr,"start_time = %lu\n", start_time);
+    if(start_time != SLOW5_UINT64_T_NULL){ //check if the field value is marked missing and print the value
+        printf("start_time = %lu\n", start_time);
+    } else{
+        printf("start_time is missing for the record\n");
+    }
 
     //------------------------------------------------------------------------
-    //              get auxiliary values with array datatype
+    //    getting auxiliary fields whose values are array datatypes
     //------------------------------------------------------------------------
 
-    uint64_t len;
+    //channel_number auxiliary field - string (char *) datatype
+    uint64_t len; //length of the array
     char* channel_number = slow5_aux_get_string(rec, "channel_number", &len, &ret);
     if(ret!=0){
         fprintf(stderr,"Error in getting auxiliary attribute from the file. Error code %d\n",ret);
         exit(EXIT_FAILURE);
     }
-    fprintf(stderr,"channel_number = %s\n", channel_number);
+    if (channel_number != NULL){ //check if the field value exists and print the value
+        printf("channel_number = %s\n", channel_number);
+    } else{
+        printf("channel_number is missing for the record\n");
+    }
 
+    //free the SLOW5 record
     slow5_rec_free(rec);
+
+    //close the SLOW5 file
     slow5_close(sp);
 
+    return 0;
 }

examples/header_attribute.c

@@ -1,5 +1,5 @@
 
-// an example programme that uses slow5lib to obtain a slow5 header attribute
+// an example programme that uses slow5lib to obtain a slow5 header data attribute
 
 #include <stdio.h>
 #include <stdlib.h>
@@ -9,18 +9,22 @@
 
 int main(){
 
+    //open the SLOW5 file
     slow5_file_t *sp = slow5_open(FILE_PATH,"r");
     if(sp==NULL){
         fprintf(stderr,"Error in opening file\n");
         exit(EXIT_FAILURE);
     }
-    const slow5_hdr_t* header = sp->header;
+
+    const slow5_hdr_t* header = sp->header; //pointer to the SLOW5 header
     int read_group = 0;
-    char* read_group_0_run_id_value = slow5_hdr_get("run_id", read_group, header);
-    if(read_group_0_run_id_value != NULL ){
+    char* read_group_0_run_id_value = slow5_hdr_get("run_id", read_group, header); //get the value of the attribute "run_id" in the read group 0
+    if(read_group_0_run_id_value != NULL ){ //check if the attribute exists and print the value
         printf("%s\n",read_group_0_run_id_value);
     }
 
+    //close the SLOW5 file
     slow5_close(sp);
 
+    return 0;
 }

examples/random_read.c

@@ -10,38 +10,48 @@
 
 int main(){
 
+    //open the SLOW5 file
     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;
 
+    slow5_rec_t *rec = NULL; //slow5 record to be read
+    int ret=0; //for return value
+
+    //load the SLOW5 index (will be built if not present)
     ret = slow5_idx_load(sp);
     if(ret<0){
         fprintf(stderr,"Error in loading index\n");
         exit(EXIT_FAILURE);
     }
 
+    //fetch the read with read_id "r3"
     ret = slow5_get("r3", &rec, sp);
-    if(ret < 0){
+    if(ret<0){
         fprintf(stderr,"Error in when fetching the read\n");
     }
     else{
         printf("%s\t",rec->read_id);
         uint64_t len_raw_signal = rec->len_raw_signal;
-        for(uint64_t i=0;i<len_raw_signal;i++){
+        for(uint64_t i=0;i<len_raw_signal;i++){ //iterate through the raw signal and print in picoamperes
             double pA = TO_PICOAMPS(rec->raw_signal[i],rec->digitisation,rec->offset,rec->range);
             printf("%f ",pA);
         }
         printf("\n");
     }
 
+    //..... fetch any other read using slow5_get (as above)
+
+    //free the SLOW5 record
     slow5_rec_free(rec);
 
+    //free the SLOW5 index
     slow5_idx_unload(sp);
 
+    //close the SLOW5 file
     slow5_close(sp);
 
+    return 0;
 }

examples/random_read_openmp.c

@@ -1,5 +1,5 @@
 
-// an example programme that uses slow5lib to randmly access records in a SLOW5 file using multiple threads (openMP)
+// an example programme that uses slow5lib to randomly access records in a SLOW5 file using multiple threads (openMP)
 #include <omp.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -12,13 +12,16 @@ char * read_id_list[READ_LIST_SIZE] = {"r4", "r1", "r3", "r4"};
 
 int main(){
 
+    //open the SLOW5 file
     slow5_file_t *sp = slow5_open(FILE_PATH,"r");
     if(sp==NULL){
        fprintf(stderr,"Error in opening file\n");
        exit(EXIT_FAILURE);
     }
 
-    int ret=0;
+    int ret=0; //for return value
+
+    //load the SLOW5 index (will be built if not present)
     ret = slow5_idx_load(sp);
     if (ret < 0) {
         fprintf(stderr, "Error in loading index\n");
@@ -27,18 +30,21 @@ int main(){
 
     #pragma omp parallel for
     for(int32_t i=0; i<READ_LIST_SIZE; i++) {
-        slow5_rec_t *rec = NULL;
-        ret = slow5_get(read_id_list[i], &rec, sp);
+        slow5_rec_t *rec = NULL; //slow5 record to be read
+        ret = slow5_get(read_id_list[i], &rec, sp); //fetch the read
         if (ret < 0) {
             fprintf(stderr, "Error in when fetching the read %s\n",read_id_list[i]);
         } else {
             fprintf(stderr, "Successfully fetched the read %s with %ld raw signal samples\n", rec->read_id, rec->len_raw_signal);
         }
-        slow5_rec_free(rec);
+        slow5_rec_free(rec); //free the SLOW5 record
     }
 
+    //free the SLOW5 index
     slow5_idx_unload(sp);
 
+    //close the SLOW5 file
     slow5_close(sp);
 
+    return 0;
 }