frequency() is now bases(), which makes more sense as a name

Author: dpryan79

README.md

@@ -91,21 +91,21 @@ If it was requested during file opening that soft-masking information be stored,
 
 ## Fetch per-base statistics
 
-It's often required to compute the percentage of 1 or more bases in a chromosome. This can be done with the `frequency()` method.
+It's often required to compute the percentage of 1 or more bases in a chromosome. This can be done with the `bases()` method.
 
-    >>> tb.frequency("chr1")
+    >>> tb.bases("chr1")
     {'A': 0.08, 'C': 0.08, 'T': 0.08666666666666667, 'G': 0.08666666666666667}
 
-This returns a dictionary with bases as keys and their frequency as values. Note that this will not sum to 1 if there are any hard-masked bases (the chromosome is 2/3 `N` in this case). One can also request this information over a particular region.
+This returns a dictionary with bases as keys and the fraction of the sequence composed of them as values. Note that this will not sum to 1 if there are any hard-masked bases (the chromosome is 2/3 `N` in this case). One can also request this information over a particular region.
 
-    >>> tb.frequency("chr1", 24, 74)
+    >>> tb.bases("chr1", 24, 74)
     {'A': 0.12, 'C': 0.12, 'T': 0.12, 'G': 0.12}
 
 The start and end position are as with the `sequence()` method described above.
 
 If integer counts are preferred, then they can instead be returned.
 
-    >>> tb.frequency("chr1", 24, 74, True)
+    >>> tb.bases("chr1", 24, 74, True)
     {'A': 6, 'C': 6, 'T': 6, 'G': 6}
 
 ## Close a file

lib2bit/2bit.c

@@ -272,7 +272,7 @@ void increment(char base, uint32_t *A, uint32_t *C, uint32_t *T, uint32_t *G) {
     }
 }
 
-void *twobitFrequencyWorker(TwoBit *tb, uint32_t tid, uint32_t start, uint32_t end, int fraction) {
+void *twobitBasesWorker(TwoBit *tb, uint32_t tid, uint32_t start, uint32_t end, int fraction) {
     void *out;
     uint32_t sz = end - start, pos = 0;
     uint32_t A = 0, C = 0, T = 0, G = 0, len = end - start;
@@ -328,7 +328,7 @@ void *twobitFrequencyWorker(TwoBit *tb, uint32_t tid, uint32_t start, uint32_t e
     return NULL;
 }
 
-void *twobitFrequency(TwoBit *tb, char *chrom, uint32_t start, uint32_t end, int fraction) {
+void *twobitBases(TwoBit *tb, char *chrom, uint32_t start, uint32_t end, int fraction) {
     uint32_t tid = 0, i;
 
     //Get the chromosome ID
@@ -350,7 +350,7 @@ void *twobitFrequency(TwoBit *tb, char *chrom, uint32_t start, uint32_t end, int
     if(end > tb->idx->size[tid]) return NULL;
     if(start >= end) return NULL;
 
-    return twobitFrequencyWorker(tb, tid, start, end, fraction);
+    return twobitBasesWorker(tb, tid, start, end, fraction);
 }
 
 /*

lib2bit/2bit.h

@@ -48,7 +48,8 @@ uint32_t twobitChromLen(TwoBit *tb, char *chrom);
 char *twobitSequence(TwoBit *tb, char *chrom, uint32_t start, uint32_t end);
 
 //Return a pointer to either 4 doubles or 4 uint32_ts holding per-base frequencies or counts.
-void *twobitFrequency(TwoBit *tb, char *chrom, uint32_t start, uint32_t end, int fractional);
+//The order is A, C, T, G
+void *twobitBases(TwoBit *tb, char *chrom, uint32_t start, uint32_t end, int fractional);
 
 #ifdef __cplusplus
 }

py2bit.c

@@ -193,7 +193,7 @@ static PyObject *py2bitSequence(pyTwoBit_t *self, PyObject *args, PyObject *kwds
     return ret;
 }
 
-static PyObject *py2bitFrequency(pyTwoBit_t *self, PyObject *args, PyObject *kwds) {
+static PyObject *py2bitBases(pyTwoBit_t *self, PyObject *args, PyObject *kwds) {
     PyObject *ret = NULL, *val = NULL;
     PyObject *fractionO = Py_True;
     TwoBit *tb = self->tb;
@@ -224,9 +224,9 @@ static PyObject *py2bitFrequency(pyTwoBit_t *self, PyObject *args, PyObject *kwd
 
     if(fractionO == Py_False) fraction = 0;
 
-    o = twobitFrequency(tb, chrom, start, end, fraction);
+    o = twobitBases(tb, chrom, start, end, fraction);
     if(!o) {
-        PyErr_SetString(PyExc_RuntimeError, "Received an error while determining the per-base frequency.");
+        PyErr_SetString(PyExc_RuntimeError, "Received an error while determining the per-base metrics.");
         return NULL;
     }
 

py2bit.h

@@ -12,7 +12,7 @@ static PyObject *py2bitInfo(pyTwoBit_t *pybw, PyObject *args);
 static PyObject* py2bitClose(pyTwoBit_t *pybw, PyObject *args);
 static PyObject* py2bitChroms(pyTwoBit_t *pybw, PyObject *args);
 static PyObject *py2bitSequence(pyTwoBit_t *pybw, PyObject *args, PyObject *kwds);
-static PyObject *py2bitFrequency(pyTwoBit_t *pybw, PyObject *args, PyObject *kwds);
+static PyObject *py2bitBases(pyTwoBit_t *pybw, PyObject *args, PyObject *kwds);
 static void py2bitDealloc(pyTwoBit_t *pybw);
 
 static PyMethodDef tbMethods[] = {
@@ -107,14 +107,14 @@ NNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNACGTACGTACGTagctagctGATCGATCGT
 >>> tb.sequence(\"chr1\", 24, 74)\n\
 NNNNNNNNNNNNNNNNNNNNNNNNNNACGTACGTACGTagctagctGATC\n\
 >>> tb.close()"},
-    {"frequency", (PyCFunction)py2bitFrequency, METH_VARARGS|METH_KEYWORDS,
-"Retrieve the percentage of A, C, T, and Gs in a chromosome or subset thereof.\n\
-On error, a runtime exception is thrown.\n\
+    {"bases", (PyCFunction)py2bitBases, METH_VARARGS|METH_KEYWORDS,
+"Retrieve the percentage or number of A, C, T, and Gs in a chromosome or subset\n\
+thereof. On error, a runtime exception is thrown.\n\
 \n\
 Positional arguments:\n\
     chr:   Chromosome name\n\
 \n\
-Keyword arguments:\n\
+Optional keyword arguments:\n\
     start: Starting position (0-based)\n\
     end:   Ending position (1-based)\n\
     fraction: Whether to return fractional or integer values (default 'True',\n\
@@ -132,11 +132,11 @@ bases. Counts may sum to less than the length of the region for the same reason.
 \n\
 >>> import py2bit\n\
 >>> tb = py2bit.open(\"test/test.2bit\")\n\
->>> tb.frequency(tb, \"chr1\")\n\
+>>> tb.bases(tb, \"chr1\")\n\
 {'A': 0.08, 'C': 0.08, 'T': 0.08666666666666667, 'G': 0.08666666666666667}\n\
->>> tb.frequency(tb, \"chr1\", 24, 74)\n\
+>>> tb.bases(tb, \"chr1\", 24, 74)\n\
 {'A': 0.12, 'C': 0.12, 'T': 0.12, 'G': 0.12}\n\
->>> tb.frequency(tb, \"chr1\", 24, 74, True)\n\
+>>> tb.bases(tb, \"chr1\", 24, 74, True)\n\
 {'A': 6, 'C': 6, 'T': 6, 'G': 6}\n\
 >>> tb.close()"},
     {NULL, NULL, 0, NULL}

py2bitTest/test.py

@@ -35,9 +35,9 @@ def testSequence(self):
         assert(tb.sequence("chr1", 24, 74) == "NNNNNNNNNNNNNNNNNNNNNNNNNNACGTACGTACGTagctagctGATC")
         tb.close()
 
-    def testFrequency(self):
+    def testBases(self):
         tb = py2bit.open(self.fname, True)
-        assert(tb.frequency("chr1") == {'A': 0.08, 'C': 0.08, 'T': 0.08666666666666667, 'G': 0.08666666666666667})
-        assert(tb.frequency("chr1", 24, 74) == {'A': 0.12, 'C': 0.12, 'T': 0.12, 'G': 0.12})
-        assert(tb.frequency("chr1", 24, 74, False) == {'A': 6, 'C': 6, 'T': 6, 'G': 6})
+        assert(tb.bases("chr1") == {'A': 0.08, 'C': 0.08, 'T': 0.08666666666666667, 'G': 0.08666666666666667})
+        assert(tb.bases("chr1", 24, 74) == {'A': 0.12, 'C': 0.12, 'T': 0.12, 'G': 0.12})
+        assert(tb.bases("chr1", 24, 74, False) == {'A': 6, 'C': 6, 'T': 6, 'G': 6})
         tb.close()