myokit 1.35.0__py3-none-any.whl → 1.35.2__py3-none-any.whl

myokit/_sim/pacing.h

@@ -1,8 +1,8 @@
 /*
  * pacing.h
  *
- * Ansi-C implementation for event-based pacing (using a Myokit Protocol
- * object) and fixed-form pacing (using a time-series).
+ * Ansi-C implementation for event-based pacing (using a myokit.Protocol) and
+ * time series pacing (using a myokit.TimeSeriesProtocol).
  *
  * How to use event-based pacing:
  *
@@ -22,13 +22,12 @@
  * Flags are used to indicate errors. If a flag other than ESys_OK is set, a
  * call to ESys_SetPyErr(flag) can be made to set a Python exception.
  *
+ * How to use time series pacing:
  *
- * How to use fixed-form pacing:
- *
- *  1. Create a pacing system using FSys_Create
- *  2. Populate it using two Python lists via FSys_Populate
- *  3. Obtain the pacing value for any time using FSys_GetLevel
- *  4. Tidy up using FSys_Destroy
+ *  1. Create a pacing system using TSys_Create
+ *  2. Populate it using two Python lists via TSys_Populate
+ *  3. Obtain the pacing value for any time using TSys_GetLevel
+ *  4. Tidy up using TSys_Destroy
  *
  * This file is part of Myokit.
  * See http://myokit.org for copyright, sharing, and licensing details.
@@ -217,11 +216,12 @@ ESys_ScheduleEvent(ESys_Event head, ESys_Event add, ESys_Flag* flag)
  * Pacing system
  */
 struct ESys_Mem {
-    Py_ssize_t n_events;   // The number of events in this system
-    double time;    // The current time
-    ESys_Event events;   // The events, stored as an array
-    ESys_Event head;     // The head of the event queue
-    ESys_Event fire;     // The currently active event
+    Py_ssize_t n_events;    // The number of events in this system
+    double time;            // The current time
+    double initial_time;    // The initial time (used by reset)
+    ESys_Event events;      // The events, stored as an array
+    ESys_Event head;        // The head of the event queue
+    ESys_Event fire;        // The currently active event
     double tnext;   // The time of the next event start or finish
     double tdown;   // The time the active event is over
     double level;   // The current output value
@@ -237,7 +237,7 @@ typedef struct ESys_Mem* ESys;
  * Returns the newly created pacing system
  */
 ESys
-ESys_Create(ESys_Flag* flag)
+ESys_Create(double initial_time, ESys_Flag* flag)
 {
     ESys sys = (ESys)malloc(sizeof(struct ESys_Mem));
     if (sys == 0) {
@@ -245,13 +245,14 @@ ESys_Create(ESys_Flag* flag)
         return 0;
     }
 
-    sys->time = 0;
+    sys->time = initial_time;
+    sys->initial_time = initial_time;
     sys->n_events = -1; // Used to indicate unpopulated system
     sys->events = NULL;
     sys->head = NULL;
     sys->fire = NULL;
-    sys->tnext = 0;
-    sys->tdown = 0;
+    sys->tnext = initial_time;
+    sys->tdown = initial_time;
     sys->level = 0;
 
     if(flag != 0) *flag = ESys_OK;
@@ -315,11 +316,11 @@ ESys_Reset(ESys sys)
     }
 
     // Reset the properties of the event system
-    sys->time = 0;
+    sys->time = sys->initial_time;
     sys->head = head;
     sys->fire = 0;
-    sys->tnext = 0;
-    sys->tdown = 0;
+    sys->tnext = sys->initial_time;
+    sys->tdown = sys->initial_time;
     sys->level = 0;
 
     return ESys_OK;
@@ -596,113 +597,113 @@ ESys_GetLevel(ESys sys, ESys_Flag* flag)
 
 /*
  *
- * Fixed-form code starts here
+ * Time-series code starts here
  *
  */
 
 /*
- * Fixed-form pacing error flags
+ * Time series pacing error flags
  */
-typedef int FSys_Flag;
-#define FSys_OK                             0
-#define FSys_OUT_OF_MEMORY                  -1
+typedef int TSys_Flag;
+#define TSys_OK                             0
+#define TSys_OUT_OF_MEMORY                  -1
 // General
-#define FSys_INVALID_SYSTEM                 -10
-#define FSys_POPULATED_SYSTEM               -11
-#define FSys_UNPOPULATED_SYSTEM             -12
+#define TSys_INVALID_SYSTEM                 -10
+#define TSys_POPULATED_SYSTEM               -11
+#define TSys_UNPOPULATED_SYSTEM             -12
 // Populating the system
-#define FSys_POPULATE_INVALID_TIMES         -20
-#define FSys_POPULATE_INVALID_VALUES        -21
-#define FSys_POPULATE_SIZE_MISMATCH         -22
-#define FSys_POPULATE_NOT_ENOUGH_DATA       -23
-#define FSys_POPULATE_INVALID_TIMES_DATA    -24
-#define FSys_POPULATE_INVALID_VALUES_DATA   -25
-#define FSys_POPULATE_DECREASING_TIMES_DATA -26
-#define FSys_POPULATE_INVALID_PROTOCOL      -27
+#define TSys_POPULATE_INVALID_TIMES         -20
+#define TSys_POPULATE_INVALID_VALUES        -21
+#define TSys_POPULATE_SIZE_MISMATCH         -22
+#define TSys_POPULATE_NOT_ENOUGH_DATA       -23
+#define TSys_POPULATE_INVALID_TIMES_DATA    -24
+#define TSys_POPULATE_INVALID_VALUES_DATA   -25
+#define TSys_POPULATE_DECREASING_TIMES_DATA -26
+#define TSys_POPULATE_INVALID_PROTOCOL      -27
 
 /*
- * Sets a python exception based on a fixed-form pacing error flag.
+ * Sets a python exception based on a time-series pacing error flag.
  *
  * Arguments
  *  flag : The python error flag to base the message on.
  */
 void
-FSys_SetPyErr(FSys_Flag flag)
+TSys_SetPyErr(TSys_Flag flag)
 {
     switch(flag) {
-    case FSys_OK:
+    case TSys_OK:
         break;
-    case FSys_OUT_OF_MEMORY:
-        PyErr_SetString(PyExc_Exception, "F-Pacing error: Memory allocation failed.");
+    case TSys_OUT_OF_MEMORY:
+        PyErr_SetString(PyExc_Exception, "T-Pacing error: Memory allocation failed.");
         break;
     // General
-    case FSys_INVALID_SYSTEM:
-        PyErr_SetString(PyExc_Exception, "F-Pacing error: Invalid pacing system provided.");
+    case TSys_INVALID_SYSTEM:
+        PyErr_SetString(PyExc_Exception, "T-Pacing error: Invalid pacing system provided.");
         break;
-    case FSys_POPULATED_SYSTEM:
-        PyErr_SetString(PyExc_Exception, "F-Pacing error: Pacing system already populated.");
+    case TSys_POPULATED_SYSTEM:
+        PyErr_SetString(PyExc_Exception, "T-Pacing error: Pacing system already populated.");
         break;
-    case FSys_UNPOPULATED_SYSTEM:
-        PyErr_SetString(PyExc_Exception, "F-Pacing error: Pacing system not populated.");
+    case TSys_UNPOPULATED_SYSTEM:
+        PyErr_SetString(PyExc_Exception, "T-Pacing error: Pacing system not populated.");
         break;
     // Populate
-    case FSys_POPULATE_INVALID_PROTOCOL:
-        PyErr_SetString(PyExc_Exception, "F-Pacing error: Invalid protocol python object passed.");
+    case TSys_POPULATE_INVALID_PROTOCOL:
+        PyErr_SetString(PyExc_Exception, "T-Pacing error: Invalid protocol python object passed.");
         break;
-    case FSys_POPULATE_INVALID_TIMES:
-        PyErr_SetString(PyExc_Exception, "F-Pacing error: Invalid times array passed.");
+    case TSys_POPULATE_INVALID_TIMES:
+        PyErr_SetString(PyExc_Exception, "T-Pacing error: Invalid times array passed.");
         break;
-    case FSys_POPULATE_INVALID_VALUES:
-        PyErr_SetString(PyExc_Exception, "F-Pacing error: Invalid values array passed.");
+    case TSys_POPULATE_INVALID_VALUES:
+        PyErr_SetString(PyExc_Exception, "T-Pacing error: Invalid values array passed.");
         break;
-    case FSys_POPULATE_SIZE_MISMATCH:
-        PyErr_SetString(PyExc_Exception, "F-Pacing error: Sizes of times and values arrays don't match.");
+    case TSys_POPULATE_SIZE_MISMATCH:
+        PyErr_SetString(PyExc_Exception, "T-Pacing error: Sizes of times and values arrays don't match.");
         break;
-    case FSys_POPULATE_NOT_ENOUGH_DATA:
-        PyErr_SetString(PyExc_Exception, "F-Pacing error: Time-series must contain at least two data points.");
+    case TSys_POPULATE_NOT_ENOUGH_DATA:
+        PyErr_SetString(PyExc_Exception, "T-Pacing error: Time-series must contain at least two data points.");
         break;
-    case FSys_POPULATE_INVALID_TIMES_DATA:
-        PyErr_SetString(PyExc_Exception, "F-Pacing error: Times array must contain only floats.");
+    case TSys_POPULATE_INVALID_TIMES_DATA:
+        PyErr_SetString(PyExc_Exception, "T-Pacing error: Times array must contain only floats.");
         break;
-    case FSys_POPULATE_INVALID_VALUES_DATA:
-        PyErr_SetString(PyExc_Exception, "F-Pacing error: Values array must contain only floats.");
+    case TSys_POPULATE_INVALID_VALUES_DATA:
+        PyErr_SetString(PyExc_Exception, "T-Pacing error: Values array must contain only floats.");
         break;
-    case FSys_POPULATE_DECREASING_TIMES_DATA:
-        PyErr_SetString(PyExc_Exception, "F-Pacing error: Times array must be non-decreasing.");
+    case TSys_POPULATE_DECREASING_TIMES_DATA:
+        PyErr_SetString(PyExc_Exception, "T-Pacing error: Times array must be non-decreasing.");
         break;
     // Unknown
     default:
-        PyErr_Format(PyExc_Exception, "F-Pacing error: Unlisted error %d", (int)flag);
+        PyErr_Format(PyExc_Exception, "T-Pacing error: Unlisted error %d", (int)flag);
         break;
     };
 }
 
 /*
- * Fixed-form pacing system
+ * Time series pacing system
  */
-struct FSys_Mem {
+struct TSys_Mem {
     Py_ssize_t n_points;   // The number of entries in the time and pace arrays
     double* times;  // The time array
     double* values; // The values array
     Py_ssize_t last_index; // The index of the most recently returned value
     //double level;   // The current output value
 };
-typedef struct FSys_Mem* FSys;
+typedef struct TSys_Mem* TSys;
 
 /*
- * Creates a fixed-form pacing system
+ * Creates a time series pacing system
  *
  * Arguments
- *  flag : The address of a fixed-form pacing error flag or NULL
+ *  flag : The address of a time series pacing error flag or NULL
  *
- * Returns the newly created fixed-form pacing system
+ * Returns the newly created time series pacing system
  */
-FSys
-FSys_Create(FSys_Flag* flag)
+TSys
+TSys_Create(TSys_Flag* flag)
 {
-    FSys sys = (FSys)malloc(sizeof(struct FSys_Mem));
+    TSys sys = (TSys)malloc(sizeof(struct TSys_Mem));
     if (sys == 0) {
-        if(flag != 0) *flag = FSys_OUT_OF_MEMORY;
+        if(flag != 0) *flag = TSys_OUT_OF_MEMORY;
         return 0;
     }
 
@@ -711,22 +712,22 @@ FSys_Create(FSys_Flag* flag)
     sys->values = NULL;
     sys->last_index = 0;
 
-    if(flag != 0) *flag = FSys_OK;
+    if(flag != 0) *flag = TSys_OK;
     return sys;
 }
 
 /*
- * Destroys a fixed-form pacing system and frees the memory it occupies.
+ * Destroys a time series pacing system and frees the memory it occupies.
  *
  * Arguments
- *  sys : The fixed-form pacing system to destroy
+ *  sys : The time series pacing system to destroy
  *
- * Returns a fixed-form pacing error flag.
+ * Returns a time series pacing error flag.
  */
-FSys_Flag
-FSys_Destroy(FSys sys)
+TSys_Flag
+TSys_Destroy(TSys sys)
 {
-    if(sys == 0) return FSys_INVALID_SYSTEM;
+    if(sys == 0) return TSys_INVALID_SYSTEM;
     if(sys->times != NULL) {
         free(sys->times);
         sys->times = NULL;
@@ -736,39 +737,39 @@ FSys_Destroy(FSys sys)
         sys->values = NULL;
     }
     free(sys);
-    return FSys_OK;
+    return TSys_OK;
 }
 
 /*
- * Populates a fixed-form pacing system using two Python list objects
+ * Populates a time series pacing system using two Python list objects
  * containing an equal number of floating point numbers.
  * Returns an error if the system already has data.
  *
  * Arguments
- *  sys    : The fixed-form pacing system to add the data to.
+ *  sys    : The time series pacing system to add the data to.
  *  times  : A Python list of (non-decreasing) floats.
  *  values : An equally sized Python list of floats.
  *
- * Returns a fixed-form pacing error flag.
+ * Returns a time series pacing error flag.
  */
-FSys_Flag
-FSys_Populate(FSys sys, PyObject* protocol)
+TSys_Flag
+TSys_Populate(TSys sys, PyObject* protocol)
 {
     int i;
     Py_ssize_t n;
     PyObject *times_list, *values_list;
 
     // Check ESys
-    if(sys == 0) return FSys_INVALID_SYSTEM;
-    if (sys->n_points != -1) return FSys_POPULATED_SYSTEM;
-    if (protocol == Py_None) return FSys_POPULATE_INVALID_PROTOCOL;
+    if(sys == 0) return TSys_INVALID_SYSTEM;
+    if (sys->n_points != -1) return TSys_POPULATED_SYSTEM;
+    if (protocol == Py_None) return TSys_POPULATE_INVALID_PROTOCOL;
 
     // Get PyList from protocol (will need to decref!)
     times_list = PyObject_CallMethod(protocol, "times", NULL); // Returns a new reference
-    if(times_list == NULL) return FSys_POPULATE_INVALID_PROTOCOL;
+    if(times_list == NULL) return TSys_POPULATE_INVALID_PROTOCOL;
     if(!PyList_Check(times_list)) {
         Py_DECREF(times_list);
-        return FSys_POPULATE_INVALID_TIMES;
+        return TSys_POPULATE_INVALID_TIMES;
     }
 
     // Check and convert times list
@@ -782,12 +783,12 @@ FSys_Populate(FSys sys, PyObject* protocol)
 
     if (PyErr_Occurred()) {
         free(sys->times); sys->times = NULL;
-        return FSys_POPULATE_INVALID_TIMES_DATA;
+        return TSys_POPULATE_INVALID_TIMES_DATA;
     }
     for(i=1; i<n; i++) {
         if(sys->times[i] < sys->times[i-1]) {
             free(sys->times); sys->times = NULL;
-            return FSys_POPULATE_DECREASING_TIMES_DATA;
+            return TSys_POPULATE_DECREASING_TIMES_DATA;
         }
     }
 
@@ -795,12 +796,12 @@ FSys_Populate(FSys sys, PyObject* protocol)
     values_list = PyObject_CallMethod(protocol, (char*)"values", NULL); // Returns a new reference
     if(values_list == NULL) {
         free(sys->times); sys->times = NULL;
-        return FSys_POPULATE_INVALID_PROTOCOL;
+        return TSys_POPULATE_INVALID_PROTOCOL;
     }
     if(!PyList_Check(values_list) || PyList_Size(values_list) != n) {
         free(sys->times); sys->times = NULL;
         Py_DECREF(values_list);
-        return FSys_POPULATE_INVALID_VALUES;
+        return TSys_POPULATE_INVALID_VALUES;
     }
     sys->values = (double*)malloc((size_t)n * sizeof(double));
     for(i=0; i<n; i++) {
@@ -812,13 +813,13 @@ FSys_Populate(FSys sys, PyObject* protocol)
     if (PyErr_Occurred()) {
         free(sys->times); sys->times = NULL;
         free(sys->values); sys->values = NULL;
-        return FSys_POPULATE_INVALID_VALUES_DATA;
+        return TSys_POPULATE_INVALID_VALUES_DATA;
     }
 
     // Update pacing system and return
     sys->n_points = n;
     sys->last_index = 0;
-    return FSys_OK;
+    return TSys_OK;
 }
 
 /*
@@ -834,7 +835,7 @@ FSys_Populate(FSys sys, PyObject* protocol)
  * using the flag argument!
  */
 double
-FSys_GetLevel(FSys sys, double time, FSys_Flag* flag)
+TSys_GetLevel(TSys sys, double time, TSys_Flag* flag)
 {
     // Index and time at left, mid and right point, plus guessed point
     Py_ssize_t ileft, imid, iright, iguess;
@@ -843,11 +844,11 @@ FSys_GetLevel(FSys sys, double time, FSys_Flag* flag)
 
     // Check system
     if(sys == 0) {
-        if(flag != 0) *flag = FSys_INVALID_SYSTEM;
+        if(flag != 0) *flag = TSys_INVALID_SYSTEM;
         return -1;
     }
     if(sys->n_points < 0) {
-        if(flag != 0) *flag = FSys_UNPOPULATED_SYSTEM;
+        if(flag != 0) *flag = TSys_UNPOPULATED_SYSTEM;
         return -1;
     }
 
@@ -860,7 +861,7 @@ FSys_GetLevel(FSys sys, double time, FSys_Flag* flag)
     tleft = sys->times[ileft];
     if (tleft > time) {
         // Out-of-bounds on the left, return left-most value
-        if(flag != 0) *flag = FSys_OK;
+        if(flag != 0) *flag = TSys_OK;
         return sys->values[ileft];
     }
 
@@ -869,7 +870,7 @@ FSys_GetLevel(FSys sys, double time, FSys_Flag* flag)
     tright = sys->times[iright];
     if (tright <= time) {
         // Out-of-bounds on the right, return right-most value
-        if(flag != 0) *flag = FSys_OK;
+        if(flag != 0) *flag = TSys_OK;
         return sys->values[iright];
     }
 
@@ -909,18 +910,32 @@ FSys_GetLevel(FSys sys, double time, FSys_Flag* flag)
 
     // Handle special case of time == tright
     // (Because otherwise it can happen that tleft == tright, which would give
-    //  a divide-by-zero in the interpolateion)
+    //  a divide-by-zero in the interpolation)
     if (time == tright) {
-        if(flag != 0) *flag = FSys_OK;
+        if(flag != 0) *flag = TSys_OK;
         sys->last_index = iright;
         return sys->values[iright];
     }
 
     // Find the correct value using linear interpolation
-    if(flag != 0) *flag = FSys_OK;
+    if(flag != 0) *flag = TSys_OK;
     sys->last_index = ileft;
     vleft = sys->values[ileft];
     return vleft + (sys->values[iright] - vleft) * (time - tleft) / (tright - tleft);
 }
 
+/*
+ * Pacing types
+ */
+union PSys {
+    ESys esys;
+    TSys tsys;
+};
+
+enum PSysType {
+    PSys_NOT_SET,
+    ESys_TYPE,
+    TSys_TYPE
+};
+
 #endif

myokit/_unit.py

@@ -258,7 +258,7 @@ class Unit:
 
         Returns a :class:`myokit.Quantity`.
 
-        Raises a :class:`myokit.IncompatibleUnitError` if the units cannot be
+        Raises an :class:`myokit.IncompatibleUnitError` if the units cannot be
         converted.'
         """
         # Check unit1

myokit/formats/__init__.py

@@ -664,3 +664,181 @@ def register_external_ewriter(name, ewriter_class):
             _scan_for_internal_formats()
         _EWRITERS[name] = ewriter_class
 
+
+class SweepSource:
+    """
+    Interface for classes that provide time-series data organised into *sweeps*
+    (or *records* or *episodes*) and *channels* (or *traces*).
+
+    The :class:`SweepSource` interface defines methods to get the number of
+    sweeps and channels, the names and units of the channels, and the data
+    stored in channels either as numpy arrays or in a :class:`myokit.DataLog`.
+
+    Each sweep contains the same number of channels, and each channel is
+    represented as a 1d array. In most cases these arrays have the same length
+    for every sweep, but whether this is the case for the current source can be
+    tested with :meth:`equal_length_sweeps`.
+
+    Data can be retrieved sweep by sweep::
+
+        (time[0], sweep[0]),        n_t data points, n_c channels of n_t points
+        (time[1], sweep[1]),
+        (time[2], sweep[2]),
+        ...
+        (time[n_s], sweep[n_s])
+
+    This allows plotting in the common "overlaid" fashion, i.e. plotting every
+    ``sweep[i] against ``time[0]``.
+
+    For other types of analysis (e.g. parameter estimation) the data can also
+    be returned as single time series::
+
+        time                            sum(n_t[i]) data points
+        sweep[0] + sweep[1] + ...       n_c channels, with sum(n_t[i]) points
+
+    Some formats can also contain information from which D/A output signals can
+    be reconstructed. These can be accessed using the :meth:`da`.
+
+    """
+    def channel(self, channel_id, join_sweeps=False):
+        """
+        Returns the data for a single channel, identified by integer or string
+        ``channel_id``.
+
+        With ``join_sweeps=False``, the data is returned as a tuple
+        ``(times, sweeps)`` where ``times`` and ``sweeps`` are 2d numpy arrays
+        indexed so that ``times[i][j]`` is the ``j``-th time point for sweep
+        ``i``.
+
+        If ``join_sweeps=True`` the sweeps are joined together, and a tuple
+        ``(times, values)`` is returned ``times`` and ``values`` are 1d arrays.
+        """
+        raise NotImplementedError
+
+    def channel_count(self):
+        """ Returns the number of channels. """
+        raise NotImplementedError
+
+    def channel_names(self, index=None):
+        """
+        Returns the names of all channels or the name of a specific channel
+        ``index``.
+        """
+        raise NotImplementedError
+
+    def channel_units(self, index=None):
+        """
+        Returns the units (as :class:`myokit.Unit`) of all channels or the
+        units of a specific channel ``index``.
+        """
+        raise NotImplementedError
+
+    def da(self, output_id, join_sweeps=False):
+        """ Like :meth:`channel`, but returns reconstructed D/A signals. """
+        raise NotImplementedError
+
+    def da_count(self):
+        """
+        Returns the available number of reconstructed D/A output channels.
+
+        This should return 0 if D/A channels are not supported.
+        """
+        raise NotImplementedError
+
+    def da_names(self, index=None):
+        """
+        Returns the names of all reconstructed D/A output channels or the name
+        of a specific output channel ``index``.
+
+        This will raise a ``NotImplementedError`` if D/A channels are not
+        supported.
+        """
+        raise NotImplementedError
+
+    def da_protocol(self, output_id=None, tu='ms', vu='mV', cu='pA',
+                    n_digits=9):
+        """
+        Returns a :class:`myokit.Protocol` representation of the D/A output
+        channel specified by name or integer ``output_id``.
+
+        If no explicit output channel is set, a guess will be made.
+
+        Time units will be converted to ``tu``, voltage units to ``vu``, and
+        current units to ``cu``. Other unit types will be left unchanged. Units
+        may be specified as :class:`myokit.Unit` objects or strings.
+
+        By default, floating point numbers in the protocol will be rounded to
+        9 digits after the decimal point. This can be customised using the
+        argument ``n_digits``.
+
+        If a D/A output cannot be converted to a :class:`myokit.Protocol`, a
+        ``ValueError`` is raised. A ``NotImplementedError`` is raised if D/A
+        channels are not supported at all.
+        """
+        raise NotImplementedError
+
+    def da_units(self, index=None):
+        """
+        Returns the units (as :class:`myokit.Unit`) of all reconstructed D/A
+        output channels or the units of a specific output channel ``index``.
+
+        This will raise a ``NotImplementedError`` if D/A channels are not
+        supported.
+        """
+        raise NotImplementedError
+
+    def equal_length_sweeps(self):
+        """
+        Returns ``True`` only if each sweep in this source has the same length.
+        """
+        raise NotImplementedError
+
+    def log(self, join_sweeps=False, use_names=False, include_da=True):
+        """
+        Returns a :class:`myokit.DataLog` containing the data from all
+        channels.
+
+        The log will have a single entry ``time`` corresponding to the time of
+        the first sweep if ``join_sweeps`` is ``False``, or the time of all
+        points when ``join_sweeps`` is ``True``.
+
+        Names will have a systematic form ``i_sweep.i_channel.label``, for
+        example ``0.1.channel`` for sweep 0 of recorded channel 1, or
+        ``3.0.da`` for sweep 3 of reconstructed D/A output 0. These can also be
+        accessed using the syntax ``log['channel', 1, 0]`` and
+        ``log['da', 0, 3]``.
+
+        To obtain a log with the user-specified names from the source instead,
+        set ``use_names`` to ``True``. This will result in names such as
+        ``0.IN 1`` or ``3.Cmd 0``.
+
+        To exclude D/A signal reconstructions, set ``include_da`` to ``False``.
+
+        A call with ``join_sweeps=False`` on a source where
+        :meth:`equal_length_sweeps()` returns ``False`` will raise a
+        ``ValueError``.
+        """
+        raise NotImplementedError
+
+    def meta_str(self, verbose=False):
+        """
+        Optional method that returns a multi-line string with unstructured meta
+        data about the source and its contents.
+
+        Will return ``None`` if no such string is available.
+        """
+        return None  # pragma: no cover
+
+    def sweep_count(self):
+        """
+        Returns the number of sweeps.
+
+        Note that a source with zero recorded channels may still report a
+        non-zero number of sweeps if it can provide D/A outputs.
+        """
+        raise NotImplementedError
+
+    def time_unit(self):
+        """ Returns the time unit used in this source. """
+        raise NotImplementedError
+