TTTR.h

Go to the documentation of this file.

#define _CRT_SECURE_NO_DEPRECATE
 
#ifndef TTTRLIB_TTTR_H
#define TTTRLIB_TTTR_H
 
#include <cstdint>
#include <string>
#include <cmath>
#include <algorithm>
#include <iostream>
#include <vector>
#include <cstdio>
#include <map>
#include <array>
#include <memory>       /* shared_ptr */
#include <stdlib.h>     /* malloc, calloc, realloc, exit, free */
#include <numeric>
#include <cinttypes>    /* uint64, int64, etc */
#include <fstream> /* ifstream */
 
#include <boost/bimap.hpp>
//#include <boost/filesystem.hpp> // std::filesystem is not in osx 10.14
 
#ifdef BUILD_PHOTON_HDF
#include "hdf5.h"
#endif
 
#include "Histogram.h"
#include "TTTRHeader.h"
#include "TTTRMask.h"
#include "TTTRRecordReader.h"
#include "TTTRRecordTypes.h"
#include "info.h"
 
 
void selection_by_count_rate(
        int **output, int *n_output,
        unsigned long long *time, int n_time,
        double time_window, int n_ph_max,
        double macro_time_calibration=1.0,
        bool invert=false, bool make_mask=false
);
 
 
void ranges_by_time_window(
    int **output, int *n_output,
    unsigned long long *input, int n_input,
    double minimum_window_length,
    double maximum_window_length = -1,
    int minimum_number_of_photons_in_time_window = -1,
    int maximum_number_of_photons_in_time_window = -1,
    double macro_time_calibration = 1.0,
    bool invert = false
);
 
 
void compute_intensity_trace(
        int **output, int *n_output,
        unsigned long long *input, int n_input,
        double time_window_length,
        double macro_time_resolution = 1.0
);
 
 
template <typename T>
inline void get_array(
    size_t n_valid_events,  
    T *array,               
    T **out,                
    int *n_out              
) {
    *n_out = static_cast<int>(n_valid_events);
    *out = static_cast<T*>(malloc(sizeof(T) * n_valid_events));
 
    for (size_t i = 0; i < n_valid_events; ++i) {
        (*out)[i] = array[i];
    }
}
 
 
class TTTRMask;
 
class TTTR : public std::enable_shared_from_this<TTTR>{
 
    friend class CLSMImage;
    friend class TTTRRange;
    friend class TTTRMask;
    friend class CorrelatorPhotonStream;
 
private:
 
    uint64_t overflow_counter;
 
    std::string filename;
 
    TTTRHeader *header = nullptr;
 
    boost::bimap<std::string, int> container_names = {};
 
    typedef bool (*processRecord_t)(
            uint32_t&,  // input
            uint64_t&,  // overflow counter
            uint64_t&,  // true number of sync pulses
            uint32_t&,  // microtime
            int16_t&,   // channel number (16bit more than enough, negative numbers - potential future special cases
            int16_t&    // the event type: photon, or marker (overflows are treated separately and removed during reading)
    );
 
    std::map<int, processRecord_t> processRecord_map = {
            {PQ_RECORD_TYPE_HHT2v1,      ProcessHHT2v1},
            {PQ_RECORD_TYPE_HHT2v2,      ProcessHHT2v2},
            {PQ_RECORD_TYPE_HHT3v1,      ProcessHHT3v1},
            {PQ_RECORD_TYPE_HHT3v2,      ProcessHHT3v2},
            {PQ_RECORD_TYPE_PHT2,        ProcessPHT2},
            {PQ_RECORD_TYPE_PHT3,        ProcessPHT3},
            {BH_RECORD_TYPE_SPC600_256,  ProcessSPC600_256},
            {BH_RECORD_TYPE_SPC600_4096, ProcessSPC600_4096},
            {BH_RECORD_TYPE_SPC130,      ProcessSPC130},
            {CZ_RECORD_TYPE_CONFOCOR3,   ProcessCzRaw}
    };
 
    int tttr_container_type; // e.g. Becker&Hickl (BH) SPC, PicoQuant (PQ) HT3, PQ-PTU
 
    std::string tttr_container_type_str; // e.g. Becker&Hickl (BH) SPC, PicoQuant (PQ) HT3, PQ-PTU
    int tttr_record_type;                // e.g. BH spc132, PQ HydraHarp (HH) T3, PQ HH T2, etc.
 
    std::FILE *fp;                          /* File handle for all other file types */
 
#ifdef BUILD_PHOTON_HDF
    hid_t hdf5_file;                        /*HDF5 file handle */
#endif
 
 
    size_t fp_records_begin;
 
    uint64_t TTTRRecord;
 
    bool (*processRecord)(
            uint32_t&, // input
            uint64_t&, // overflow counter
            uint64_t&, // true number of sync pulses
            uint32_t&, // microtime
            int16_t&,   // channel number (16bit more than enough, negative numbers - potential future special cases
            int16_t&   // the event type: photon, or marker (overflows are treated separately and removed during reading)
    );
 
    unsigned long long *macro_times;
 
    unsigned short *micro_times;
 
    signed char *routing_channels;
 
    signed char *event_types;
 
    size_t n_records_in_file = 0;
 
    size_t n_records_read = 0;
 
    size_t n_valid_events = 0;
 
    void allocate_memory_for_records(size_t n_rec);
 
    void deallocate_memory_of_records();
 
    int read_hdf_file(const char *fn);
 
    void read_records(size_t n_rec, bool rewind, size_t chunk);
 
    void read_records(size_t n_rec);
 
    void read_records();
 
protected:
 
    void find_used_routing_channels();
 
    std::vector<signed char> used_routing_channels;
 
 
public:
 
    std::shared_ptr<TTTR> Get() { return shared_from_this(); }
 
    void copy_from(const TTTR &p2, bool include_big_data = true);
 
    int read_file(const char *fn = nullptr, int container_type = -1);
 
    static size_t get_number_of_records_by_file_size(
        std::FILE *fp,
        size_t offset,
        size_t bytes_per_record
    );
 
    void append_events(
        unsigned long long *macro_times, int n_macrotimes,
        unsigned short *micro_times, int n_microtimes,
        signed char *routing_channels, int n_routing_channels,
        signed char *event_types, int n_event_types,
        bool shift_macro_time = true,
        long long macro_time_offset = 0
    );
 
    void append_event(
        unsigned long long macro_time,
        unsigned short micro_time,
        signed char routing_channel,
        signed char event_type,
        bool shift_macro_time = true,
        long long macro_time_offset = 0
    );
 
    void append(
            const TTTR *other,
            bool shift_macro_time=true,
            long long macro_time_offset=0
    );
 
     size_t size() {
      return get_n_valid_events();
     }
 
     void get_used_routing_channels(signed char **output, int *n_output);
 
     void get_macro_times(unsigned long long **output, int *n_output);
 
     void get_micro_times(unsigned short **output, int *n_output);
 
     void get_intensity_trace(int **output, int *n_output, double time_window_length = 1.0);
 
     void get_routing_channel(signed char** output, int* n_output);
 
     void get_event_type(signed char** output, int* n_output);
 
     unsigned int get_number_of_micro_time_channels();
 
     size_t get_n_valid_events();
 
     std::string get_tttr_container_type(){
        return tttr_container_type_str;
    }
 
     std::shared_ptr<TTTR> select(int *selection, int n_selection);
 
    TTTR();
 
    TTTR(const TTTR &p2);
 
    TTTR(const char *filename, int container_type, bool read_input);
 
    TTTR(const char *filename, int container_type);
 
    TTTR(const char *filename, const char* container_type);
 
     TTTR(unsigned long long *macro_times, int n_macrotimes,
          unsigned short *micro_times, int n_microtimes,
          signed char *routing_channels, int n_routing_channels,
          signed char *event_types, int n_event_types,
          bool find_used_channels = true
     );
 
     TTTR(const TTTR &parent,
             int *selection, int n_selection,
             bool find_used_channels = true);
 
    ~TTTR();
 
    std::string get_filename();
 
    std::shared_ptr<TTTR> get_tttr_by_selection(int *selection, int n_selection){
        auto p = std::make_shared<TTTR>(*this, selection, n_selection, true);
        return p;
    }
 
    void get_ranges_by_time_window(
            int **output, int *n_output,
            double minimum_window_length,
            double maximum_window_length=-1,
            int minimum_number_of_photons_in_time_window=-1,
            int maximum_number_of_photons_in_time_window=-1,
            double macro_time_calibration = -1,
            bool invert=false
    ){
        if(macro_time_calibration < 0){
            macro_time_calibration = header->get_macro_time_resolution();
        }
        ranges_by_time_window(
                output, n_output,
                macro_times, n_valid_events,
                minimum_window_length,
                maximum_window_length,
                minimum_number_of_photons_in_time_window,
                maximum_number_of_photons_in_time_window,
                macro_time_calibration,
                invert
        );
    }
 
     void get_selection_by_channel(
             int **output, int *n_output,
             signed char *input, int n_input
     );
 
     std::shared_ptr<TTTR> get_tttr_by_channel(signed char *input, int n_input){
      int* sel; int nsel;
      get_selection_by_channel(&sel, &nsel, input, n_input);
      return get_tttr_by_selection(sel, nsel);
     }
 
     void get_selection_by_count_rate(
             int **output, int *n_output,
             double time_window, int n_ph_max,
             bool invert=false, bool make_mask=false
     );
 
 
     std::shared_ptr<TTTR> get_tttr_by_count_rate(
             double time_window, int n_ph_max,
             bool invert=false, bool make_mask=false
     ){
        int* sel; int nsel;
        get_selection_by_count_rate(
                &sel, &nsel,
                time_window, n_ph_max,
                invert, make_mask);
        return get_tttr_by_selection(sel, nsel);
    }
 
     void get_time_window_ranges(
             int **output, int *n_output,
             double minimum_window_length,
             int minimum_number_of_photons_in_time_window,
             int maximum_number_of_photons_in_time_window=-1,
             double maximum_window_length=-1.0,
             double macro_time_calibration=-1,
             bool invert = false
     );
 
    TTTRHeader* get_header();
 
     void set_header(TTTRHeader* v);
 
     size_t get_n_events();
 
    bool write(std::string filename, TTTRHeader* header = nullptr);
 
    void write_spc132_events(FILE* fp, TTTR* tttr);
 
    void write_hht3v2_events(FILE* fp, TTTR* tttr);
 
     void write_header(std::string &fn, TTTRHeader* header = nullptr);
 
     void shift_macro_time(int shift);
 
    TTTR* operator+(const TTTR* other) const {
        auto re = new TTTR();
        re->copy_from(*this, true);
        re->append(other);
        return re;
    }
 
     static void compute_microtime_histogram(
             TTTR *tttr_data,
             double** output, int* n_output,
             double **time, int *n_time,
             unsigned short micro_time_coarsening = 1,
             std::vector<int> *tttr_indices = nullptr
     );
 
     void get_microtime_histogram(
             double **histogram, int *n_histogram,
             double **time, int *n_time,
             unsigned short micro_time_coarsening = 1
     ){
      compute_microtime_histogram(
              this, histogram, n_histogram,
              time, n_time,
              micro_time_coarsening
      );
     }
 
     static double compute_mean_lifetime(
             TTTR *tttr_data,
             TTTR *tttr_irf = nullptr,
             double m0_irf = 1, double m1_irf = 0,
             std::vector<int> *tttr_indices = nullptr,
             double dt = -1.0,
             int minimum_number_of_photons = 1,
             std::vector<double> *background = nullptr,
             double m0_bg = 0.0, double m1_bg = 0.0,
             double background_fraction = -1.0
     );
 
     double mean_lifetime(
             TTTR *tttr_irf = nullptr,
             int m0_irf = 1, int m1_irf = 1,
             std::vector<int> *tttr_indices = nullptr,
             double dt = -1.0,
             int min_ph = 1
     ){
      return compute_mean_lifetime(
              this,
              tttr_irf, m0_irf, m1_irf,
              tttr_indices, dt, min_ph
      );
     }
 
     static double compute_count_rate(
             TTTR *tttr_data,
             std::vector<int> *tttr_indices = nullptr,
             double macrotime_resolution = -1.0
     );
 
     double get_count_rate(
             std::vector<int> *tttr_indices = nullptr,
             double macrotime_resolution = -1.0
     ){
      return compute_count_rate(this, tttr_indices, macrotime_resolution);
     }
 
     static double compute_mean_microtime(
             TTTR *tttr_data,
             std::vector<int> *tttr_indices = nullptr,
             double microtime_resolution = -1.0,
             int minimum_number_of_photons = 1
     );
 
 
    double get_mean_microtime(
         std::vector<int> *tttr_indices = nullptr,
         double microtime_resolution = -1.0,
         int minimum_number_of_photons = 1
    ){
        return compute_mean_microtime(
                this, tttr_indices,
                microtime_resolution, minimum_number_of_photons);
    }
 
};
 
 
#endif //TTTRLIB_TTTR_H