WireCell::Waveform Namespace Reference

Typedefs
typedef float	real_t
	The type for the signal in each bin. More...
typedef std::complex< float >	complex_t
	The type for the spectrum in each bin. More...
template<typename Val >
using	Sequence = std::vector< Val >
typedef Sequence< real_t >	realseq_t
typedef Sequence< complex_t >	compseq_t
	A complex-valued sequence, eg for discrete spectrum powers. More...
typedef std::pair< int, int >	BinRange
	A half-open range of bins (from first bin to one past last bin) More...
typedef std::vector< BinRange >	BinRangeList
	A list of bin ranges. More...
typedef std::map< int, BinRangeList >	ChannelMasks
	Map channel number to a vector of BinRanges. More...
typedef std::map< std::string, ChannelMasks >	ChannelMaskMap
	Collect channel masks by some label. More...
typedef std::pair< double, double >	Period
	A range of time. More...
typedef std::pair< double, double >	Band
	A range of frequency. More...
typedef std::pair< double, double >	Domain

Functions
BinRangeList	merge (const BinRangeList &br)
	Return a new list with any overlaps formed into unions. More...
BinRangeList	merge (const BinRangeList &br1, const BinRangeList &br2)
	Merge two bin range lists, forming a union from any overlapping ranges. More...
ChannelMasks	merge (const ChannelMasks &one, const ChannelMasks &two)
	Return a new mapping which is the union of all same channel masks. More...
void	merge (ChannelMaskMap &one, ChannelMaskMap &two, std::map< std::string, std::string > &name_map)
int	sample_count (const Domain &domain, double width)
	Return the number of samples needed to cover the domain with sample size width. More...
double	sample_width (const Domain &domain, int count)
	Return the sample size if domain is equally sampled with given number of samples. More...
std::pair< int, int >	sub_sample (const Domain &domain, int nsamples, const Domain &subdomain)
	Return the begin/end sample numbers inside the a subdomain of a domain with nsamples total. More...
template<typename Val >
Sequence< Val >	resample (const Sequence< Val > &wave, const Domain &domain, int nsamples, const Domain &newdomain)
realseq_t	real (const compseq_t &seq)
	Return the real part of the sequence. More...
realseq_t	imag (const compseq_t &seq)
	Return the imaginary part of the sequence. More...
realseq_t	magnitude (const compseq_t &seq)
	Return the magnitude or absolute value of the sequence. More...
realseq_t	phase (const compseq_t &seq)
	Return the phase or arg part of the sequence. More...
template<typename Val >
void	increase (Sequence< Val > &seq, Val scalar)
	Increase (shift) sequence values by scalar. More...
void	increase (Sequence< float > &seq, double scalar)
template<typename Val >
void	increase (Sequence< Val > &seq, const Sequence< Val > &other)
	Increase (shift) sequence values by values in another sequence. More...
template<typename Val >
void	scale (Sequence< Val > &seq, Val scalar)
	Scale (multiply) sequence values by scalar. More...
void	scale (Sequence< float > &seq, double scalar)
template<typename Val >
void	scale (Sequence< Val > &seq, const Sequence< Val > &other)
	Scale (multiply) seq values by values from the other sequence. More...
template<typename Val >
void	shrink (Sequence< Val > &seq, const Sequence< Val > &other)
	Shrink (divide) seq values by values from the other sequence. More...
std::pair< int, int >	edge (const realseq_t &wave)
template<typename Val >
Val	sum (const Sequence< Val > &seq)
	Return sum of all entries in sequence. More...
template<typename Val >
Val	sum2 (const Sequence< Val > &seq)
	Return sum of square of all entries in sequence. More...
std::pair< double, double >	mean_rms (const realseq_t &wave)
real_t	median (realseq_t &wave)
real_t	median_binned (realseq_t &wave)
real_t	percentile (realseq_t &wave, real_t percentage)
real_t	percentile_binned (realseq_t &wave, real_t percentage)
compseq_t	dft (realseq_t seq)
realseq_t	linear_convolve (Waveform::realseq_t in1, Waveform::realseq_t in2, bool truncate=true)
realseq_t	replace_convolve (Waveform::realseq_t wave, Waveform::realseq_t newres, Waveform::realseq_t oldres, bool truncate=true)
realseq_t	idft (compseq_t spec)
short	most_frequent (const std::vector< short > &vals)
	Return the smallest, most frequent value to appear in vector. More...

Typedef Documentation

typedef std::pair<double,double> WireCell::Waveform::Band

A range of frequency.

Definition at line 69 of file Waveform.h.

typedef std::pair<int,int> WireCell::Waveform::BinRange

A half-open range of bins (from first bin to one past last bin)

Definition at line 38 of file Waveform.h.

typedef std::vector<BinRange> WireCell::Waveform::BinRangeList

A list of bin ranges.

Definition at line 41 of file Waveform.h.

typedef std::map<std::string, ChannelMasks> WireCell::Waveform::ChannelMaskMap

Collect channel masks by some label.

Definition at line 59 of file Waveform.h.

typedef std::map<int, BinRangeList > WireCell::Waveform::ChannelMasks

Map channel number to a vector of BinRanges.

Definition at line 50 of file Waveform.h.

typedef std::complex<float> WireCell::Waveform::complex_t

The type for the spectrum in each bin.

Definition at line 21 of file Waveform.h.

typedef Sequence<complex_t> WireCell::Waveform::compseq_t

A complex-valued sequence, eg for discrete spectrum powers.

Definition at line 34 of file Waveform.h.

typedef std::pair<double,double> WireCell::Waveform::Domain

A domain of a sequence is bounded by the time or frequency at the start of its first element and that at the end of its last.

Definition at line 75 of file Waveform.h.

typedef std::pair<double,double> WireCell::Waveform::Period

A range of time.

Definition at line 66 of file Waveform.h.

typedef float WireCell::Waveform::real_t

The type for the signal in each bin.

Definition at line 18 of file Waveform.h.

typedef Sequence<real_t> WireCell::Waveform::realseq_t

Definition at line 31 of file Waveform.h.

template<typename Val >

using WireCell::Waveform::Sequence = typedef std::vector<Val>

A sequence is an ordered array of values (real or complex). By itself it is not associated with a domain.

Definition at line 27 of file Waveform.h.

Function Documentation

Waveform::compseq_t WireCell::Waveform::dft

(

realseq_t

seq

)

Discrete Fourier transform of real sequence. Returns full spectrum. No normalization scaling applied

Definition at line 141 of file Waveform.cxx.

{
    auto v = Eigen::Map<Eigen::VectorXf>(wave.data(), wave.size());
    Eigen::FFT<Waveform::real_t> trans;
    Eigen::VectorXcf ret = trans.fwd(v);
    return compseq_t(ret.data(), ret.data()+ret.size());
}

std::pair< int, int > WireCell::Waveform::edge

(

const realseq_t &

wave

)

Return a pair of indices into wave which bound non-zero region. First index is of first non-zero sample, second index is one past last non-zero sample. If entire wave is empty then both are set to size().

Definition at line 121 of file Waveform.cxx.

{
    const int size = wave.size();
    int imin=size, imax=size;

    for (int ind=0; ind < size; ++ind) {
        const real_t val = wave[ind];
        if (val != 0.0) {
            if (imin == size) { // found start edge
                imin = ind;
            }
            if (imin < size) {
                imax = ind+1;
            }
        }
    }
    return std::make_pair(imin, imax);
}

Waveform::realseq_t WireCell::Waveform::idft

(

compseq_t

spec

)

Inverse, discrete Fourier transform. Expects full spectrum (twice Nyquist frequency). Applies the 1/Nsamples normalization.

Definition at line 149 of file Waveform.cxx.

{
    Eigen::FFT<Waveform::real_t> trans;
    auto v = Eigen::Map<Eigen::VectorXcf>(spec.data(), spec.size());
    Eigen::VectorXf ret;
    trans.inv(ret, v);
    return realseq_t(ret.data(), ret.data()+ret.size());
}

Waveform::realseq_t WireCell::Waveform::imag

(

const compseq_t &

seq

)

Return the imaginary part of the sequence.

Definition at line 60 of file Waveform.cxx.

{
    return c2r(seq, [](Waveform::complex_t c) { return std::imag(c); });
}

template<typename Val >

void WireCell::Waveform::increase	(	Sequence< Val > &	seq,
		Val	scalar
	)

Increase (shift) sequence values by scalar.

Definition at line 129 of file Waveform.h.

                                                      {
            std::transform(seq.begin(), seq.end(), seq.begin(), 
                           [scalar](Val x) { return x+scalar; });
        }

void WireCell::Waveform::increase ( Sequence< float > &  seq, double  scalar  )

inline

Definition at line 133 of file Waveform.h.

                                                                  {
            increase(seq, (float)scalar);
        }

template<typename Val >

void WireCell::Waveform::increase	(	Sequence< Val > &	seq,
		const Sequence< Val > &	other
	)

Increase (shift) sequence values by values in another sequence.

Definition at line 139 of file Waveform.h.

                                                                      {
            std::transform(seq.begin(), seq.end(), other.begin(), seq.begin(),
                           std::plus<Val>());
        }

Waveform::realseq_t WireCell::Waveform::linear_convolve	(	Waveform::realseq_t	in1,
		Waveform::realseq_t	in2,
		bool	truncate = true
	)

Definition at line 159 of file Waveform.cxx.

{
    size_t n1_orig = in1.size(), n2_orig = in2.size();
    size_t n_out = n1_orig + n2_orig - 1;

    in1.resize(n_out, 0);
    in2.resize(n_out, 0);

    auto v1 = Eigen::Map<Eigen::VectorXf>(in1.data(), in1.size());
    auto v2 = Eigen::Map<Eigen::VectorXf>(in2.data(), in2.size());

    Eigen::FFT<Waveform::real_t> trans;

    Eigen::VectorXcf s1 = trans.fwd(v1);
    Eigen::VectorXcf s2 = trans.fwd(v2);
    Eigen::VectorXcf s12 = (s1.array() * s2.array()).matrix();
    Eigen::VectorXf vret;
    trans.inv(vret, s12);
    realseq_t ret(vret.data(), vret.data()+vret.size());
    if (truncate) {
        ret.resize(n1_orig);
    }
    return ret;
}

Waveform::realseq_t WireCell::Waveform::magnitude

(

const compseq_t &

seq

)

Return the magnitude or absolute value of the sequence.

Definition at line 65 of file Waveform.cxx.

{
    return c2r(seq, [](Waveform::complex_t c) { return std::abs(c); });
}

std::pair< double, double > WireCell::Waveform::mean_rms

(

const realseq_t &

wave

)

Definition at line 24 of file Waveform.cxx.

{
    const int n = wf.size();
    if (n==0) {
        return std::make_pair<double,double>(0,0);
    }
    if (n==1) {
        return std::make_pair<double,double>(wf[0],0);
    }

    // if left as float, numerical precision will lead to many NaN for
    // the RMS due to sometimes subtracting similar sized numbers.
    std::vector<double> wfd(wf.begin(), wf.end());

    const double wsum = Waveform::sum(wfd);
    const double w2sum = Waveform::sum2(wfd);
    const double mean = wsum/n;
    const double rms = sqrt( (w2sum - wsum*wsum/n) / n );
    //   const double rms = sqrt( (w2sum - wsum*wsum/n) / (n-1) );
    return std::make_pair(mean,rms);
}

Waveform::real_t WireCell::Waveform::median

(

Waveform::realseq_t &

wave

)

Definition at line 76 of file Waveform.cxx.

{
    return percentile(wave,0.5);
}

Waveform::real_t WireCell::Waveform::median_binned

(

Waveform::realseq_t &

wave

)

Definition at line 81 of file Waveform.cxx.

{
    return percentile_binned(wave,0.5);
}

WireCell::Waveform::BinRangeList WireCell::Waveform::merge

(

const BinRangeList &

br

)

Return a new list with any overlaps formed into unions.

Definition at line 222 of file Waveform.cxx.

{
    WireCell::Waveform::BinRangeList tmp(brl.begin(), brl.end());
    WireCell::Waveform::BinRangeList out;
    sort(tmp.begin(), tmp.end());
    Waveform::BinRange last_br = tmp[0];
    out.push_back(last_br);

    for (size_t ind=1; ind<tmp.size(); ++ind) {
        Waveform::BinRange this_br = tmp[ind];
        if (out.back().second >= this_br.first) {
          out.back().second = this_br.second;
          continue;
        }
        out.push_back(this_br);
    }
    return out;
}

WireCell::Waveform::BinRangeList WireCell::Waveform::merge	(	const BinRangeList &	br1,
		const BinRangeList &	br2
	)

Merge two bin range lists, forming a union from any overlapping ranges.

Definition at line 243 of file Waveform.cxx.

{
    WireCell::Waveform::BinRangeList out;
    out.reserve(br1.size() + br2.size());
    out.insert(out.end(), br1.begin(), br1.end());
    out.insert(out.end(), br2.begin(), br2.end());
    return merge(out);
}

WireCell::Waveform::ChannelMasks WireCell::Waveform::merge	(	const ChannelMasks &	one,
		const ChannelMasks &	two
	)

Return a new mapping which is the union of all same channel masks.

Definition at line 258 of file Waveform.cxx.

{
    WireCell::Waveform::ChannelMasks out = one;
    for (auto const &it : two) {
        int ch = it.first;
        out[ch] = merge(out[ch], it.second);
    }
    return out;
}

void WireCell::Waveform::merge	(	ChannelMaskMap &	one,
		ChannelMaskMap &	two,
		std::map< std::string, std::string > &	name_map
	)

Definition at line 270 of file Waveform.cxx.

                                                                                                            {

    // loop over second map
    for (auto const& it: two){
        std::string name = it.first;
        std::string mapped_name;
        if (name_map.find(name)!=name_map.end()){
            mapped_name = name_map[name];
        }else{
            mapped_name = name;
        }
        if (one.find(mapped_name) != one.end()){
            one[mapped_name] = merge(one[mapped_name],it.second);
        }else{
            one[mapped_name] = it.second;
        }
    }
}

short WireCell::Waveform::most_frequent

(

const std::vector< short > &

vals

)

Return the smallest, most frequent value to appear in vector.

Definition at line 289 of file Waveform.cxx.

{
    const size_t nbins = 1<<16;
    std::vector<unsigned int> hist(nbins, 0);
    for (unsigned short val : vals) {
        hist[val] += 1;
    }
    auto it = std::max_element(hist.begin(), hist.end());
    return it - hist.begin();   // casts back to signed short
}

Waveform::real_t WireCell::Waveform::percentile	(	Waveform::realseq_t &	wave,
		real_t	percentage
	)

Definition at line 87 of file Waveform.cxx.

{
    std::nth_element(wave.begin(), wave.begin()+wave.size()*percentage, wave.end());
    return wave.at(wave.size()*percentage);
}

Waveform::real_t WireCell::Waveform::percentile_binned	(	Waveform::realseq_t &	wave,
		real_t	percentage
	)

Definition at line 93 of file Waveform.cxx.

                                                                                            {
    const auto mm = std::minmax_element(wave.begin(), wave.end());
    const auto vmin = *mm.first;
    const auto vmax = *mm.second;
    const int nbins = wave.size();
    const auto binsize = (vmax-vmin)/nbins;
    Waveform::realseq_t hist(nbins);
    for (auto val : wave) {
        int bin = int(round((val - vmin)/binsize));
        bin = std::max(0, bin);
        bin = std::min(nbins-1, bin);
        hist[bin] += 1.0;
    }

    const int imed = wave.size() * percentage;
    int count = 0;
    for (int ind=0; ind<nbins; ++ind) {
        count += hist[ind];
        if (count > imed) {
            float ret = vmin + ind*binsize;
            return ret;
        }
    }
    // can't reach here, return bogus value.
    return vmin + (vmax-vmin)*percentage;
}

Waveform::realseq_t WireCell::Waveform::phase

(

const compseq_t &

seq

)

Return the phase or arg part of the sequence.

Definition at line 70 of file Waveform.cxx.

{
    return c2r(seq, [](Waveform::complex_t c) { return std::arg(c); });
}

Waveform::realseq_t WireCell::Waveform::real

(

const compseq_t &

seq

)

Return the real part of the sequence.

Definition at line 55 of file Waveform.cxx.

{
    return c2r(seq, [](Waveform::complex_t c) { return std::real(c); });
}

Waveform::realseq_t WireCell::Waveform::replace_convolve	(	Waveform::realseq_t	wave,
		Waveform::realseq_t	newres,
		Waveform::realseq_t	oldres,
		bool	truncate = true
	)

Definition at line 187 of file Waveform.cxx.

{
    size_t sizes[3] = {wave.size(), newres.size(), oldres.size()};
    size_t n_out = sizes[0]+sizes[1]+sizes[2] - *std::min_element(sizes, sizes+3) - 1;

    wave.resize(n_out, 0);
    newres.resize(n_out, 0);
    oldres.resize(n_out, 0);

    auto v1 = Eigen::Map<Eigen::VectorXf>(wave.data(),     wave.size());
    auto v2 = Eigen::Map<Eigen::VectorXf>(newres.data(), newres.size());
    auto v3 = Eigen::Map<Eigen::VectorXf>(oldres.data(), oldres.size());

    Eigen::FFT<Waveform::real_t> trans;

    Eigen::VectorXcf s1 = trans.fwd(v1);
    Eigen::VectorXcf s2 = trans.fwd(v2);
    Eigen::VectorXcf s3 = trans.fwd(v3);

    Eigen::VectorXcf s123 = (s1.array() * s2.array() / s3.array()).matrix();

    Eigen::VectorXf vret;
    trans.inv(vret, s123);
    realseq_t ret(vret.data(), vret.data()+vret.size());
    if (truncate) {
        ret.resize(sizes[0]);
    }
    return ret;
}

template<typename Val >

Sequence<Val> WireCell::Waveform::resample	(	const Sequence< Val > &	wave,
		const Domain &	domain,
		int	nsamples,
		const Domain &	newdomain
	)

Return a new sequence resampled and interpolated from the original wave defined over the domain to a new domain of nsamples.

Definition at line 92 of file Waveform.h.

                                                                                                                       {
            const int oldnsamples = wave.size();
            const double oldstep = sample_width(domain, oldnsamples);
            const double step = sample_width(newdomain, nsamples);
            Sequence<Val> ret;
            for (int ind=0; ind<nsamples; ++ind) {
                double cursor = newdomain.first + ind*step;
                double oldfracsteps = (cursor-domain.first)/oldstep;
                int oldind = int(oldfracsteps);
                if (cursor <= domain.first || oldind <= 0) {
                    ret.push_back(wave[0]);
                    continue;
                }
                if (cursor >= domain.second or oldind+1 >= oldnsamples) {
                    ret.push_back(wave[oldnsamples-1]);
                    continue;
                }
                double d1 = oldfracsteps - oldstep*oldind;
                double d2 = oldstep - d1;
                Val newval = (wave[oldind] * d1 + wave[oldind+1]*d2) / oldstep;
                ret.push_back(newval);
            }
            return ret;
        }

int WireCell::Waveform::sample_count ( const Domain &  domain, double  width  )

inline

Return the number of samples needed to cover the domain with sample size width.

Definition at line 77 of file Waveform.h.

                                                                    {
            return (domain.second-domain.first)/width;
        }

double WireCell::Waveform::sample_width ( const Domain &  domain, int  count  )

inline

Return the sample size if domain is equally sampled with given number of samples.

Definition at line 81 of file Waveform.h.

                                                                    {
            return (domain.second-domain.first)/count;
        }

template<typename Val >

void WireCell::Waveform::scale	(	Sequence< Val > &	seq,
		Val	scalar
	)

Scale (multiply) sequence values by scalar.

Definition at line 146 of file Waveform.h.

                                                   {
            std::transform(seq.begin(), seq.end(), seq.begin(), 
                           [scalar](Val x) { return x*scalar; });
        }

void WireCell::Waveform::scale ( Sequence< float > &  seq, double  scalar  )

inline

Definition at line 150 of file Waveform.h.

                                                               {
            scale(seq, (float)scalar);
        }

template<typename Val >

void WireCell::Waveform::scale	(	Sequence< Val > &	seq,
		const Sequence< Val > &	other
	)

Scale (multiply) seq values by values from the other sequence.

Definition at line 156 of file Waveform.h.

                                                                   {
            std::transform(seq.begin(), seq.end(), other.begin(), seq.begin(),
                           std::multiplies<Val>());
        }

template<typename Val >

void WireCell::Waveform::shrink	(	Sequence< Val > &	seq,
		const Sequence< Val > &	other
	)

Shrink (divide) seq values by values from the other sequence.

Definition at line 162 of file Waveform.h.

                                                                    {
            std::transform(seq.begin(), seq.end(), other.begin(), seq.begin(),
                           std::divides<Val>());
        }

std::pair< int, int > WireCell::Waveform::sub_sample	(	const Domain &	domain,
		int	nsamples,
		const Domain &	subdomain
	)

Return the begin/end sample numbers inside the a subdomain of a domain with nsamples total.

Definition at line 15 of file Waveform.cxx.

{
    const double bin = sample_width(domain, nsamples);
    int beg = ceil((subdomain.first - domain.first) / bin);
    int end = nsamples- ceil((domain.second - subdomain.second) / bin);
    return std::make_pair(std::max(0,beg), std::min(nsamples, end));
}

template<typename Val >

Val WireCell::Waveform::sum

(

const Sequence< Val > &

seq

)

Return sum of all entries in sequence.

Definition at line 178 of file Waveform.h.

                                          {
            return std::accumulate(seq.begin(), seq.end(), Val());
        }

template<typename Val >

Val WireCell::Waveform::sum2

(

const Sequence< Val > &

seq

)

Return sum of square of all entries in sequence.

Definition at line 184 of file Waveform.h.

                                           {
            return std::accumulate(seq.begin(), seq.end(), Val(),
                                   [](const Val& bucket, Val x) {
                                       return bucket + x*x;
                                   });
        }