Merge branch 'dev' into ex-zd

.github/workflows/c-cpp.yml

@@ -107,6 +107,19 @@ jobs:
       run: make clean && make CC=icc -j8 zstd=1
     - name: test zstd
       run: make test zstd=1 CC=icc
+  ubuntu_22:
+    name: Ubuntu 22
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v2
+    - name: install packages
+      run: sudo apt-get update && sudo apt-get install zlib1g-dev
+    - name: build-gcc
+      run: make -j8
+    - name: test-gcc
+      run: make test
+    - name: make mt
+      run: examples/mt/build.sh
   os_x_11:
     name: OSX 11
     runs-on: macos-11

.github/workflows/python.yml

@@ -82,7 +82,7 @@ jobs:
     steps:
     - uses: actions/checkout@v2
     - name: install packages
-      run: pip3 install numpy
+      run: pip3 install numpy setuptools
     - name: build
       run: make pyslow5
     - name: test
@@ -93,7 +93,7 @@ jobs:
     steps:
     - uses: actions/checkout@v2
     - name: install packages
-      run: pip3 install numpy
+      run: pip3 install numpy setuptools
     - name: build
       run: make pyslow5
     - name: test

docs/slow5_api/low_level_api/slow5_idx_load_with.md

@@ -1,15 +1,13 @@
 # slow5_idx_load_with
 
 ## NAME
-slow5_idx_load_with - loads the index file for a SLOW5 file given a file path for the index
+slow5_idx_load_with - loads the index file for a SLOW5 file for a user specified file path for the index
 
 ## SYNOPSYS
-`int slow5_idx_load_with(slow5_with_file_t *s5p, const char *pathname)`
+`int slow5_idx_load_with(slow5_file_t *s5p, const char *pathname)`
 
 ## DESCRIPTION
-`slow5_idx_load_with()` loads an index file for a SLOW5 file pointed by *s5p* into the memory from the disk and associates the index with *s5p*. If the index file is not found, the index is first created and written to the disk.
-
-`slow5_idx_load_with()` could be called instead of `slow5_idx_load_with()` when the index file is at a custom location.
+`slow5_idx_load_with()` loads an index file located at *pathname* for a SLOW5 file pointed by *s5p* into the memory from the disk and associates the index with *s5p*. If the index file is not found, it will error out.
 
 ## RETURN VALUE
 Upon successful completion, `slow5_idx_load_with()` returns a non-negative integer. Otherwise, a negative value is returned.

docs/slow5_api/mt_api/slow5_free_batch.md

@@ -0,0 +1,64 @@
+# slow5_free_batch
+
+## NAME
+
+slow5_free_batch - frees up a slow5 record batch
+
+## SYNOPSYS
+
+`void slow5_free_batch(slow5_batch_t *read_batch)`
+
+## DESCRIPTION
+
+The `slow5_free_batch()` function frees the memory of a *slow5_batch_t* structure pointed by *read_batch*, which must have been returned by a previous call to `slow5_init_batch()`.
+
+## RETURN VALUE
+
+None
+
+## EXAMPLES
+
+```
+#include <stdio.h>
+#include <stdlib.h>
+#include <slow5/slow5.h>
+#include <slow5/slow5_mt.h>
+
+#define FILE_PATH "examples/example.slow5"
+
+int main(){
+
+ slow5_file_t *sp = slow5_open(FILE_PATH,"r");
+    if(sp==NULL){
+        fprintf(stderr,"Error in opening file\n");
+        exit(EXIT_FAILURE);
+    }
+
+    int batch_size = 4096;
+    int num_thread = 8;
+
+    slow5_mt_t *mt = slow5_init_mt(num_thread,sp);
+    if (mt==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising multi-thread struct\n");
+        exit(EXIT_FAILURE);
+    }
+
+    slow5_batch_t *read_batch = slow5_init_batch(batch_size);
+    if (read_batch==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising slow5 record batch\n");
+        exit(EXIT_FAILURE);
+    }
+
+    // ...
+
+    slow5_free_batch(read_batch);
+    slow5_free_mt(mt);
+    slow5_close(sp);
+
+    return 0;
+}
+```
+
+## SEE ALSO
+
+[slow5_init_batch()](slow5_init_batch.md)

docs/slow5_api/mt_api/slow5_free_mt.md

@@ -0,0 +1,57 @@
+# slow5_free_mt
+
+## NAME
+
+slow5_free_mt - frees up a slow5 multi-thread structure
+
+## SYNOPSYS
+
+`void slow5_free_mt(slow5_mt_t *mt)`
+
+## DESCRIPTION
+
+The `slow5_free_mt()` function frees the memory of a slow5_mt_t structure pointed by mt, which must have been returned by a previous call to `slow5_init_mt()`.
+
+## RETURN VALUE
+
+None
+
+## EXAMPLES
+
+```
+#include <stdio.h>
+#include <stdlib.h>
+#include <slow5/slow5.h>
+#include <slow5/slow5_mt.h>
+
+#define FILE_PATH "examples/example.slow5"
+
+int main(){
+
+    slow5_file_t *sp = slow5_open(FILE_PATH,"r");
+    if(sp==NULL){
+        fprintf(stderr,"Error in opening file\n");
+        exit(EXIT_FAILURE);
+    }
+
+    int num_thread = 8;
+
+    slow5_mt_t *mt = slow5_init_mt(num_thread,sp);
+    if (mt==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising multi-thread struct\n");
+        exit(EXIT_FAILURE);
+    }
+
+    //...
+
+    slow5_free_mt(mt);
+    slow5_close(sp);
+
+    return 0;
+}
+```
+
+
+## SEE ALSO
+
+[slow5_init_mt()](slow5_init_mt.md)

docs/slow5_api/mt_api/slow5_get_batch.md

@@ -0,0 +1,102 @@
+# slow5_get_batch
+
+## NAME
+
+slow5_get_batch - fetches a batch of SLOW5 records corresponding to a given batch of read ID
+
+## SYNOPSYS
+
+`int slow5_get_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, char **rid, int num_rid)`
+
+## DESCRIPTION
+
+`slow5_get_batch()` fetches a batch of record from a SLOW5 file associated with *mt* for a specified list of read IDs. The list of read must be pointed by *rid* and the the size of the list must be specified by *num_rid*.
+
+## RETURN VALUE
+
+The number of records fetched.
+
+## NOTES
+
+*num_rid* must be less than or equal to the capacity of the read_batch.
+
+## ERRORS
+
+Currently, in case of error, this function will exit the programme. Proper error handling might be introduced in future, where a negative number return is indicative of error.
+
+## NOTES
+
+
+## EXAMPLES
+
+```
+#include <stdio.h>
+#include <stdlib.h>
+#include <slow5/slow5.h>
+#include <slow5/slow5_mt.h>
+
+#define FILE_PATH "examples/example.slow5"
+
+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_idx_load(sp);
+    if(ret<0){
+        fprintf(stderr,"Error in loading index\n");
+        exit(EXIT_FAILURE);
+    }
+
+    int num_rid = 4;
+    int num_thread = 2;
+    int batch_size = 4096;
+    char *rid[num_rid];
+    rid[0]="r4";
+    rid[1]="r1",
+    rid[2]="r2";
+    rid[3]="r5";
+
+    slow5_mt_t *mt = slow5_init_mt(num_thread,sp);
+    if (mt==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising multi-thread struct\n");
+        exit(EXIT_FAILURE);
+    }
+
+    slow5_batch_t *read_batch = slow5_init_batch(batch_size);
+    if (read_batch==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising slow5 record batch\n");
+        exit(EXIT_FAILURE);
+    }
+
+    ret = slow5_get_batch(mt, read_batch, rid, num_rid);
+    if(ret!=num_rid){
+        fprintf(stderr,"Error in fetching all records\n");
+        exit(EXIT_FAILURE);
+    }
+
+    for(int i=0;i<ret;i++){
+        rec = read_batch->slow5_rec;
+        uint64_t len_raw_signal = rec[i]->len_raw_signal;
+        printf("%s\t%ld\n",rec[i]->read_id,len_raw_signal);
+    }
+
+    slow5_free_batch(read_batch);
+    slow5_free_mt(mt);
+
+    slow5_idx_unload(sp);
+    slow5_close(sp);
+
+    return 0;
+}
+```
+
+## SEE ALSO
+
+[slow5_get()](slow5_get_next_batch.md)

docs/slow5_api/mt_api/slow5_get_next_batch.md

@@ -0,0 +1,85 @@
+# slow5_get_next_batch
+
+## NAME
+
+slow5_get_next_batch - fetches the next batch of records at the current file pointer of a SLOW5 file
+
+## SYNOPSYS
+
+`int slow5_get_next_batch(slow5_mt_t *mt, slow5_batch_t *read_batch, int num_reads)`
+
+## DESCRIPTION
+
+`slow5_get_next_batch()` fetches the next *num_reads* number of records from a SLOW5 file associated with *mt* at the current file pointer into a *slow5_batch_t*.
+
+## RETURN VALUE
+
+The number of records fetched.
+
+## NOTES
+
+*num_reads* must be less than or equal to the capacity of the read_batch.
+
+## ERRORS
+
+Currently, in case of error, this function will exit the programme. Proper error handling might be introduced in future, where a negative number return is indicative of error.
+
+## EXAMPLES
+
+```
+#include <stdio.h>
+#include <stdlib.h>
+#include <slow5/slow5.h>
+#include <slow5/slow5_mt.h>
+
+#define FILE_PATH "examples/example.slow5"
+
+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;
+    int batch_size = 4096;
+    int num_thread = 8;
+
+    slow5_mt_t *mt = slow5_init_mt(num_thread,sp);
+    if (mt==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising multi-thread struct\n");
+        exit(EXIT_FAILURE);
+    }
+
+    slow5_batch_t *read_batch = slow5_init_batch(batch_size);
+    if (read_batch==NULL){ //currently not useful, but better have this for future proofing
+        fprintf(stderr,"Error in initialising slow5 record batch\n");
+        exit(EXIT_FAILURE);
+    }
+
+    while((ret = slow5_get_next_batch(mt,read_batch,4096)) > 0){
+
+        for(int i=0;i<ret;i++){
+            rec = read_batch->slow5_rec;
+            uint64_t len_raw_signal = rec[i]->len_raw_signal;
+            printf("%s\t%ld\n",rec[i]->read_id,len_raw_signal);
+        }
+
+        if(ret<4096){ //this indicates nothing left to read //better handling of errors may be introduced in future
+            break;
+        }
+    }
+
+    slow5_free_batch(read_batch);
+    slow5_free_mt(mt);
+    slow5_close(sp);
+
+    return 0;
+}
+```
+
+## SEE ALSO
+
+[slow5_get()](slow5_get_batch.md)