Integrate

class baseband.tasks.Integrate(ih, step=None, phase=None, *, start=0, average=True, samples_per_frame=1, dtype=None)

Bases: baseband_tasks.base.BaseTaskBase

Integrate a stream stepwise.

Parameters

ihtask or baseband stream reader

Input data stream, with time as the first axis.

stepint or Quantity, optional

Interval over which to integrate. For time invervals, should have units of time. For phase intervals, units should be consistent with what the phase callable returns. If no phase callable is passed in, then if step is integer, it is taken to be a number of samples in the underlying stream that should be integrated over, and if step is omitted, integration is over all samples.

phasecallable

Should return full pulse phase (i.e., including cycle count) for given input times (passed in as ‘~astropy.time.Time’). The output should be compatible with step, i.e., generally an Quantity with angular units.

startTime or int, optional

Time or offset at which to start the integration. If an offset or if step is integer, the actual start time will the underlying sample time nearest to the requested one. Default: 0 (start of stream).

averagebool, optional

Whether the output should be the average of all entries that contributed to it, or rather the sum, in a structured array that holds both 'data' and 'count' items.

samples_per_frameint, optional

Number of samples to process in one go. This can be used to optimize the process. With many samples per bin, the default of 1 should be OK.

dtypedtype, optional

Output dtype. Generally, the default of the dtype of the underlying stream is good enough, but can be used to increase precision. Note that if average=True, it is the user’s responsibilty to pass in a structured dtype.

Notes

If there are not many samples per bin, either set samples_per_frame to a larger number or ensure that samples_per_frame of the underlying stream is not small (larger than, say, 20). If both are small, there will be a relatively large overhead in calculating phases.

Since time or phase bins are typically not an integer multiple of the underlying bin spacing, the integrated samples will generally not contain the same number of samples. The actual number of samples is counted, and for average=True, the sums have been divided by these counts, with bins with no points set to NaN. For average=False, the arrays returned by read are structured arrays with data and count fields.

Attributes Summary

closed
complex_data
dtype	Data type of the output.
meta
ndim	Number of dimensions of the output.
offset
sample_rate	Number of complete samples per second.
sample_shape	Shape of a complete sample.
samples_per_frame	Number of samples per frame of data.
shape	Shape of the output.
size	Number of component samples in the output.
start_time	Start time of the output.
stop_time	Time at the end of the output, just after the last sample.
time	Time of the sample pointer's current offset in the output.

Methods Summary

close()	Close task.
read([count, out])	Read a number of complete samples.
seek(offset[, whence])	Change the sample pointer position.
tell([unit])	Current offset in the file.

Attributes Documentation

closed = False

complex_data

dtype

Data type of the output.

meta

ndim

Number of dimensions of the output.

offset = 0

sample_rate

Number of complete samples per second.

sample_shape

Shape of a complete sample.

samples_per_frame

Number of samples per frame of data.

For compatibility with file readers, to help indicate what a nominal chunk of data is.

shape

Shape of the output.

size

Number of component samples in the output.

start_time

Start time of the output.

See also time and stop_time.

stop_time

Time at the end of the output, just after the last sample.

See also start_time and time.

time

Time of the sample pointer’s current offset in the output.

See also start_time and stop_time.

Methods Documentation

close()

Close task.

Note that this does not explicitly close the underlying source; instead, it just deletes the reference to it.

read(count=None, out=None)

Read a number of complete samples.

Parameters

countint or None, optional

Number of complete samples to read. If None (default) or negative, the number of samples left. Ignored if out is given.

outNone or array, optional

Array to store the samples in. If given, count will be inferred from the first dimension; the remaining dimensions should equal sample_shape.

Returns

outndarray of float or complex

The first dimension is sample-time, and the remaining ones are as given by sample_shape.

seek(offset, whence=0)

Change the sample pointer position.

This works like a normal filehandle seek, but the offset is in samples (or a relative or absolute time).

Parameters

offsetint, Quantity, or Time

Offset to move to. Can be an (integer) number of samples, an offset in time units, or an absolute time. For the latter two, the pointer will be moved to the nearest integer sample.

whence{0, 1, 2, ‘start’, ‘current’, or ‘end’}, optional

Like regular seek, the offset is taken to be from the start if whence=0 (default), from the current position if 1, and from the end if 2. One can alternativey use ‘start’, ‘current’, or ‘end’ for 0, 1, or 2, respectively. Ignored if offset is a time.

tell(unit=None)

Current offset in the file.

Parameters

unitUnit or str, optional

Time unit the offset should be returned in. By default, no unit is used, i.e., an integer enumerating samples is returned. For the special string ‘time’, the absolute time is calculated.

Returns

offsetint, Quantity, or Time

Offset in current file (or time at current position).