diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 76a5262f..bbd2ec1b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -43,45 +43,41 @@ jobs: if: startsWith(matrix.os, 'macos') run: tools/install_macos_sdk.sh - - name: Build Conda Package + - name: Build and Upload Conda Package shell: bash -el {0} run: | mamba install conda-build boa anaconda-client cd conda-recipe - # Use older conda_build_config -> boost-cpp 1.78 curl -sLO https://raw.githubusercontent.com/conda-forge/conda-forge-pinning-feedstock/084b098a28a7a66e9a0967d156bc55b9ebfc6726/recipe/conda_build_config.yaml # curl -sLO https://github.com/conda-forge/conda-forge-pinning-feedstock/raw/main/recipe/conda_build_config.yaml - conda mambabuild . --output-folder ../conda-bld - - - name: Upload Conda Package - shell: bash -el {0} - run: | + conda mambabuild . --output-folder conda-bld anaconda -t ${{ secrets.ANACONDA_TOKEN }} upload -u tpeulen --force conda-bld/**/*.tar.bz2 + - build_wheels: - name: Build wheels on ${{ matrix.os }} - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: [ubuntu-latest, windows-latest, macos-13, macos-14] - - steps: - - uses: actions/checkout@v4 - - # Used to host cibuildwheel - - uses: actions/setup-python@v3 - - - name: Install cibuildwheel - run: python -m pip install cibuildwheel==2.16.5 - - - name: Build wheels - run: python -m cibuildwheel --output-dir wheelhouse - # to supply options, put them in 'env', like: - # env: - # CIBW_SOME_OPTION: value - - - uses: actions/upload-artifact@v4 - with: - name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }} - path: ./wheelhouse/*.whl \ No newline at end of file +# build_wheels: +# name: Build wheels on ${{ matrix.os }} +# runs-on: ${{ matrix.os }} +# strategy: +# matrix: +# os: [ubuntu-latest, windows-latest, macos-13, macos-14] +# +# steps: +# - uses: actions/checkout@v4 +# +# # Used to host cibuildwheel +# - uses: actions/setup-python@v3 +# +# - name: Install cibuildwheel +# run: python -m pip install cibuildwheel==2.16.5 +# +# - name: Build wheels +# run: python -m cibuildwheel --output-dir wheelhouse +# # to supply options, put them in 'env', like: +# # env: +# # CIBW_SOME_OPTION: value +# +# - uses: actions/upload-artifact@v4 +# with: +# name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }} +# path: ./wheelhouse/*.whl diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index cb0646bf..751baa85 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -61,9 +61,12 @@ conda:build:windows: <<: *build tags: - win - script: - - conda activate base - - .\tools\build.bat + script: | + conda activate base + copy /Y tools\.condarc %userprofile% + copy /Y tools\conda_build_config.yaml conda_build_config.yaml + mamba install -y boa doxygen cmake + conda mambabuild conda-recipe --output-folder bld-dir conda:test:linux: stage: test diff --git a/README.md b/README.md index a266adef..6c397c6e 100644 --- a/README.md +++ b/README.md @@ -177,4 +177,4 @@ are not supported. Copyright 2007-2024 tttrlib developers. Licensed under the BSD-3-Clause -[3]: https://github.com/fluorescence-tools/tttrlib/doc/logos/mashup.png "tttrlib FLIM" +[3]: https://github.com/Fluorescence-Tools/tttrlib/blob/master/doc/logos/mashup.png?raw=true "tttrlib FLIM" diff --git a/conda-recipe/meta.yaml b/conda-recipe/meta.yaml index 1f2bb0ad..c88c91fd 100755 --- a/conda-recipe/meta.yaml +++ b/conda-recipe/meta.yaml @@ -36,7 +36,7 @@ requirements: - numpy run: - python - - {{ pin_compatible('numpy') }} + - {{ pin_compatible('numpy', max_pin='x.x') }} - boost-cpp - hdf5 - tqdm diff --git a/examples/correlation/plot_confocor3_two_ch_correlation.py b/examples/correlation/plot_confocor3_two_ch_correlation.py index 5265ed3e..cf8402f9 100644 --- a/examples/correlation/plot_confocor3_two_ch_correlation.py +++ b/examples/correlation/plot_confocor3_two_ch_correlation.py @@ -25,7 +25,7 @@ # ------------ # The photon data registered by different detectors are saved in separate files. # Read the data of all channels that should be correlated into separate containers. -fns = [str(p) for p in pathlib.Path('../../tttr-data/cz/fcs').glob('5a6ce6a348a08e3da9f7c0ab4ee0ce94_R1_P1_K1_Ch*.raw')] +fns = [str(p) for p in pathlib.Path('../../tttr-data/cz/fcs').glob('b02f1b794ef4110bcde513983548ee4b_R1_P12_K1_Ch*.raw')] tttr_data = [tttrlib.TTTR(fn, 'CZ-RAW') for fn in fns] #%% diff --git a/include/CLSMFrame.h b/include/CLSMFrame.h index 00277817..baa3962f 100644 --- a/include/CLSMFrame.h +++ b/include/CLSMFrame.h @@ -20,120 +20,67 @@ class CLSMFrame: public TTTRSelection{ public: - /*! - * \brief Get a vector containing pointers to the CLSMLines in the CLSMFrame. - * - * This function returns a vector containing pointers to the CLSMLines stored - * in the CLSMFrame. - * - * @return A vector of CLSMLine pointers. - */ - std::vector get_lines() { + std::vector get_lines(){ return lines; } - - /*! - * \brief Get the number of lines in the CLSMFrame. - * - * @return The number of lines in the CLSMFrame. - */ + /// Get the number of lines in the CLSMFrame size_t size() final{ return lines.size(); } - /*! - * \brief Default constructor for CLSMFrame. - * - * This constructor creates an empty CLSMFrame object. - */ CLSMFrame(); /*! - * \brief Copy constructor for CLSMFrame. + * Copy constructor * - * @param old_frame [in] Reference to the existing CLSMFrame object to be copied. - * @param fill [in] If set to false, the content of the pixels is not copied. + * @param fill if set to false the content of the pixels is not copied */ - CLSMFrame(const CLSMFrame& old_frame, bool fill = true) : TTTRSelection(old_frame) { - for (auto& l : old_frame.lines) { + CLSMFrame(const CLSMFrame& old_frame, bool fill = true) : TTTRSelection(old_frame){ + for(auto l: old_frame.lines){ lines.emplace_back(new CLSMLine(*l, fill)); } } - /*! - * \brief Destructor for CLSMFrame. - * - * Deletes dynamically allocated CLSMLine objects in the lines vector. - */ - virtual ~CLSMFrame() { - for (auto& l : lines) { - delete l; + virtual ~CLSMFrame(){ + for(auto l: lines){ + delete(l); } } - /*! - * \brief Constructor for CLSMFrame with specified frame indices and a TTTR object. - * - * This constructor initializes a CLSMFrame object with the specified frame indices - * (frame_start to frame_stop) using a TTTR (Time-Tagged Time-Resolved) data object. - * - * @param frame_start [in] The starting frame index for the CLSMFrame. - * @param frame_stop [in] The stopping frame index for the CLSMFrame. - * @param tttr [in] Pointer to a TTTR object containing time-resolved data. - */ explicit CLSMFrame(size_t frame_start, size_t frame_stop, TTTR* tttr); /*! - * \brief Append a CLSMLine to the current CLSMFrame. - * - * @param line [in] Pointer to the CLSMLine to be appended. + * Append a line to the current frame + * @param line */ - void append(CLSMLine* line); + void append(CLSMLine * line); /*! - * \brief Retrieve a pointer to the CLSMLine with the specified line number. * - * @param i_line [in] The line number. - * @return A pointer to the CLSMLine with the requested number. + * @param i_line the line number + * @return a pointer to the line with requested number */ - CLSMLine* operator[](unsigned int i_line) { + CLSMLine* operator[](unsigned int i_line){ return lines[i_line]; } - /*! - * \brief Add the corresponding CLSMLines of another CLSMFrame to the current frame. - * - * This operator performs element-wise addition, adding each CLSMLine of the - * right-hand side (rhs) CLSMFrame to the corresponding CLSMLine of the current frame. - * - * @param rhs [in] The right-hand side CLSMFrame to be added. - * @return A reference to the modified current CLSMFrame. - */ - CLSMFrame& operator+=(const CLSMFrame& rhs) { - for (std::size_t i = 0; i < lines.size(); ++i) { - *lines[i] += *rhs.lines[i]; + CLSMFrame& operator+=(const CLSMFrame& rhs){ + int i = 0; + for(auto l: lines){ + *l += *rhs.lines[i]; } return *this; } /*! - * \brief Crop the CLSMFrame by selecting a region of lines and pixels. - * - * This function crops the CLSMFrame by selecting a specific range of lines - * (from line_start to line_stop) and pixels (from pixel_start to pixel_stop). - * - * @param line_start [in] The starting line index for cropping. - * @param line_stop [in] The stopping line index for cropping. - * @param pixel_start [in] The starting pixel index for cropping. - * @param pixel_stop [in] The stopping pixel index for cropping. + * Crops a frame */ void crop( - int line_start, int line_stop, - int pixel_start, int pixel_stop + int line_start, int line_stop, + int pixel_start, int pixel_stop ); - }; diff --git a/include/CLSMImage.h b/include/CLSMImage.h index 8bf2e407..cec87329 100644 --- a/include/CLSMImage.h +++ b/include/CLSMImage.h @@ -12,12 +12,12 @@ #include "pocketfft/pocketfft_hdronly.h" #include "TTTR.h" /* TTTR */ +#include "Correlator.h" +#include "DecayPhasor.h" #include "CLSMFrame.h" #include "CLSMLine.h" #include "CLSMPixel.h" -#include "DecayPhasor.h" -#include "Correlator.h" /// Different types of distances between two accessible volumes @@ -109,39 +109,40 @@ class CLSMSettings{ public: /*! - * \brief CLSMSettings Constructor. - * - * Constructs a CLSMSettings object with the specified parameters. - * - * @param skip_before_first_frame_marker If true, skip TTTR events before the first frame marker (default is false). - * @param skip_after_last_frame_marker If true, skip TTTR events after the last frame marker (default is false). - * @param reading_routine An integer specifying the reading routine used to - * read a CLSM image out of a TTTR data stream. A CLSM image can be encoded - * in various ways in a TTTR stream. - * @param marker_line_start Routing channel number or micro time channel number serving as a marker - * for the start of a new line in a frame within the TTTR data stream. - * @param marker_line_stop Routing channel number or micro time channel number serving as a marker - * for the stop of a line in a frame within the TTTR data stream. - * @param marker_frame_start Routing channel numbers (default reading routine) - * or micro time channel number (SP8 reading routine) serving as a marker - * for a new frame in the TTTR data stream. - * @param marker_event_type Event types interpreted as markers for frames and lines. - * @param n_pixel_per_line Number of pixels into which each line is separated. - * If set to zero, the number of pixels per line corresponds to the number - * of lines in the first frame. - * @param n_lines Number of lines (default is -1, auto-detect based on the first frame). - */ - explicit CLSMSettings( - bool skip_before_first_frame_marker = false, - bool skip_after_last_frame_marker = false, - int reading_routine = CLSM_DEFAULT, - int marker_line_start = 3, - int marker_line_stop = 2, - std::vector marker_frame_start = std::vector({1}), - int marker_event_type = 1, - int n_pixel_per_line = 1, - int n_lines = -1 - // long long macro_time_shift = 0 + * @param marker_frame_start routing channel numbers (default reading routine) + * or micro time channel number (SP8 reading routine) that serves as a marker + * informing on a new frame in the TTTR data stream. + * @param marker_line_start routing channel number (default reading routine) + * or micro time channel number (SP8 reading routine) that serves as a marker + * informing on the start of a new line in a frame within the TTTR data stream + * @param marker_line_stop routing channel number (default reading routine) + * or micro time channel number (SP8 reading routine) that serves as a marker + * informing on the stop of a new line in a frame within the TTTR data stream + * @param marker_event event types that are interpreted as markers for + * frames and lines. + * @param n_pixel_per_line number of pixels into which each line is separated. + * If the number of pixels per line is set to zero. The number of pixels per + * line will correspond to the number of lines in the first frame. + * @param macro_time_shift Number of macro time counts a line start is shifted + * relative to the line start marker in the TTTR object (default 0) + * @param reading_routine an integer that specifies the reading routine used to + * read a CLSM image out of a TTTR data stream. A CLSM image can be encoded + * by several ways in a TTTR stream. Leica encodes frame and line markers in + * micro time channel numbers. PicoQuant and others use a more 'traditional' + * encoding for frame and line markers marking TTTR events as marker events and + * using the channel number to differentiate the different marker types. + */ + CLSMSettings( + bool skip_before_first_frame_marker = false, + bool skip_after_last_frame_marker = false, + int reading_routine = CLSM_DEFAULT, + int marker_line_start = 3, + int marker_line_stop = 2, + std::vector marker_frame_start = std::vector({1}), + int marker_event_type = 1, + int n_pixel_per_line = 1, + int n_lines = -1 +// long long macro_time_shift = 0 ){ this->skip_before_first_frame_marker = skip_before_first_frame_marker; this->skip_after_last_frame_marker = skip_after_last_frame_marker; @@ -237,22 +238,14 @@ class CLSMImage { bool skip_after_last_frame_marker = false; /*! - * \brief Fills the time-tagged time-resolved (TTTR) indices of the pixels with the - * indices of the photons that fall within each pixel. + * Fill the tttr_indices of the pixels with the indices of the channels + * that are within a pixel * - * This function processes the TTTR data to associate routing channels with pixels based - * on specified criteria. The TTTR indices of the channels within each pixel are stored. - * - * @param tttr_data Pointer to the TTTR object containing the data to be - * processed (default is nullptr). - * @param channels List of routing channels. Events that have routing - * channels in this vector are added to pixels of corresponding - * time. - * @param clear If set to true (default), the pixels are cleared before - * being filled. If set to false, new TTTR indices are added - * to the pixels. - * @param micro_time_ranges List of pairs representing micro-time ranges. If provided, - * only events within these ranges are considered. + * @param channels[in] list of routing channels. Events that have routing + * channels in this vector are added to pixels of corresponding time. + * @param clear_pixel[in] if set to true (default) the pixels are cleared + * before they are filled. If set to false new tttr indices are added to + * the pixels */ void fill( TTTR *tttr_data = nullptr, @@ -260,27 +253,6 @@ class CLSMImage { bool clear = true, const std::vector> µ_time_ranges = std::vector>() ); - - /*! - * \deprecated Use the 'fill' function instead. - * \brief Fills the time-tagged time-resolved (TTTR) indices of the pixels with the - * indices of the channels that fall within each pixel. - * - * This function is deprecated in favor of 'fill'. It processes the TTTR data to - * associate routing channels with pixels based on specified criteria. The TTTR indices - * of the channels within each pixel are stored. - * - * @param tttr_data Pointer to the TTTR object containing the data to be - * processed. - * @param channels List of routing channels. Events that have routing - * channels in this vector are added to pixels of corresponding - * time. - * @param clear_pixel If set to true (default), the pixels are cleared before - * being filled. If set to false, new TTTR indices are added - * to the pixels. - * @param micro_time_ranges List of pairs representing micro-time ranges. If provided, - * only events within these ranges are considered. - */ void fill_pixels( TTTR *tttr_data, std::vector channels, @@ -292,258 +264,176 @@ class CLSMImage { } /*! - * \brief Clears the time-tagged time-resolved (TTTR) indices stored in the pixels. + * Clear tttr_indices stored in the pixels */ void clear(); - - /*! - * \deprecated Use the 'clear' function instead. - * \brief Clears the time-tagged time-resolved (TTTR) indices stored in the pixels. - * - * This function is deprecated in favor of 'clear'. It removes the stored TTTR indices - * from the pixels. - */ void clear_pixels(){ std::clog << "WARNING: 'clear_pixels' deprecated. Use 'clear'." << std::endl; clear(); } /*! - * \brief Strips time-tagged time-resolved (TTTR) indices from all pixels in the image. - * - * This function removes specified TTTR indices from all pixels in the image. It assumes - * that each TTTR index is present only once in the image. - * - * @param tttr_indices List of TTTR indices to be removed from the pixels. - * @param offset Offset value added to the TTTR indices before removal - * (default is 0). + * Strips tttr_indices from all pixels in Image + * assumes that each tttr index is only once in an image */ void strip(const std::vector &tttr_indices, int offset = 0); /*! - * \brief Computes an image where pixels represent correlation curves. + * Computes the an image where pixels are correlation curves * - * This function calculates a correlation image where each pixel corresponds to a - * correlation curve. The resulting image is determined by the specified parameters - * and is stored in the provided output array. - * - * @param output Pointer to the array that will contain the correlation - * image. The array is allocated by the function. - * @param dim1 Number of correlation curves in the image (frames or - * time bins). - * @param dim2 Number of lines per frame in the correlation image. - * @param dim3 Number of pixels per line in the correlation image. - * @param dim4 Number of cascades in the correlation image. - * @param tttr Shared pointer to the TTTR object containing the data. - * @param clsm_other Pointer to another CLSMImage object (default is nullptr). - * @param correlation_method Method used for correlation computation (default is - * "default"). - * @param n_bins Number of bins used for correlation computation - * (default is 50). - * @param n_casc Number of cascades in the correlation image - * (default is 1). - * @param stack_frames If true, correlation curves are stacked into a single - * image (default is false). - * @param normalized_correlation If true, correlation curves are normalized - * (default is false). - * @param min_photons Minimum number of photons required for correlation - * computation (default is 2). + * @param output[out] + * @param dim1[out] + * @param dim2[out] + * @param dim3[out] + * @param dim4[out] + * @param tttr_self + * @param tac_coarsening + * @param stack_frames */ void get_fcs_image( - float **output, int *dim1, int *dim2, int *dim3, int *dim4, - std::shared_ptr tttr, - CLSMImage *clsm_other = nullptr, - std::string correlation_method = "default", - int n_bins = 50, - int n_casc = 1, - bool stack_frames = false, - bool normalized_correlation = false, - int min_photons = 2 + float **output, int *dim1, int *dim2, int *dim3, int *dim4, + std::shared_ptr tttr, + CLSMImage *clsm_other, + std::string correlation_method = "default", + int n_bins = 50, + int n_casc = 1, + bool stack_frames = false, + bool normalized_correlation = false, + int min_photons = 2 ); - /*! - * \brief Retrieves the frames stored in the CLSMImage. - * - * @return Vector of CLSMFrame pointers representing the frames in the CLSMImage. - */ + /// Get the frames in the CLSMImage std::vector get_frames() { return frames; } - /*! - * \brief Computes an intensity image. - * - * This function calculates an intensity image and stores it in the provided output - * array. The dimensions of the intensity image are returned in the output parameters. - * - * @param output Pointer to the array that will contain the intensity image. The array - * is allocated by the function. - * @param dim1 Number of frames in the intensity image. - * @param dim2 Number of lines per frame in the intensity image. - * @param dim3 Number of pixels per line in the intensity image. - */ + /// Intensity image void get_intensity(unsigned short **output, int *dim1, int *dim2, int *dim3); /*! - * \brief Computes an image stack where the value of each pixel corresponds to a histogram - * of micro times in each pixel. The micro times can be coarsened by integer - * numbers. - * - * This function calculates an image stack where each pixel represents a histogram of - * micro times. The resulting image stack is stored in the provided output array, and - * the dimensions of the image stack are returned in the output parameters. + * Computes an image stack where the value of each pixel corresponds to + * a histogram of micro times in each pixel. The micro times can be coarsened + * by integer numbers. * - * @param tttr_data Pointer to a TTTR object. - * @param output Pointer to the output array of unsigned chars that will - * contain the image stack. The array is allocated by the - * function. - * @param dim1 Number of frames in the image stack. - * @param dim2 Number of lines per frame in the image stack. - * @param dim3 Number of pixels per line in the image stack. - * @param dim4 Number of micro time channels in the histogram. - * @param micro_time_coarsening Constant used to coarsen the micro times. The default - * value is 1, and the micro times are binned without - * coarsening. - * @param stack_frames If true, the frames are stacked. + * @param tttr_data pointer to a TTTR object + * @param out pointer to output array of unsigned chars that will contain + * the image stack + * @param dim1 number of frames + * @param dim2 number of lines + * @param dim3 number of pixels + * @param dim4 number of micro time channels in the histogram + * @param micro_time_coarsening constant used to coarsen the micro times. The default + * value is 1 and the micro times are binned without coarsening. + * @param stack_frames if True the frames are stacked. */ void get_fluorescence_decay( - TTTR *tttr_data, - unsigned char **output, int *dim1, int *dim2, int *dim3, int *dim4, - int micro_time_coarsening = 1, - bool stack_frames = false + TTTR *tttr_data, + unsigned char **output, int *dim1, int *dim2, int *dim3, int *dim4, + int micro_time_coarsening = 1, + bool stack_frames = false ); - /*! - * \brief Computes micro time histograms for the stacks of images and a selection of - * pixels. Photons in pixels that are selected by the selection array contribute - * to the returned array of micro time histograms. + * Computes micro time histograms for the stacks of images and a selection + * of pixels. Photons in pixels that are selected by the selection array + * contribute to the returned array of micro time histograms. * - * This function calculates micro time histograms for selected pixels in the image stack, - * based on a provided mask. The resulting micro time histograms are stored in the - * provided output array, and the dimensions of the output array are returned in the - * output parameters. - * - * @param tttr_data Pointer to a TTTR object. - * @param mask A stack of images used as a mask to select pixels. - * @param dmask1 Number of frames in the mask. - * @param dmask2 Number of lines in the mask. - * @param dmask3 Number of pixels per line in the mask. - * @param output Pointer to the output array of unsigned int that contains the - * micro time histograms. The array is allocated by the function. - * @param dim1 Dimension of the output array, i.e., the number of stacks. - * @param dim2 Dimension of the output array, i.e., the number of micro time - * channels. - * @param tac_coarsening Constant used to coarsen the micro times. - * @param stack_frames If true, the frames are stacked. + * @param tttr_data pointer to a TTTR object + * @param mask a stack of images used as a mask to select pixels + * @param dmask1 number of frames + * @param dmask2 number of lines + * @param dmask3 number of pixels per line + * @param out pointer to output array of unsigned int contains the micro time histograms + * @param dim1 dimension of the output array, i.e., the number of stacks + * @param dim1 dimension the number of micro time channels + * @param tac_coarsening constant used to coarsen the micro times + * @param stack_frames if True the frames are stacked. */ void get_decay_of_pixels( - TTTR *tttr_data, - uint8_t* mask, int dmask1, int dmask2, int dmask3, - unsigned int **output, int *dim1, int *dim2, - int tac_coarsening, - bool stack_frames + TTTR *tttr_data, + uint8_t* mask, int dmask1, int dmask2, int dmask3, + unsigned int **output, int *dim1, int *dim2, + int tac_coarsening, + bool stack_frames ); - /*! - * \brief Calculates an image stack where the value of each pixel corresponds to the - * mean micro time (in units of the micro channel resolution). + * Calculates an image stack where the value of each pixel corresponds + * to the mean micro time (in units of the micro channel resolution). * - * Pixels with few photons can be discriminated. Discriminated pixels will be filled - * with zeros. + * Pixels with few photons can be discriminated. Discriminated pixels will + * be filled with zeros. * - * @param tttr_data Pointer to a TTTR object. - * @param output Pointer to the output array that will contain the - * image stack. The array is allocated by the function. - * @param dim1 Returns the number of frames. - * @param dim2 Returns the number of lines. - * @param dim3 Returns the number of pixels per line. - * @param microtime_resolution Micro channel resolution (default is -1.0, which - * means it will be obtained from the TTTR object). - * @param minimum_number_of_photons The minimum number of photons in a micro time - * (default is 2). - * @param stack_frames If true, the frames are stacked (default is false). - * If stack frames is set to true, the mean arrival time - * is computed using the TTTR indices of all pixels - * (corresponding to the photon-weighted mean arrival time). + * @param tttr_data[in] pointer to a TTTR object + * @param out[out] pointer to output array that will contain the image stack + * @param dim1[out] returns the number of frames + * @param dim2[out] returns the number of lines + * @param dim3[out] returns the number of pixels per line + * @param minimum_number_of_photons[in] the minimum number of photons in a micro time + * @param stack_frames[in] if true the frames are stacked (default value is + * false). If stack frames is set to true the mean arrival time is computed + * using the tttr indices of all pixels (this corresponds to the photon weighted + * mean arrival time). */ void get_mean_micro_time( - TTTR *tttr_data, - double **output, int *dim1, int *dim2, int *dim3, - double microtime_resolution = -1.0, - int minimum_number_of_photons = 2, - bool stack_frames = false + TTTR *tttr_data, + double **output, int *dim1, int *dim2, int *dim3, + double microtime_resolution = -1.0, + int minimum_number_of_photons = 2, + bool stack_frames = false ); - /*! - * \brief Computes the phasor values for every pixel. + * Computes the phasor values for every pixel * - * Pixels with few photons can be discriminated. Discriminated pixels will be filled - * with zeros. + * Pixels with few photons can be discriminated. Discriminated pixels will + * be filled with zeros. * - * @param output Pointer to the output array that will contain the - * image stack. The array is allocated by the function. - * @param dim1 Returns the number of frames. - * @param dim2 Returns the number of lines. - * @param dim3 Returns the number of pixels per line. - * @param dim4 Returns 2 (first is the g phasor value (cos), - * second the s phasor (sin)). - * @param tttr_data Pointer to a TTTR object. - * @param tttr_irf Pointer to a TTTR object representing the Instrument - * Response Function (IRF) (default is nullptr). - * @param frequency Modulation frequency for phasor computation - * (default is -1, which means it will be obtained from - * the TTTR object). - * @param minimum_number_of_photons The minimum number of photons in a micro time - * (only used if frames are not stacked, default is 2). - * @param stack_frames If true, the frames are stacked (default is false). - * If stack frames is set to true, the mean arrival time - * is computed using the TTTR indices of all pixels - * (corresponding to the photon-weighted mean arrival time). + * @param tttr_data[in] pointer to a TTTR object + * @param output[out] pointer to output array that will contain the image stack + * @param dim1[out] returns the number of frames + * @param dim2[out] returns the number of lines + * @param dim3[out] returns the number of pixels per line + * @param dim4[out] returns 2 (first is the g phasor value (cos), second the + * s phasor (sin) + * @param minimum_number_of_photons[in] the minimum number of photons in a micro time + * (only used if frames are not stacked) + * @param stack_frames[in] if true the frames are stacked (default value is + * false). If stack frames is set to true the mean arrival time is computed + * using the tttr indices of all pixels (this corresponds to the photon weighted + * mean arrival time). */ void get_phasor( - float **output, int *dim1, int *dim2, int *dim3, int *dim4, - TTTR *tttr_data, - TTTR *tttr_irf = nullptr, - double frequency = -1, - int minimum_number_of_photons = 2, - bool stack_frames = false + float **output, int *dim1, int *dim2, int *dim3, int *dim4, + TTTR *tttr_data, + TTTR *tttr_irf = nullptr, + double frequency = -1, + int minimum_number_of_photons = 2, + bool stack_frames = false ); - /*! - * \brief Computes an image of average lifetimes. + * Computes an image of average lifetimes * - * The average lifetimes are computed (not fitted) by the methods of moments - * (Irvin Isenberg, 1973, Biophysical journal). + * The average lifetimes are computed (not fitted) by the methods of + * moments (Irvin Isenberg, 1973, Biophysical journal). This approach + * does not consider scattered light. * - * Pixels with few photons can be discriminated. Discriminated pixels are filled - * with zeros. + * Pixels with few photons can be discriminated. Discriminated pixels are + * filled with zeros. * - * By default, the fluorescence lifetimes of the pixels are computed in units of - * nanoseconds. + * By default the fluorescence lifetimes of the pixels are computed in + * units of nanoseconds. * - * @param tttr_data Pointer to a TTTR object. - * @param output Pointer to the output array that will contain the - * image stack. The array is allocated by the function. - * @param dim1 Returns the number of frames. - * @param dim2 Returns the number of lines. - * @param dim3 Returns the number of pixels per line. - * @param minimum_number_of_photons The minimum number of photons in a micro time - * (default is 3). - * @param tttr_irf Pointer to a TTTR object of the Instrument Response - * Function (IRF) (default is nullptr). - * @param m0_irf The zero moment of the IRF (optional, default is 1.0). - * @param m1_irf The first moment of the IRF (optional, default is 1.0). - * @param stack_frames If true, the frames are stacked (default is false). - * @param background Vector of background values (optional, default is an - * empty vector). - * @param m0_bg The zero moment of the background (optional, default is 0.0). - * @param m1_bg The first moment of the background (optional, default is 0.0). - * @param background_fraction Background fraction used for discrimination - * (default is -1.0, which disables discrimination). + * @param tttr_data[in] pointer to a TTTR object + * @param tttr_irf[in] pointer to a TTTR object of the IRF + * @param out[out] pointer to output array that will contain the image stack + * @param dim1[out] returns the number of frames + * @param dim2[out] returns the number of lines + * @param dim3[out] returns the number of pixels per line + * @param minimum_number_of_photons[in] the minimum number of photons in a micro time + * @param m0_irf is the zero moment of the IRF (optional, default=1) + * @param m1_irf is the first moment of the IRF (optional, default=1) */ void get_mean_lifetime( TTTR *tttr_data, @@ -556,56 +446,26 @@ class CLSMImage { double background_fraction = -1.0 ); - /*! - * \brief Convert three-dimensional coordinates (frame, line, pixel) to a one-dimensional index. - * - * This inline function calculates a unique one-dimensional index for a given set of - * three-dimensional coordinates representing a position in an array. - * - * @param frame Index of the frame. - * @param line Index of the line within the frame. - * @param pixel Index of the pixel within the line. - * @return One-dimensional index corresponding to the input coordinates. - */ + /// Convert frame, line, and pixel to 1D index inline int to1D(int frame, int line, int pixel) { - return (frame * n_lines * n_pixel) + (line * n_pixel) + pixel; + return (frame * n_lines * n_pixel) + (line * n_lines) + pixel; } - - /*! - * \brief Convert a one-dimensional index to three-dimensional coordinates (frame, line, pixel). - * - * This inline function calculates the three-dimensional coordinates (frame, line, pixel) - * corresponding to a given one-dimensional index in an array. - * - * @param idx One-dimensional index to be converted. - * @return Vector containing frame, line, and pixel indices in that order. - */ + /// Convert 1D index to frame, line, and pixel inline std::vector to3D(int idx) { int frame = idx / (n_lines * n_pixel); idx -= (frame * n_lines * n_pixel); - int line = idx / n_pixel; + int line = idx / n_lines; int pixel = idx % n_pixel; return std::vector{frame, line, pixel}; } - - /*! - * \brief Get a pointer to a CLSMPixel object based on a one-dimensional index. - * - * This member function calculates the three-dimensional coordinates (frame, line, pixel) - * corresponding to a given one-dimensional index and returns a pointer to the - * corresponding CLSMPixel object. - * - * @param idx One-dimensional index to determine the CLSMPixel. - * @return Pointer to the CLSMPixel object. - */ - CLSMPixel* getPixel(unsigned int idx) { + CLSMPixel* getPixel(unsigned int idx){ int frame, line, pixel; frame = idx / (n_lines * n_pixel); idx -= (frame * n_lines * n_pixel); - line = idx / n_pixel; + line = idx / n_lines; pixel = idx % n_pixel; CLSMFrame* s_frame = frames[frame]; @@ -614,165 +474,133 @@ class CLSMImage { return s_pixel; } - - /*! - * \brief Get the number of frames in the CLSM image. - * - * This member function returns the number of frames in the CLSM image. - * - * @return The number of frames in the CLSM image. - */ + /// Get the number of frames in the CLSM image int get_n_frames() const { return n_frames; } - - /*! - * \brief Get the number of lines per frame in the CLSMImage. - * - * This member function returns the number of lines per frame in the CLSMImage. - * - * @return The number of lines per frame in the CLSMImage. - */ + /// Get the number of lines per frame in the CLSMImage int get_n_lines() const { return n_lines; } - - /*! - * \brief Get the number of pixels per line in a frame of the CLSMImage. - * - * This member function returns the number of pixels per line in a frame of the CLSMImage. - * - * @return The number of pixels per line in a frame of the CLSMImage. - */ + /// Get the number of pixels per line a frame of the CLSMImage int get_n_pixel() const { return n_pixel; } /*! - * \brief Copy information from another CLSMImage object. - * - * Copies the information from another CLSMImage object, including pixel indices, - * if the `fill` parameter is set to true (default is false). + * Copy the information from another CLSMImage object * - * @param p2 The CLSMImage object from which information is copied. - * @param fill If set to true (default is false), the time-tagged time-resolved - * indices of the pixels are copied. + * @param p2 The information from this object is copied. + * @param fill If this is set to true (default is false) the tttr indices + * of the pixels are copied. + * @return */ void copy(const CLSMImage &p2, bool fill = false); /*! - * \brief Append a CLSMFrame to the CLSM image. + * Append a frame to the CLSM image. * - * Appends a CLSMFrame to the CLSM image. - * - * @param frame The CLSMFrame to be appended. + * @param frame */ void append(CLSMFrame *frame); /*! - * \brief Move the content of the Pixels based on source and target pixel indices. + * Moves the content of the Pixels * - * The input is an interleaved array of source and target pixel indices. - * A pixel index is a mapping from frames, lines, and pixel combination to an index. + * The input is an interleaved array or source and target + * pixel indices. A pixel index is a mapping from a frames, + * lines, and pixel combination to an index. * - * @param input [in] Pointer to an interleaved array containing source and target pixel indices. - * @param n_input [in] Number of elements in the input array. + * @param index + * @param n_index */ void transform(unsigned int* input, int n_input); /*! - * \brief Rebin a CLSMImage. - * - * Rebinning redistributes photons and macro times in pixels. + * Rebin a CLSMImage * - * Note: Rebinning may alter the distribution of photons and macro times in the image. + * Note, rebinning redistributes photons and thus + * the macro times in pixels. * - * @param bin_line [in] Binning factor for lines. - * @param bin_pixel [in] Binning factor for pixels within lines. + * @param bin_line binning factor for lines + * @param bin_pixel binning factor for pixel in lines */ void rebin(int bin_line, int bin_pixel); /*! - * \brief Distribute the photons of a pixel_id to a set of pixel ids in a target image according to provided probabilities. + * Distribute the photons of a pixel_id to a set of + * pixel ids in a target image according to provided probabilities * - * This function distributes the photons of a specified pixel_id to a set of pixel_ids - * in a target CLSMImage based on the provided probabilities. - * - * @param pixel_id [in] The source pixel_id whose photons will be distributed. - * @param target [in] Pointer to the target CLSMImage. - * @param target_pixel_ids [in] Vector of target pixel_ids to which photons will be distributed. - * @param target_probabilities [in] Vector of probabilities corresponding to each target pixel_id. */ void distribute( - unsigned int pixel_id, - CLSMImage* target, - std::vector& target_pixel_ids, - std::vector& target_probabilities + unsigned int pixel_id, + CLSMImage* target, + std::vector &target_pixel_ids, + std::vector &target_probabilities ); - /*! - * \brief Crop the CLSMImage. - * - * Crop the image by specifying the range of frames, lines, and pixels to keep. - * - * @param frame_start [in] Starting frame index for cropping. - * @param frame_stop [in] Stopping frame index for cropping. - * @param line_start [in] Starting line index for cropping. - * @param line_stop [in] Stopping line index for cropping. - * @param pixel_start [in] Starting pixel index for cropping. - * @param pixel_stop [in] Stopping pixel index for cropping. + * Crop the image + * @param frame_start + * @param frame_stop + * @param line_start + * @param line_stop + * @param pixel_start + * @param pixel_stop */ void crop( - int frame_start, int frame_stop, - int line_start, int line_stop, - int pixel_start, int pixel_stop + int frame_start, int frame_stop, + int line_start, int line_stop, + int pixel_start, int pixel_stop ); - /*! - * \brief Stack frames in the CLSMImage. - * - * This function stacks the frames in the CLSMImage by summing the pixel values - * of each corresponding pixel in all frames. - */ - void stack_frames() { + void stack_frames(){ CLSMFrame* f0 = frames[0]; - for (unsigned int i = 1; i < n_frames; i++) { + for(unsigned int i = 1; i < n_frames; i++){ *f0 += *frames[i]; } frames.resize(1); n_frames = 1; } - - /*! - * \brief Copy constructor for CLSMImage. - * - * Constructs a new CLSMImage by copying the content of another CLSMImage. - * - * @param p2 [in] The CLSMImage object from which the content is copied. - * @param fill [in] If set to true (default is false), the time-tagged time-resolved - * indices of the pixels are copied. - */ + /// Copy constructor CLSMImage(const CLSMImage &p2, bool fill = false); /*! - * \brief Constructs a CLSMImage object from TTTR data. * - * Constructs a CLSMImage object from Time-Tagged Time-Resolved (TTTR) data, using - * specified markers, settings, and optional source CLSMImage. - * - * @param tttr_data [in] Pointer to TTTR object containing the raw data. - * @param settings [in] CLSMSettings object specifying parameters for image construction. - * @param source [in] A CLSMImage object used as a template. All frames and lines are copied, - * and empty pixels are created. If fill is set to true (default), the content of the pixels is copied. - * @param fill [in] If set to true (default), the lines are filled with pixels containing either - * the photons of the specified channels or the photons from the source CLSMImage instance. - * @param channels [in] The channel number of the events used to fill the pixels. - * @param micro_time_ranges [in] Vector of pairs specifying the micro time ranges. - * @see CLSMSettings for more details on available settings. + * @param tttr_data pointer to TTTR object + * @param marker_frame_start routing channel numbers (default reading routine) + * or micro time channel number (SP8 reading routine) that serves as a marker + * informing on a new frame in the TTTR data stream. + * @param marker_line_start routing channel number (default reading routine) + * or micro time channel number (SP8 reading routine) that serves as a marker + * informing on the start of a new line in a frame within the TTTR data stream + * @param marker_line_stop routing channel number (default reading routine) + * or micro time channel number (SP8 reading routine) that serves as a marker + * informing on the stop of a new line in a frame within the TTTR data stream + * @param marker_event_type event types that are interpreted as markers for + * frames and lines. + * @param n_pixel_per_line number of pixels into which each line is separated. + * If the number of pixels per line is set to zero. The number of pixels per + * line will correspond to the number of lines in the first frame. + * @param reading_routine an integer that specifies the reading routine used to + * read a CLSM image out of a TTTR data stream. A CLSM image can be encoded + * by several ways in a TTTR stream. Leica encodes frame and line markers in + * micro time channel numbers. PicoQuant and others use a more 'traditional' + * encoding for frame and line markers marking TTTR events as marker events and + * using the channel number to differentiate the different marker types. + * @param source A CLSMImage object that is used as a template for the created + * object. All frames and lines are copied and empty pixels are created. If + * the parameter fill is set to true moreover the content of the pixels is copied. + * @param fill if set to true (default) is false the lines are filled with pixels + * that will contain either the photons of the specified channels or the photons + * from the source CLSMImage instance. + * @param channels The channel number of the events that will be used to fill + * the pixels. + * @param stack_frames If set to true (default is false) the frames in the CLSM + * image are stacked and the resulting CLSMImage will hava a single frame. */ explicit CLSMImage( std::shared_ptr tttr_data = nullptr, @@ -780,116 +608,114 @@ class CLSMImage { CLSMImage *source = nullptr, bool fill = true, std::vector channels = std::vector(), - std::vector> micro_time_ranges = - std::vector>() + std::vector> micro_time_ranges = + std::vector>() ); - /*! - * \brief Destructor for CLSMImage. - * - * Frees memory by deleting dynamically allocated CLSMFrame objects in the frames vector. - * It ensures proper cleanup of resources when a CLSMImage object is destroyed. - */ + /// Destructor virtual ~CLSMImage() { for (auto frame : frames) { delete frame; } } - - /*! - * \brief Accessor for CLSMFrame at the specified index in CLSMImage. - * - * Returns a pointer to the CLSMFrame located at the given index in the frames vector. - * - * @param i_frame [in] Index of the desired CLSMFrame. - * @return Pointer to the CLSMFrame at the specified index. - */ - CLSMFrame* operator[](unsigned int i_frame) { + CLSMFrame *operator[](unsigned int i_frame) { return frames[i_frame]; - } - - - /*! - * \brief Performs an image correlation spectroscopy analysis via FFTs for a set of frames. - * - * This function computes the image correlation for a set of frames, either specified - * by an array or a CLSMImage object. It can compute image cross-correlation and image - * auto-correlations based on the type of correlation specified by a vector of pairs. - * - * @param output [out] Array that will contain the Image Correlation Spectrscopy analysis (ICS). - * @param dim1 [out] Number of frames in the ICS. - * @param dim2 [out] Number of lines (line shifts) in the ICS. - * @param dim3 [out] Number of pixels (pixel shifts) in the ICS. - * @param tttr_data [in] Pointer to TTTR object containing the raw data (optional). - * @param clsm [in] Optional pointer to a CLSMImage object. - * @param images [in] Optional pointer to an image array. - * @param input_frames [in] Number of frames in the image array. - * @param input_lines [in] Number of lines in the image array. - * @param input_pixel [in] Number of pixels per line in the image array. - * @param x_range [in] Defines the region of interest (ROI) in the image (pixel). - * @param y_range [in] Defines the ROI in y-direction (lines). - * @param frames_index_pairs [in] Vector of integer pairs corresponding to frame numbers - * used for cross-correlation (default computes auto-correlation). - * @param subtract_average [in] Specifies background correction: "stack" subtracts the average over all frames, - * "frame" subtracts the average of each frame. Default is no correction. - * @param mask [in] Stack of images used as a mask to select pixels (optional). - * @param dmask1 [in] Number of frames in the mask. - * @param dmask2 [in] Number of lines in the mask. - * @param dmask3 [in] Number of pixels per line in the mask. + }; + + /*! + * Computes an image correlation via FFTs for a set of frames + * + * This function computes the image correlation for a set of frames. The + * frames can be either specified by an array or by a CLSMImage object. This + * function can compute image cross-correlation and image auto-correlations. + * The type of the correlation is specified by a set of pairs that are cross- + * correlated. + * + * @param output the array that will contain the ICS + * @param dim1 number of frames in the ICS + * @param dim2 number of lines (line shifts) in the ICS + * @param dim3 number of pixel (pixel shifts) in the ICS + * @param tttr_data + * @param clsm an optional pointer to a CLSMImage object + * @param images an optional pointer to an image array + * @param input_frames number of frames in the image array + * @param input_lines number of lines in the image array + * @param input_pixel number of pixel in the image array + * @param x_range defines the region of interest (ROI) in the image (pixel). + * This parameter is optional. The default value is [0,-1]. This means that + * the entire input pixel range is used + * @param y_range region defines the ROI in y-direction (lines). The default + * value is [0,-1]. By default all lines in the image are used. + * @param frames_index_pairs A vector of integer pairs. The pairs correspond + * to the frame numbers in the input that will be cross-correlated. If no + * vector of frame pairs is specified the image auto-correlation will be + * computed + * @param subtract_average the input image can be corrected for the background, + * i.e., a constant background can be subtracted from the frames. If this + * parameter is set to "stack" the average over all frames is computed and + * subtracted pixel-wise from each frame. If this parameter is set to "frame" + * the average of each frame is computed and subtracted from the each frame. + * By default no correction is applied. + * @param mask a stack of images used as a to select pixels + * @param dmask1 number of frames + * @param dmask2 number of lines + * @param dmask3 number of pixels per line */ static void compute_ics( double **output, int *dim1, int *dim2, int *dim3, std::shared_ptr tttr_data = nullptr, CLSMImage* clsm = nullptr, - double *images = nullptr, int input_frames = -1, int input_lines = -1, int input_pixel = 1, - std::vector x_range = std::vector({0, -1}), - std::vector y_range = std::vector({0, -1}), - std::vector> frames_index_pairs = std::vector>(), - std::string subtract_average = "", - uint8_t *mask = nullptr, int dmask1 = -1, int dmask2 = -1, int dmask3 = -1 + double *images = nullptr, int input_frames=-1, int input_lines=-1, int input_pixel=1, + std::vector x_range=std::vector({0,-1}), + std::vector y_range=std::vector({0,-1}), + std::vector> frames_index_pairs=std::vector>(), + std::string subtract_average="", + uint8_t *mask=nullptr, int dmask1=-1, int dmask2=-1, int dmask3=-1 ); - /*! - * \brief Copies a region of interest (ROI) from the input images, performs background - * correction, and stores the result in a new array. - * - * The ROI is defined by specifying ranges for pixels and lines. The function supports - * various correction options, such as subtracting a constant background value, - * clipping output values, and correcting by the mean intensity of frames. - * - * @param output Pointer to the array that will contain the ROI. The array is - * allocated by the function. - * @param dim1 Number of frames in the output ROI. - * @param dim2 Number of lines per frame in the output ROI. - * @param dim3 Number of pixels per line in the output ROI. - * @param clsm Pointer to a CLSMImage object (default is nullptr). - * @param x_range Range (selection) of pixels for the ROI. - * @param y_range Range (selection) of lines for the ROI. - * @param subtract_average If set to "stack," the mean image of the ROIs computed by - * averaging over all frames is subtracted from each frame, and - * the mean intensity of all frames and pixels is added to the - * pixels. If set to "frame," the average of each frame is - * subtracted from that frame. Default is no correction. - * @param background Constant number subtracted from each pixel. - * @param clip If true, values in the ROI are clipped to the range - * [clip_min, clip_max] (default is false). - * @param clip_max Maximum value when output ROIs are clipped. - * @param clip_min Minimum value when output ROIs are clipped. - * @param images Input array of images used to define ROIs (default is nullptr). - * @param n_frames Number of frames in the input array images. - * @param n_lines Number of lines in the input array images. - * @param n_pixels Number of pixels per line in the input array images. - * @param mask Stack of images used to select pixels (default is nullptr). - * @param dmask1 Number of frames; if smaller than ROI, the first mask frame - * is applied to all ROI frames greater than dmask1. - * @param dmask2 Number of lines; if smaller than ROI, the outside region is - * selected, and the mask is applied to all lines smaller than - * dmask2. - * @param dmask3 Number of pixels per line in the mask. - * @param selected_frames List of frames used to define the ROIs. If empty, all frames - * in the input are used. - */ + /*! + * Copies a region of interest (ROI) into a new image and does some background + * correction. + * + * The ROI is defined by defining a range for the pixels and lines. The ROI + * can be corrected by a constant background value, clipped to limit the range + * of the output values, and corrected by the mean intensity of the frames. + * + * @param output the array that will contain the ROI. The array is allocated + * by the function + * @param dim1 the number of frames in the output ROI + * @param dim2 the number of lines per frame in the output + * @param dim3 the number of pixels per line in the output ROI + * @param clsm a pointer to a CLSMImage object + * @param x_range the range (selection) of the pixels + * @param y_range the range (selection) of the lines + * @param subtract_average If this parameter is set to "stack" the mean image + * of the ROIs that is computed by the average over all frames is subtracted + * from each frame and the mean intensity of all frames and pixels is added + * to the pixels. If this parameter is set to "frame" the average of each + * frame is subtracted from each frame. The default behaviour is to do nothing. + * @param background A constant number that is subtracted from each pixel. + * @param clip If set to true (the default value is false) the values in the + * ROI are clipped to the range [clip_min, clip_max] + * @param clip_max the maximum value when output ROIs are clipped + * @param clip_min the minimum value when output ROIs are clipped + * @param images Input array of images that are used to defined ROIs. If no + * CLSMImage object is specified. This array is used as an input. + * @param n_frames The number of frames in the input array images + * @param n_lines The number of lines in the input array images + * @param n_pixel The number of pixel in the input array images + * @param selected_frames A list of frames that is used to define the ROIs. + * If no frames are defined by this list, all frames in the input are used. + * @param mask a stack of images used as a to select pixels + * @param dmask1 number of frames if the number of frames in the mask is + * smaller then the ROI the first mask frame will be applied to all ROI + * frames that are greater than dmask1 + * @param dmask2 number of lines if smaller then ROI the outside region + * will be selected and the mask will be applied to all lines smaller than + * dmask2 + * @param dmask3 number of pixels per line in the mask. + */ static void get_roi( double** output, int* dim1, int* dim2, int* dim3, CLSMImage* clsm = nullptr, @@ -898,38 +724,21 @@ class CLSMImage { std::string subtract_average = "", double background = 0.0, bool clip=false, double clip_max=1e6, double clip_min=-1e6, - double *images = nullptr, int n_frames=-1, int n_lines=-1, int n_pixels=1, + double *images = nullptr, int input_frames=-1, int input_lines=-1, int input_pixel=1, uint8_t *mask = nullptr, int dmask1 = -1, int dmask2 = -1, int dmask3 = -1, std::vector selected_frames = std::vector() ); - /*! - * \brief Retrieves the time-tagged time-resolved (TTTR) indices of frame markers for - * a Leica SP8 microscope. - * - * This function analyzes a TTTR object to extract frame marker information. The frame - * markers are identified by specified parameters, and the corresponding TTTR indices - * are returned as a vector. - * - * @param tttr Pointer to the TTTR object that is inspected - * (default is nullptr). - * @param start_event Starting event index for analysis (default is 0). - * @param stop_event Stopping event index for analysis (default is -1, - * indicating the end of the TTTR data). - * @param marker_frame_start Vector specifying the frame markers to consider - * (default is {4, 6}). - * @param marker_event_type Event type associated with frame markers - * (default is 15). - * @param reading_routine Type of reading routine, e.g., CLSM_SP8 - * (default is CLSM_SP8). - * @param skip_before_first_frame_marker If true, skip events before the first frame - * marker (default is false). - * @param skip_after_last_frame_marker If true, skip events after the last frame - * marker (default is false). - * @return Vector of TTTR indices corresponding to frame - * markers. - */ + * Get the tttr indices of frame markers for a SP8 + * + * @param tttr pointer to the TTTR object that is inspected + * @param marker_frame vector of + * @param marker_event + * @param start_event + * @param stop_event + * @return + */ static std::vector get_frame_edges( TTTR* tttr = nullptr, int start_event = 0, @@ -941,78 +750,29 @@ class CLSMImage { bool skip_after_last_frame_marker = false ); - /*! - * \brief Identifies line edges by reading start and stop markers in a time-tagged - * time-resolved (TTTR) dataset. - * - * This function analyzes a TTTR object to extract line edges based on specified - * start and stop markers. The corresponding TTTR indices are returned as a vector. - * - * @param tttr Pointer to the TTTR object that is inspected. - * @param start_event Starting event index for analysis. - * @param stop_event Stopping event index for analysis. - * @param marker_line_start Marker value indicating the start of a line - * (default is 1). - * @param marker_line_stop Marker value indicating the stop of a line - * (default is 2). - * @param marker_event_type Event type associated with line markers - * (default is 15). - * @param reading_routine Type of reading routine, e.g., CLSM_SP8 - * (default is CLSM_SP8). - * @return Vector of TTTR indices corresponding to line edges. - */ + /// Read start stop marker to identify line edges static std::vector get_line_edges( - TTTR* tttr, - int start_event, int stop_event, - int marker_line_start = 1, int marker_line_stop = 2, - int marker_event_type = 15, - int reading_routine = CLSM_SP8 + TTTR* tttr, + int start_event, int stop_event, + int marker_line_start = 1, int marker_line_stop = 2, + int marker_event_type = 15, + int reading_routine = CLSM_SP8 ); - - /*! - * \brief Identifies line edges by reading a start marker and using line duration as - * the stop criterion in a time-tagged time-resolved (TTTR) dataset. - * - * This function analyzes a TTTR object to extract line edges based on a specified - * start marker and line duration. The corresponding TTTR indices are returned as a - * vector. - * - * @param tttr Pointer to the TTTR object that is inspected. - * @param start_event Starting event index for analysis. - * @param stop_event Stopping event index for analysis. - * @param marker_line_start Marker value indicating the start of a line - * (default is 1). - * @param line_duration Duration of a line, used as the stop criterion - * (default is 2). - * @param marker_event_type Event type associated with line markers - * (default is 15). - * @param reading_routine Type of reading routine, e.g., CLSM_SP8 - * (default is CLSM_SP8). - * @return Vector of TTTR indices corresponding to line edges. - */ + /// Read start marker and use line duration as stop static std::vector get_line_edges_by_duration( - TTTR* tttr, - int start_event, int stop_event, - int marker_line_start = 1, - int line_duration = 2, - int marker_event_type = 15, - int reading_routine = CLSM_SP8 + TTTR* tttr, + int start_event, int stop_event, + int marker_line_start = 1, + int line_duration = 2, + int marker_event_type = 15, + int reading_routine = CLSM_SP8 ); - - /*! - * \brief Obtains the duration of a line (in milliseconds) for a specified frame and line. - * - * This function calculates the duration of a line in milliseconds for a given frame and - * line based on the time-tagged time-resolved (TTTR) data and header information. - * - * @param frame Number of the frame in the image (default is 0). - * @param line Number of the line in the image (default is 0). - * @return Duration of the line in the selected frame in milliseconds. Returns -1.0 - * if the TTTR object is not initialized or if frame and line indices are - * out of bounds. - */ + /// @brief Obtain line duration (in milliseconds) + /// @param frame number of frame in image + /// @param line number of line in image + /// @return duration of line in selected frame double get_line_duration(int frame = 0, int line = 0){ double re = -1.0; if(tttr != nullptr){ @@ -1033,19 +793,10 @@ class CLSMImage { return re; } - /*! - * \brief Obtains the duration of a pixel (in milliseconds) for a specified frame and line. - * - * This function calculates the duration of a pixel in milliseconds for a given frame and - * line, based on the time-tagged time-resolved (TTTR) data, header information, and the - * number of pixels per line. - * - * @param frame Selected frame number (default is 0). - * @param line Selected line number (default is 0). - * @return Duration of the pixel in the selected frame in milliseconds. Returns -1.0 - * if the TTTR object is not initialized, or if frame and line indices are - * out of bounds. - */ + /// @brief Obtain pixel duration in milliseconds + /// @param frame Selected frame number + /// @param line selected line number + /// @return duration of pixel in selected frame double get_pixel_duration(int frame = 0, int line = 0){ return get_line_duration(frame, line) / settings.n_pixel_per_line; } diff --git a/include/Correlator.h b/include/Correlator.h index 08db9e1b..db5d01ac 100644 --- a/include/Correlator.h +++ b/include/Correlator.h @@ -178,17 +178,17 @@ class Correlator { std::vector &corr_normalized ); - /*! - * @brief Normalize the correlation curve. - * - * This static function makes a copy of the current correlation curve, - * including the x-axis and corresponding correlation amplitudes, - * and calculates the values of the normalized correlation. - * - * @param[in] correlator Reads necessary normalization parameters from the correlator settings. - * @param[in,out] curve Correlation curve to be normalized. - */ - static void normalize(Correlator* correlator, CorrelatorCurve &curve); + /*! + * @brief Normalized the correlation of a correlation curve + * + * Makes a copy of the current correlation curve, i.e., the x-axis and + * and the corresponding correlation amplitudes and calculates the values + * of the normalized correlation. + * + * @param[in] correlator reads necessary normalization parameters from correlator settings + * @param[in,out] curve correlation curve + */ + static void normalize(Correlator* correlator, CorrelatorCurve &curve); public: @@ -197,191 +197,146 @@ class Correlator { CorrelatorCurve curve; /*! - * @brief Compute the time difference in macro time units between the first and the last event. - * - * This function calculates the time difference in macro time units between the first - * and the last event in the event stream. - * - * @return Time difference in macro time units. + * @brief Computes the the time difference in macro time units the first and the last event */ uint64_t dt(); /*! - * @brief Correlator Constructor. * - * Constructs a Correlator object with the specified parameters. - * - * @param[in] tttr Optional TTTR object. If provided, the macro and micro time calibration - * of the TTTR object header calibrate the correlator. - * @param[in] method Name of the correlation method used by the correlator. - * @param[in] n_bins Number of equally spaced correlation bins per block (determines correlation bins). - * @param[in] n_casc Number of blocks (determines correlation bins). - * @param[in] make_fine If true, macro and micro time are combined. + * @param[in] tttr optional TTTR object. If provided, the macro and micro time calibration + * of the TTTR object header calibrate the correlator. + * @param[in] method name of correlation method that is used by the correlator + * @param[in] n_bins number of equally spaced correlation bins per block (determines correlation bins) + * @param[in] n_casc number of blocks (determines correlation bins) + * @param[in] make_fine if true macro and micro time are combined. */ Correlator( - std::shared_ptr tttr = nullptr, - std::string method = "wahl", - int n_bins = 17, - int n_casc = 25, - bool make_fine = false + std::shared_ptr tttr = nullptr, + std::string method = "wahl", + int n_bins = 17, + int n_casc = 25, + bool make_fine = false ); - ~Correlator() = default; /*! - * @brief Set the number of cascades (blocks) of the correlation curve. - * - * This function sets the number of cascades (blocks) of the correlation curve - * and updates the curve accordingly. - * - * @param[in] n_casc Number of cascades (blocks) of the correlation curve. + * @brief Set correlation axis parameter and update axis + * @param[in] n_casc number of cascades (also called blocks) of the correlation curve */ - void set_n_casc(int n_casc) { - curve.set_n_casc(n_casc); - is_valid = false; + void set_n_casc(int v) { + curve.set_n_casc(v); + is_valid = false; } - + /// @brief get correlation /*! - * @brief Get the correlation curve. - * - * Computes the correlation (if necessary) and returns the correlation curve. - * - * @return Correlation curve. - */ + * computes correlation (if necessary) and returns correlation curve + * @return correlation curve + * STOP STOP + */ CorrelatorCurve *get_curve() { if (!is_valid) run(); return &curve; - } - + } /*! - * @brief Get the number of correlation blocks. - * - * Returns the number of correlation blocks (cascades) in the correlation curve. - * - * @return Number of correlation blocks. + * @return number of correlation blocks */ unsigned int get_n_casc() { return curve.get_n_casc(); - } + } /*! - * @brief Set the number of equally spaced correlation channels per block. - * - * This function sets the number of equally spaced correlation channels per block - * and updates the correlation curve accordingly. - * - * @param[in] v Number of equally spaced correlation channels per block. + * @param[in] v number of equally spaced correlation channels per block */ void set_n_bins(int v) { curve.set_n_bins(v); is_valid = false; - } + } /*! - * @brief Get the number of equally spaced correlation channels per block. - * - * Returns the number of equally spaced correlation channels per block in the correlation curve. - * - * @return Number of equally spaced correlation channels per block. + * @return the number of equally spaced correlation channels per block */ unsigned int get_n_bins() const { return curve.settings.n_bins; } - /*! - * @brief Set the correlation method. - * - * This function sets the correlation method used by the correlator. - * - * @param[in] cm The name of the method. Options: "felekyan", "wahl", or "laurence". - * - * References: - * - Felekyan, S., et al., 2005. Full correlation from picoseconds to seconds by time-resolved and - * time-correlated single photon detection. Review of Scientific Instruments, 76(8), p.083104. - * - Wahl, M., et al., 2003. Fast calculation of fluorescence correlation data with asynchronous - * time-correlated single-photon counting, Opt Express Vol. 11, No. 26, p. 3383. - * - Laurence, T.A., et al., 2006. Fast, flexible algorithm for calculating photon correlations, - * Opt Lett. 15;31(6):829-31. + * Correlation method + * @param[in] cm the name of the method options: "felekyan", "wahl", or "laurence" + * + * Felekyan, S., Kühnemuth, R., Kudryavtsev, V., Sandhagen, C., Becker, W. and Seidel, C.A., + * 2005. Full correlation from picoseconds to seconds by time-resolved and time-correlated + * single photon detection. Review of scientific instruments, 76(8), p.083104. + * + * Michael Wahl, Ingo Gregor, Matthias Patting, Joerg Enderlein, + * 2003, Fast calculation of fluorescence correlation data with asynchronous + * time-correlated single-photon counting, Opt Express Vol. 11, No. 26, p. 3383 + * + * Ted A. Laurence, Samantha Fore, Thomas Huser, 2006. Fast, flexible algorithm for + * calculating photon correlations, , Opt Lett. 15;31(6):829-31 + * */ void set_correlation_method(std::string cm) { is_valid = false; correlation_method = cm; - } - + } /*! - * @brief Get the name of the used correlation method. - * - * Returns the name of the correlation method currently set in the correlator. - * - * @return Name of the used correlation method. + * @return name of the used correlation method */ std::string get_correlation_method() { return correlation_method; - } + } /*! - * @brief Add microtime information to the event stream. - * - * This function adds microtime information to the event stream for correlation analysis. + * @brief Add microtime information to event stream * - * @param[in] tac_1 The micro times of the first correlation channel. - * @param[in] n_tac_1 The number of events in the first correlation channel. - * @param[in] tac_2 The micro times of the second correlation channel. - * @param[in] n_tac_2 The number of events in the second correlation channel. + * @param[in] tac_1 The micro times of the first correlation channel + * @param[in] n_tac_1 The number of events in the first correlation channel + * @param[in] tac_2 The micro times of the second correlation channel + * @param[in] n_tac_2 The number of events in the second correlation channel * @param[in] number_of_microtime_channels The maximum number of TAC channels of the micro times. */ void set_microtimes( - unsigned short *tac_1, int n_tac_1, - unsigned short *tac_2, int n_tac_2, - unsigned int number_of_microtime_channels + unsigned short *tac_1, int n_tac_1, + unsigned short *tac_2, int n_tac_2, + unsigned int number_of_microtime_channels ); /*! - * @brief Add macrotimes information to the event stream. - * - * This function adds macrotimes information to the event stream for correlation analysis. - * - * @param[in] t1 Time events in the first correlation channel. - * @param[in] n_t1 The number of time events in the first channel. - * @param[in] t2 Time events in the second correlation channel. - * @param[in] n_t2 The number of time events in the second channel. - */ + * @param[in] t1 time events in the the first correlation channel + * @param[in] n_t1 The number of time events in the first channel + * @param[in] t1 time events in the the second correlation channel + * @param[in] n_t2 The number of time events in the second channel + */ void set_macrotimes( - unsigned long long *t1, int n_t1, - unsigned long long *t2, int n_t2 + unsigned long long *t1, int n_t1, + unsigned long long *t2, int n_t2 ); /*! - * @brief Get event times of the first and second correlation channel. - * - * This function returns the event times of the first and second correlation channel. - * - * @return A pair of vectors containing event times of the first and second correlation channel. - */ - std::pair, std::vector> get_macrotimes() { - return {this->p1.times, this->p2.times}; - } - + * @brief get event times of first and second correlation channel + * + * @return event times of first and second correlation channel + */ + std::pair, std::vector> + get_macrotimes() { + return {this->p1.times, this->p2.times}; + } /*! - * @brief Set time events and weights for the first and second correlation channels. - * - * This function sets the time events and weights for the first and second correlation channels. - * - * @param[in] t1 An array containing the time events of the first channel. - * @param[in] n_t1 The number of time events in the first channel. - * @param[in] weight_ch1 A vector of weights for the time events of the first channel. - * @param[in] n_weights_ch1 The number of weights for the first channel. - * @param[in] t2 An array containing the time events of the second channel. - * @param[in] n_t2 The number of time events in the second channel. - * @param[in] weight_ch2 A vector of weights for the time events of the second channel. - * @param[in] n_weights_ch2 The number of weights for the second channel. - */ + * + * @param[in] time events of the first correlation channel + * @param[in] n_t1 The number of time events in the first channel + * @param[in] w1 A vector of weights for the time events of the first channel + * @param[in] n_weights_ch1 The number of weights of the first channel + * @param[in] t2 A vector of the time events of the second channel + * @param[in] n_t2 The number of time events in the second channel + * @param[in] w2 A vector of weights for the time events of the second channel + * @param[in] n_weights_ch2 The number of weights of the second channel + */ void set_events( unsigned long long *t1, int n_t1, double *weight_ch1, int n_weights_ch1, @@ -389,16 +344,15 @@ class Correlator { double *weight_ch2, int n_weights_ch2 ); - /*! - * @brief Set weights used for correlation. - * - * This function sets and updates weights for the events in the first and second correlation channels. + * @brief Set weights used for correlation + * + * Set and update weights of the events in first and second correlation channel * - * @param[in] weight_ch1 A vector of weights for the time events of the first channel. - * @param[in] n_weights_ch1 The number of weights for the first channel. - * @param[in] weight_ch2 A vector of weights for the time events of the second channel. - * @param[in] n_weights_ch2 The number of weights for the second channel. + * @param[in] w1 A vector of weights for the time events of the first channel + * @param[in] n_weights_ch1 The number of weights of the first channel + * @param[in] w2 A vector of weights for the time events of the second channel + * @param[in] n_weights_ch2 The number of weights of the second channel */ void set_weights( double *weight_ch1, int n_weights_ch1, @@ -406,13 +360,9 @@ class Correlator { ); /*! - * @brief Get weights used for correlation. - * - * This function retrieves the weights for the events in the first and second correlation channels. - * - * @return A pair of vectors containing weights for the first and second correlation channels, respectively. - */ - std::pair, std::vector> get_weights(){ + * @return weights in first and second correlation channel + */ + std::pair, std::vector> get_weights() { return {this->p1.weights, this->p2.weights}; } @@ -420,7 +370,7 @@ class Correlator { * @brief Get correlation bins (axis) * * @param[out] output x_axis / time axis of the correlation - * @param[out] n_output number of elements in the axis + * @param[out] n_out number of elements in the axis * of the x-axis */ void get_x_axis(double **output, int *n_output); @@ -474,18 +424,15 @@ class Correlator { std::pair, std::shared_ptr> get_tttr(); - /*! - * @brief Update weights based on a filter map and event information. - * - * This function updates the weights. Non-zero weights are assigned a filter value based on a filter map - * and the micro time of the event. + /*! + * Updates the weights. Non-zero weights are assigned a filter value that + * is defined by a filter map and the micro time of the event. * - * @param filter[in] A map of filters where the first element in the map is the routing channel number, - * and the second element is a vector that maps a micro time to a filter value. - * @param micro_times_1[in] Micro times of events in the first correlation channel. - * @param routing_channels_1[in] Routing channels of events in the first correlation channel. - * @param micro_times_2[in] Micro times of events in the second correlation channel. - * @param routing_channels_2[in] Routing channels of events in the second correlation channel. + * @param micro_times[in] + * @param routing_channels[in] + * @param filter[in] map of filters the first element in the map is the routing + * channel number, the second element of the map is a vector that maps a + * micro time to a filter value. */ void set_filter( const std::map> &filter, diff --git a/include/CorrelatorCurve.h b/include/CorrelatorCurve.h index 0ea7c578..d16d746a 100644 --- a/include/CorrelatorCurve.h +++ b/include/CorrelatorCurve.h @@ -5,8 +5,6 @@ #include #include /* std::max */ #include /* pow */ -#include // include this header for uint64_t - struct CorrelationCurveSettings{ @@ -59,30 +57,12 @@ class CorrelatorCurve{ /// The normalized correlation std::vector corr_normalized; - /** - * @brief Resizes the internal vectors to a specified size. - * - * @param n The new size for the vectors. - */ void resize(size_t n){ x_axis.resize(n); correlation.resize(n); corr_normalized.resize(n); } - /** - * @brief Clear the correlation values. - * - * This method sets all values in the correlation vector to zero, effectively - * resetting the correlation curve. After calling this method, the correlation - * curve will be empty. - * - * Example Usage: - * @code - * // Clear the correlation values - * correlatorCurve.clear(); - * @endcode - */ void clear(){ std::fill(correlation.begin(), correlation.end(), 0.0); } @@ -92,76 +72,42 @@ class CorrelatorCurve{ /// Stores the settings of the correlation curve, i.e., the number of correlation bins CorrelationCurveSettings settings; - /** - * @brief Get the size of the correlation curve. - * - * This method returns the size of the correlation curve, which corresponds - * to the number of elements in the x-axis and correlation vectors. - * - * @return The size of the correlation curve. - * - * Example Usage: - * @code - * // Get the size of the correlation curve - * size_t curveSize = correlatorCurve.size(); - * @endcode - */ size_t size(){ return x_axis.size(); } - /** - * @brief Get the x-axis of the correlation. - * - * This method retrieves the x-axis (time axis) of the correlation curve. + /*! + * @brief Get the x-axis of the correlation * - * @param[out] output A pointer to an array that will contain the x-axis. - * @param[out] n_output A pointer to an integer that will contain the - * number of elements in the x-axis. + * @param[out] x_axis a pointer to an array that will contain the x-axis + * @param[out] n_out a pointer to the an integer that will contain the + * number of elements of the x-axis */ void get_x_axis(double **output, int *n_output); /*! - * @brief Set the x-axis to arbitrary bin values. - * - * Attention: Make sure that the correlation method supports arbitrary bin spacing. - * - * @param[in] input A vector of long long unsigned integers representing the desired bin values. - */ + * @brief Set the x-axis to arbitray bin values. + * + * Attention: Make sure that the correlation method supports arbitray bin spacing + */ void set_x_axis(std::vector input); /*! - * @brief Set the number of equally spaced correlation channels per block. - * - * This method updates the number of bins in the correlation curve. The number - * of bins is set to the maximum of the specified value and 1. After updating - * the settings, the x-axis (correlation bins) is also updated accordingly. - * - * @param[in] v The number of equally spaced correlation channels per block. + * @param[in] v the number of equally spaced correaltion channels per block */ void set_n_bins(int v) { settings.n_bins = std::max(1, v); update_axis(); } - /*! - * @brief Get the number of equally spaced correlation channels per block. - * - * This method retrieves the number of bins in the correlation curve. - * - * @return The number of equally spaced correlation channels per block. - */ unsigned int get_n_bins() { return settings.n_bins; } /*! - * @brief Set the number of cascades (blocks) in the correlation curve and update the correlation axis. - * - * This method sets the number of cascades (blocks) in the correlation curve and ensures it is at least 1. - * It then updates the correlation axis accordingly. - * - * @param[in] v The desired number of cascades. + * Sets the number of cascades (also called blocks) of the correlation curve + * and updates the correlation axis. + * @param[in] n_casc */ void set_n_casc(int v) { settings.n_casc = std::max(1, v); @@ -169,30 +115,14 @@ class CorrelatorCurve{ } /*! - * @brief Get the number of cascades (blocks) in the correlation curve. - * - * This method returns the current number of cascades (blocks) in the correlation curve. - * - * @return The number of cascades. + * @return number of correlation blocks */ unsigned int get_n_casc() const { return settings.n_casc; } - /*! - * @brief Get the non-normalized correlation values. - * - * @param[out] output A pointer to an array that will contain the non-normalized correlation values. - * @param[out] n_output A pointer to an integer that will contain the number of elements in the correlation array. - */ void get_corr(double** output, int* n_output); - /*! - * @brief Get the normalized correlation values. - * - * @param[out] output A pointer to an array that will contain the normalized correlation values. - * @param[out] n_output A pointer to an integer that will contain the number of elements in the normalized correlation array. - */ void get_corr_normalized(double** output, int* n_output); }; diff --git a/include/CorrelatorPhotonStream.h b/include/CorrelatorPhotonStream.h index cdf5ea2d..553aba6f 100644 --- a/include/CorrelatorPhotonStream.h +++ b/include/CorrelatorPhotonStream.h @@ -8,9 +8,7 @@ -/*! - * @brief CorrelatorPhotonStream class gathers event times and weights. - */ +//! CorrelatorPhotonStream gathers event times and weights class CorrelatorPhotonStream{ friend class Correlator; @@ -26,143 +24,75 @@ class CorrelatorPhotonStream{ public: - /*! - * @brief Default constructor for CorrelatorPhotonStream. - */ CorrelatorPhotonStream() = default; - /*! - * @brief Copy constructor for CorrelatorPhotonStream. - * - * @param a Another CorrelatorPhotonStream object to copy. - */ CorrelatorPhotonStream(const CorrelatorPhotonStream& a): times(a.times), weights(a.weights) {}; - /*! - * @brief Default destructor for CorrelatorPhotonStream. - */ ~CorrelatorPhotonStream() = default; - /*! - * @brief The array containing the time points of the first correlation channel. - */ + /// The array containing the times points of the first correlation channel std::vector times; - /*! - * @brief The array containing the weights of the first correlation channel. - */ + /// The array containing the weights of the first correlation channel std::vector weights; - /** - * @brief Check if the CorrelatorPhotonStream is empty. - * - * @return True if both the times and weights arrays are empty, false otherwise. - */ bool empty() const{ return times.empty() && weights.empty(); } - /** - * @brief Get the size of the CorrelatorPhotonStream. - * - * @return The number of elements in the times array. - */ size_t size() const{ return times.size(); } - /** - * @brief Clear the CorrelatorPhotonStream. - * - * Clears the times and weights arrays, making them empty. - */ void clear(){ times.clear(); weights.clear(); } - /** - * @brief Resize the CorrelatorPhotonStream. - * - * Resizes the times and weights arrays to the specified size, setting the - * initial value of weights to the provided value. + /*! * - * @param n The new size for the arrays. - * @param x The initial value of the weights (default is 1.0). + * @param n + * @param x initial value of the weights */ - void resize(size_t n, double x = 1.0){ + void resize(size_t n, double x=1.0){ times.resize(n); weights.resize(n, x); } - /** - * @brief Make time events fine by adding micro time to macro time. + /*! + * Changes the time events by adding the micro time to the macro time * * Changes the time events by adding the micro time to the macro time. * The micro times should match the macro time, i.e., the length of - * the micro time array should be at least the same length as the + * the micro time array should be the at least the same length as the * macro time array. * - * @param[in,out] t An array containing the time events (macro times). + * @param[in,out] t An array containing the time events (macro times) * @param[in] n_times The number of macro times. - * @param[in] tac An array containing the micro times corresponding to macro times. - * @param[in] n_tac The number of micro times. - */ + * @param[in] tac An array containing the micro times of the corresponding macro times + !*/ static void make_fine_times( unsigned long long *t, unsigned int n_times, unsigned short *tac, unsigned int n_tac ); - /** - * @brief Make time events fine by adding micro time to macro time. - * - * Changes the time events by adding the micro time to the macro time. - * The micro times should match the macro time, i.e., the length of - * the micro time array should be at least the same length as the - * macro time array. - * - * @param[in] tac An array containing the micro times corresponding to macro times. - * @param[in] n_tac The number of micro times. - * @param[in] number_of_microtime_channels The maximum number of TAC channels of the micro times. - */ void make_fine( unsigned short *tac, int n_tac, unsigned int number_of_microtime_channels ); - /** - * @brief Set weights using a filter for time events. - * - * The weights are set based on a filter map and optional micro times and routing channels. - * - * @param[in] filter Map of filters. The first element in the map is the routing - * channel number, and the second element of the map is a vector that maps a - * micro time to a filter value. - * @param[in] micro_times Optional array containing micro times. - * @param[in] routing_channels Optional array containing routing channels. - */ void set_weights( const std::map>& filter, std::vector micro_times = std::vector(), std::vector routing_channels = std::vector() ); - /** - * @brief Set time events and weights. - * - * Sets the time events and their corresponding weights based on provided arrays. - * - * @param[in] t Array containing time events. - * @param[in] n_t Number of time events. - * @param[in] weight Array containing weights. - * @param[in] n_weight Number of weights. - */ void set_events( - unsigned long long *t, int n_t, - double* weight, int n_weight - ){ + unsigned long long *t, int n_t, + double* weight, int n_weight + ){ resize(std::min(n_t, n_weight)); for(size_t i = 0; i < size();i++){ times[i] = t[i]; @@ -170,74 +100,46 @@ class CorrelatorPhotonStream{ } } - /** - * @brief Coarsen the time events. + /*! + * Coarsens the time events + * + * This method coarsens the time events by dividing the times by two. + * In case two consecutive time events in the array have the same time, the + * weights of the two events are added to the following weight element and the + * value of the previous weight is set to zero. * - * Coarsens the time events by dividing the times by two. If two consecutive time events - * have the same time, the weights of the two events are added to the following weight element, - * and the value of the previous weight is set to zero. */ void coarsen(); - /** - * @brief Compute the time difference in macro time units between the first and last event. - * - * @return The time difference between the first and last event. - */ unsigned long long dt(); - /** - * @brief Compute the sum of weights in the correlation stream. - * - * @return The sum of weights in the correlation stream. - */ double sum_of_weights(); - /** - * @brief Compute the mean count rate in the correlation stream. - * - * @return The mean count rate in counts per macro time clock. - */ double mean_count_rate(); - /** - * @brief Set the time axis calibration. - * - * The time axis calibration represents the duration between two sync signals (macro time clock). + /*! + * Set time axis calibration. The time axis calibration if the duration of + * between two sync signals (macro time clock) * - * @param v The time axis calibration in seconds. + * @param v time axis calibration (duration between sync clock signals) in + * seconds */ void set_time_axis_calibration(double v); - /** - * @brief Get the calibration of the time axis. - * - * Returns the calibration of the time axis in seconds, which represents the duration - * of a sync signal (macro time clock). - * - * @return The calibration of the time axis in seconds. + /*! + * @return The calibration of the time axis in seconds. The time axis + * calibration is the duration of a sync signal (macro time clock). */ double get_time_axis_calibration() const{ return time_axis_calibration; } - /** - * @brief Set the TTTR object for the CorrelatorPhotonStream. - * - * Sets the TTTR object for the CorrelatorPhotonStream and optionally makes the time events fine - * by adding the micro time to the macro time. - * - * @param tttr The TTTR object to set. - * @param make_fine If true, makes the time events fine by adding the micro time to the macro time. - */ - void set_tttr(std::shared_ptr tttr, bool make_fine = false); + void set_tttr( + std::shared_ptr tttr, + bool make_fine = false + ); - /** - * @brief Get the TTTR object associated with the CorrelatorPhotonStream. - * - * @return The shared pointer to the TTTR object. - */ - std::shared_ptr get_tttr() const { + std::shared_ptr get_tttr() const{ return tttr; } diff --git a/include/DecayConvolution.h b/include/DecayConvolution.h index 27f3fe93..cfb7fa5b 100644 --- a/include/DecayConvolution.h +++ b/include/DecayConvolution.h @@ -1,5 +1,5 @@ -#ifndef TTTRLIB_FSCONV_H -#define TTTRLIB_FSCONV_H +#ifndef FIT2X_FSCONV_H +#define FIT2X_FSCONV_H #include /* std::ceil */ #include /* std::accumulate */ @@ -70,27 +70,26 @@ void rescale_w(double *fit, double *decay, double *w_sq, double *scale, int star /*! - * \brief Scale the model function to the data considering weights and background. + * @brief Scale model function to the data (with weights and background) * - * This function scales the model function (fit) to the data by counting the number + * This function scales the model function (fit) to the data by the number * of photons between a start and a stop micro time counting channel. The number - * of photons between start and stop is counted, and the model function is scaled - * to match the data by area, considering the noise of the data and a constant + * of photons between start and stop are counted and the model function is scaled + * to match the data by area considering the noise of the data and a constant * offset of the data. * - * The scaling parameter (scale) is calculated using the formula: - * \f$ \text{scale} = \frac{\sum (\text{fit} \cdot (\text{decay} - \text{bg}) / w^2)}{\sum (\text{fit}^2 / w^2)} \f$ + * scale = sum(fit*(decay-bg)/w^2)/sum(fit^2/w^2) * - * @param fit [in,out] Model function that is scaled (modified in-place). - * @param decay [in] Experimental data to which the model function is scaled. - * @param w_sq [in] Squared weights of the data. - * @param bg [in] Constant background of the data. - * @param scale [out] The scaling parameter (the factor) by which the model + * @param fit[in,out] model function that is scaled (modified in-place) + * @param decay[in] the experimental data to which the model function is scaled + * @param w_sq[in] squared weights of the data. + * @param bg[in] constant background of the data + * @param scale[out] the scaling parameter (the factor) by which the model * function is multiplied. - * @param start [in] The start micro time channel. - * @param stop [in] The stop micro time channel. + * @param start[in] The start micro time channel + * @param stop[in] The stop micro time channel */ -void rescale_w_bg(double *fit, double *decay, double *w_sq, double bg, double *scale, int start, int stop); +void rescale_w_bg(double *fit, double *decay, double *e_sq, double bg, double *scale, int start, int stop); /*! @@ -294,106 +293,110 @@ void add_pile_up_to_model( /*! - * \brief Threshold the amplitudes in the interleaved lifetime spectrum. + * Threshold the amplitudes * * Amplitudes with absolute values smaller than the specified threshold are * set to zero. * - * @param lifetime_spectrum [in,out] Interleaved lifetime spectrum (amplitude, lifetime). - * @param n_lifetime_spectrum [in] Number of elements in the lifetime spectrum. - * @param amplitude_threshold [in] Threshold value for amplitude discrimination. + * @param lifetime_spectrum interleaved lifetime spectrum (amplitude, lifetime) + * @param n_lifetime_spectrum number of elements in lifetime spectrum + * @param amplitude_threshold */ void discriminate_small_amplitudes( - double* lifetime_spectrum, int n_lifetime_spectrum, - double amplitude_threshold + double* lifetime_spectrum, int n_lifetime_spectrum, + double amplitude_threshold ); /*! -* \brief Compute the fluorescence decay for a lifetime spectrum and an instrument +* Compute the fluorescence decay for a lifetime spectrum and a instrument * response function considering periodic excitation. * -* Fills the pre-allocated output array `model` with a fluorescence -* intensity decay defined by a set of fluorescence lifetimes specified in the -* `lifetime_spectrum` parameter. The fluorescence decay is convolved -* (non-periodically) with an instrumental response function defined by -* `irf`. +* Fills the pre-allocated output array `output_decay` with a fluorescence +* intensity decay defined by a set of fluorescence lifetimes defined by the +* parameter `lifetime_handler`. The fluorescence decay will be convolved +* (non-periodically) with an instrumental response function that is defined +* by `instrument_response_function`. * -* This function calculates a fluorescence intensity model that is +* This function calculates a fluorescence intensity model_decay that is * convolved with an instrument response function (IRF). The fluorescence -* intensity model is specified by its fluorescence lifetime spectrum, -* represented by an interleaved array containing fluorescence lifetimes with +* intensity model_decay is specified by its fluorescence lifetime spectrum, +* i.e., an interleaved array containing fluorescence lifetimes with * corresponding amplitudes. * * This convolution only works with evenly linear spaced time axes. * -* @param model [in,out] In-place output array that is filled with the values -* of the computed fluorescence intensity decay model. -* @param n_model [in] Number of elements in the output array. -* @param time_axis [in] Time-axis of the model. -* @param n_time_axis [in] Length of the time axis. -* @param irf [in] Instrument response function array. -* @param n_irf [in] Length of the instrument response function array. -* @param lifetime_spectrum [in] Interleaved array of amplitudes and fluorescence -* lifetimes in the form (amplitude, lifetime, amplitude, lifetime, ...). -* @param n_lifetime_spectrum [in] Number of elements in the lifetime spectrum. -* @param convolution_start [in] Start channel of convolution (position in array -* of IRF). -* @param convolution_stop [in] Convolution stop channel (the index on the time-axis). -* @param period [in] Period of repetition in units of the lifetime (usually, -* nano-seconds). Default value is 100.0. +* @param inplace_output[in,out] Inplace output array that is filled with the values +* of the computed fluorescence intensity decay model +* @param n_output[in] Number of elements in the output array +* @param time_axis[in] the time-axis of the model_decay +* @param n_time_axis[in] length of the time axis +* @param irf[in] the instrument response function array +* @param n_irf[in] length of the instrument response function array +* @param lifetime_spectrum[in] Interleaved array of amplitudes and fluorescence +* lifetimes of the form (amplitude, lifetime, amplitude, lifetime, ...) +* @param n_lifetime_spectrum[in] number of elements in the lifetime spectrum +* @param convolution_start[in] Start channel of convolution (position in array of IRF) +* @param convolution_stop[in] convolution stop channel (the index on the time-axis) +* @param period Period of repetition in units of the lifetime (usually, +* nano-seconds) */ void fconv_per_cs_time_axis( - double *model, int n_model, - double *time_axis, int n_time_axis, - double *irf, int n_irf, - double *lifetime_spectrum, int n_lifetime_spectrum, - int convolution_start = 0, - int convolution_stop = -1, - double period = 100.0 + double *model, int n_model, + double *time_axis, int n_time_axis, + double *irf, int n_irf, + double *lifetime_spectrum, int n_lifetime_spectrum, + int convolution_start = 0, + int convolution_stop = -1, + double period = 100.0 ); /*! - * \brief Compute the fluorescence decay for a lifetime spectrum and an instrument response function. - * - * Fills the pre-allocated output array `inplace_output` with a fluorescence - * intensity decay defined by a set of fluorescence lifetimes specified in the - * `lifetime_spectrum` parameter. The fluorescence decay is convolved - * (non-periodically) with an instrumental response function defined by - * `instrument_response_function`. - * - * This function calculates a fluorescence intensity decay model that is - * convolved with an instrument response function (IRF). The fluorescence - * intensity decay model is specified by its fluorescence lifetime spectrum, - * represented by an interleaved array containing fluorescence lifetimes with - * corresponding amplitudes. - * - * The convolution supports unevenly spaced time axes. - * - * @param inplace_output [in,out] In-place output array that is filled with the - * values of the computed fluorescence intensity decay model. - * @param n_output [in] Number of elements in the output array. - * @param time_axis [in] Time-axis of the fluorescence intensity decay model. - * @param n_time_axis [in] Length of the time axis. - * @param instrument_response_function [in] Instrument response function array. - * @param n_instrument_response_function [in] Length of the instrument response function array. - * @param lifetime_spectrum [in] Interleaved array of amplitudes and fluorescence - * lifetimes in the form (amplitude, lifetime, amplitude, lifetime, ...). - * @param n_lifetime_spectrum [in] Number of elements in the lifetime spectrum. - * @param convolution_start [in] Start channel of convolution (position in array - * of IRF). - * @param convolution_stop [in] Convolution stop channel (the index on the time-axis). - */ +* Compute the fluorescence decay for a lifetime spectrum and a instrument +* response function. +* +* Fills the pre-allocated output array `output_decay` with a fluorescence +* intensity decay defined by a set of fluorescence lifetimes defined by the +* parameter `lifetime_handler`. The fluorescence decay will be convolved +* (non-periodically) with an instrumental response function that is defined +* by `instrument_response_function`. +* +* This function calculates a fluorescence intensity model_decay that is +* convolved with an instrument response function (IRF). The fluorescence +* intensity model_decay is specified by its fluorescence lifetime spectrum, +* i.e., an interleaved array containing fluorescence lifetimes with +* corresponding amplitudes. +* +* This convolution works also with uneven spaced time axes. +* +* @param inplace_output[in,out] Inplace output array that is filled with the +* values of the computed fluorescence intensity decay model +* @param n_output[in] Number of elements in the output array +* @param time_axis[in] the time-axis of the model_decay +* @param n_time_axis[in] length of the time axis +* @param irf[in] the instrument response function array +* @param n_irf[in] length of the instrument response function array +* @param lifetime_spectrum[in] Interleaved array of amplitudes and fluorescence +* lifetimes of the form (amplitude, lifetime, amplitude, lifetime, ...) +* @param n_lifetime_spectrum[in] number of elements in the lifetime spectrum +* @param convolution_start[in] Start channel of convolution (position in array +* of IRF) +* @param convolution_stop[in] convolution stop channel (the index on the time-axis) +* @param use_amplitude_threshold[in] If this value is True (default False) +* fluorescence lifetimes in the lifetime spectrum which have an amplitude +* with an absolute value of that is smaller than `amplitude_threshold` are +* not omitted in the convolution. +* @param amplitude_threshold[in] Threshold value for the amplitudes +*/ void fconv_cs_time_axis( - double *inplace_output, int n_output, - double *time_axis, int n_time_axis, - double *instrument_response_function, int n_instrument_response_function, - double *lifetime_spectrum, int n_lifetime_spectrum, - int convolution_start = 0, - int convolution_stop = -1 + double *inplace_output, int n_output, + double *time_axis, int n_time_axis, + double *instrument_response_function, int n_instrument_response_function, + double *lifetime_spectrum, int n_lifetime_spectrum, + int convolution_start = 0, + int convolution_stop = -1 ); - -#endif //TTTRLIB_FSCONV_H +#endif //FIT2X_FSCONV_H diff --git a/include/DecayFit.h b/include/DecayFit.h index bb4d1b8e..9978d453 100644 --- a/include/DecayFit.h +++ b/include/DecayFit.h @@ -1,5 +1,5 @@ -#ifndef TTTRLIB_DECAYFIT_H -#define TTTRLIB_DECAYFIT_H +#ifndef FIT2X_DECAYFIT_H +#define FIT2X_DECAYFIT_H #include #include @@ -299,4 +299,4 @@ class DecayFit{ }; -#endif //TTTRLIB_DECAYFIT_H +#endif //FIT2X_DECAYFIT_H diff --git a/include/DecayFit23.h b/include/DecayFit23.h index 6e889d25..ae506c32 100644 --- a/include/DecayFit23.h +++ b/include/DecayFit23.h @@ -1,5 +1,5 @@ -#ifndef TTTRLIB_DECAYFIT23_H -#define TTTRLIB_DECAYFIT23_H +#ifndef FIT2X_DECAYFIT23_H +#define FIT2X_DECAYFIT23_H #include #include @@ -141,4 +141,4 @@ class DecayFit23 { }; -#endif //TTTRLIB_DECAYFIT23_H +#endif //FIT2X_DECAYFIT23_H diff --git a/include/DecayFit24.h b/include/DecayFit24.h index b9670faa..380f8c53 100644 --- a/include/DecayFit24.h +++ b/include/DecayFit24.h @@ -1,5 +1,5 @@ -#ifndef TTTRLIB_DECAYFIT24_H -#define TTTRLIB_DECAYFIT24_H +#ifndef FIT2X_DECAYFIT24_H +#define FIT2X_DECAYFIT24_H #include "DecayFit.h" #include "DecayConvolution.h" @@ -114,4 +114,4 @@ class DecayFit24 : DecayFit { }; -#endif //TTTRLIB_DECAYFIT24_H +#endif //FIT2X_DECAYFIT24_H diff --git a/include/DecayFit25.h b/include/DecayFit25.h index ed6a2efb..983ba71e 100644 --- a/include/DecayFit25.h +++ b/include/DecayFit25.h @@ -1,5 +1,5 @@ -#ifndef TTTRLIB_DECAYFIT25_H -#define TTTRLIB_DECAYFIT25_H +#ifndef FIT2X_DECAYFIT25_H +#define FIT2X_DECAYFIT25_H #include "DecayConvolution.h" @@ -67,4 +67,4 @@ class DecayFit25 : DecayFit { }; -#endif //TTTRLIB_DECAYFIT25_H +#endif //FIT2X_DECAYFIT25_H diff --git a/include/DecayFit26.h b/include/DecayFit26.h index 715a4fb5..454c791f 100644 --- a/include/DecayFit26.h +++ b/include/DecayFit26.h @@ -1,5 +1,5 @@ -#ifndef TTTRLIB_DECAYFIT26_H -#define TTTRLIB_DECAYFIT26_H +#ifndef FIT2X_DECAYFIT26_H +#define FIT2X_DECAYFIT26_H #include "DecayFit.h" #include "DecayConvolution.h" @@ -43,4 +43,4 @@ class DecayFit26 : DecayFit { }; -#endif //TTTRLIB_DECAYFIT26_H +#endif //FIT2X_DECAYFIT26_H diff --git a/include/DecayPhasor.h b/include/DecayPhasor.h index 06be15a0..5e60f211 100644 --- a/include/DecayPhasor.h +++ b/include/DecayPhasor.h @@ -1,5 +1,5 @@ -#ifndef TTTRLIB_PHASOR_H -#define TTTRLIB_PHASOR_H +#ifndef FIT2X_PHASOR_H +#define FIT2X_PHASOR_H #include #include @@ -9,50 +9,47 @@ #include "CLSMImage.h" /* CLSMImage */ -/** - * @brief Utility class for computing phasor values in decay analysis. - */ class DecayPhasor{ public: - /** - * @brief Compute the phasor (g, s) for a selection of microtimes. + /*! + * Compute the phasor (g,s) for a selection of micro times * - * This function computes the phasor (g, s) for a set of microtimes that are selected - * using a second vector of indices. The indices specify which elements of the microtimes + * This function computes the phasor (g,s) for a set of micro times + * that are selected out of an vector. The microtimes are selected by a + * second vector. The second vector speciefies which indices of the microtime * vector are used to compute the phasor. * - * @param[in] microtimes Vector of microtimes. - * @param[in] n_microtimes Number of elements in the microtimes vector. - * @param[in] frequency The frequency of the phasor. - * @param[in] minimum_number_of_photons Minimum number of photons. - * @param[in] g_irf G-value of instrument response phasor. - * @param[in] s_irf S-value of instrument response phasor. - * @param[in] idxs Vector of selected indices. - * @return Vector of length 2: first element g-value, second element s-value. + * @param micro_times vector of micro times + * @param idxs vector of selected indices + * @param minimum_number_of_photons + * @param frequency the frequency of the phasor + * @param g_irf g-value of instrument response phasor + * @param s_irf s-value of instrument response phasor + * @return vector of length 2: first element g-value, second element s-value */ + static std::vector compute_phasor( unsigned short* microtimes, int n_microtimes, double frequency = 1.0, int minimum_number_of_photons = 1, - double g_irf = 1.0, - double s_irf = 0.0, + double g_irf=1.0, + double s_irf=0.0, std::vector* idxs = nullptr ); - - /** - * @brief Compute the phasor (g, s) for a histogram/bincounts of microtimes. + /*! + * Compute the phasor (g,s) for a histogram / bincounts * - * This function computes the phasor (g, s) for bincounted microtimes. + * This function computes the phasor (g,s) for bincounted micro times * - * @param[in] bincounts Vector of bincounts. - * @param[in] frequency The frequency of the phasor. - * @param[in] minimum_number_of_photons Minimum number of photons. - * @param[in] g_irf G-value of instrument response phasor. - * @param[in] s_irf S-value of instrument response phasor. - * @return Vector of length 2: first element g-value, second element s-value. + * @param bincounts vector bincounts + * @param minimum_number_of_photons + * @param frequency the frequency of the phasor + * @param g_irf g-value of instrument response phasor + * @param s_irf s-value of instrument response phasor + * @return vector of length 2: first element g-value, second element s-value */ static std::vector compute_phasor_bincounts( std::vector &bincounts, @@ -61,34 +58,28 @@ class DecayPhasor{ double g_irf, double s_irf ); - - /** - * @brief Calculate g-value for a given set of phasor parameters. + /*! + * https://journals.plos.org/plosone/article/file?type=supplementary&id=info:doi/10.1371/journal.pone.0194578.s001 * - * Reference: https://journals.plos.org/plosone/article/file?type=supplementary&id=info:doi/10.1371/journal.pone.0194578.s001 - * - * @param[in] g_irf G-value of instrument response phasor. - * @param[in] s_irf S-value of instrument response phasor. - * @param[in] g_exp Experimental g-value. - * @param[in] s_exp Experimental s-value. - * @return Computed g-value. + * @param g_irf g-value of instrument response phasor + * @param s_irf s-value of instrument response phasor + * @param g_exp + * @param s_exp + * @return */ static double g( double g_irf, double s_irf, double g_exp, double s_exp ); - - /** - * @brief Calculate s-value for a given set of phasor parameters. - * - * Reference: https://journals.plos.org/plosone/article/file?type=supplementary&id=info:doi/10.1371/journal.pone.0194578.s001 + /*! + * https://journals.plos.org/plosone/article/file?type=supplementary&id=info:doi/10.1371/journal.pone.0194578.s001 * - * @param[in] g_irf G-value of instrument response phasor. - * @param[in] s_irf S-value of instrument response phasor. - * @param[in] g_exp Experimental g-value. - * @param[in] s_exp Experimental s-value. - * @return Computed s-value. + * @param g_irf + * @param s_irf + * @param g_exp + * @param s_exp + * @return */ static double s( double g_irf, double s_irf, @@ -98,4 +89,4 @@ class DecayPhasor{ }; -#endif //TTTRLIB_PHASOR_H +#endif //FIT2X_PHASOR_H diff --git a/include/DecayStatistics.h b/include/DecayStatistics.h index 29a887af..6666f297 100644 --- a/include/DecayStatistics.h +++ b/include/DecayStatistics.h @@ -1,5 +1,5 @@ -#ifndef TTTRLIB_DECAYSTATISTICS_H -#define TTTRLIB_DECAYSTATISTICS_H +#ifndef FIT2X_DECAYSTATISTICS_H +#define FIT2X_DECAYSTATISTICS_H #include @@ -180,17 +180,16 @@ namespace statistics{ } /*! - * @brief Computes different chi2 measures for counting data. + * Different chi2 measures for counting data: * - * Reference: https://arxiv.org/pdf/1903.07185.pdf + * https://arxiv.org/pdf/1903.07185.pdf * - * @param data Vector containing the data. - * @param model Vector containing the model. - * @param weights Vector containing the weights. - * @param x_min Minimum index for computation. - * @param x_max Maximum index for computation. - * @param type Type of chi2 measure (default is "neyman"). - * @return The computed chi2 value. + * @param data + * @param model + * @param x_min + * @param x_max + * @param type + * @return */ double chi2_counting( std::vector &data, @@ -198,9 +197,8 @@ namespace statistics{ std::vector &weights, int x_min = -1, int x_max = -1, - const char* type = "neyman" + const char* type="neyman" ); - } -#endif //TTTRLIB_DECAYSTATISTICS_H +#endif //FIT2X_DECAYSTATISTICS_H diff --git a/include/LvArrays.h b/include/LvArrays.h index f85aa060..e9720454 100644 --- a/include/LvArrays.h +++ b/include/LvArrays.h @@ -6,8 +6,8 @@ * a this files defines a set of functions that facilitate the creation of the * LabView structures. */ -#ifndef TTTRLIB_DECAYLVARRAYS_H -#define TTTRLIB_DECAYLVARRAYS_H +#ifndef FIT2X_DECAYLVARRAYS_H +#define FIT2X_DECAYLVARRAYS_H #include #include @@ -105,4 +105,4 @@ MParam* CreateMParam( std::vector data = std::vector() ); -#endif //TTTRLIB_DECAYLVARRAYS_H +#endif //FIT2X_DECAYLVARRAYS_H diff --git a/include/Pda.h b/include/Pda.h index fca4a4ec..a4db4788 100644 --- a/include/Pda.h +++ b/include/Pda.h @@ -9,8 +9,6 @@ #include "PdaCallback.h" -/// \class Pda -/// \brief Photon Distribution Analysis class for computing histograms. class Pda { private: @@ -50,25 +48,17 @@ class Pda { public: - /*! - * \brief Computes the S1S2 histogram. - * - * This function computes the S1S2 histogram based on the specified parameters, - * such as the maximum and minimum number of photons, background levels, and - * the probability distribution. - */ + /// Computes the S1S2 histogram void evaluate(); /*! - * \brief Constructor for creating a new Pda object. + * Constructor creating a new Pda object * - * Initializes a Pda object for computing Photon Distribution Analysis histograms. + * A Pda object can be used to compute Photon Distribution Analysis + * histograms. * - * @param hist2d_nmax The maximum number of photons. - * @param hist2d_nmin The minimum number of photons considered. - * @param background_ch1 Background level in the first channel (green channel). - * @param background_ch2 Background level in the second channel (red channel). - * @param pF Probability distribution of having a certain number of photons. + * @param hist2d_nmax the maximum number of photons + * @param hist2d_nmin the minimum number of photons considered */ Pda( int hist2d_nmax=300, @@ -88,14 +78,14 @@ class Pda { ~Pda() = default; /*! - * \brief Appends a species to the Pda object. + * Appends a species. * - * A species is defined by the amplitude (fraction) and the probability - * of detecting a photon in the first detection channel. + * A species is defined by the probability of detecting a photon in the + * first detection channel. * - * @param amplitude The amplitude (fraction) of the species. - * @param probability_ch1 The probability of detecting the species in the - * first detection channel. + * @param amplitude the amplitude (fraction) of the species + * @param probability_ch1 the probability of detecting the species in the + * first detection channel */ void append(double amplitude, double probability_ch1) { _is_valid_sgsr = false; @@ -103,9 +93,7 @@ class Pda { _probability_ch1.push_back(probability_ch1); } - /*! - * \brief Clears the model and removes all species from the Pda object. - */ + /// Clears the model and removes all species void clear_probability_ch1() { _is_valid_sgsr = false; _amplitudes.clear(); @@ -113,10 +101,10 @@ class Pda { } /*! - * \brief Returns the amplitudes of the species. + * Returns the amplitudes of the species * - * @param output_view[out] A C type array containing the amplitude of the species. - * @param n_output[out] The number of species. + * @param output[out] A C type array containing the amplitude of the species + * @param n_output[out] The number of species */ void get_amplitudes(double **output_view, int *n_output) { *n_output = _amplitudes.size(); @@ -124,10 +112,10 @@ class Pda { } /*! - * \brief Sets the amplitudes of the species. + * Sets the amplitudes of the species. * - * @param input[in] A C type array that contains the amplitude of the species. - * @param n_input[in] The number of species. + * @param input[in] A C type array that contains the amplitude of the species + * @param n_input[in] The number of species */ void set_amplitudes(double *input, int n_input) { _amplitudes.clear(); @@ -137,13 +125,13 @@ class Pda { } /*! - * \brief Set the callback (cb) for the computation of a 1D histogram. + * Set the callback (cb) for the computation of a 1D histogram. * - * The cb function reduces two-dimensional values, i.e., the intensity in - * channel (ch1) and ch2, to a one-dimensional number. The cb is used to + * The cb function recudes two dimensional values, i.e., the intensity in + * channel (ch1) and ch2 to a one dimensional number. The cb is used to * compute either FRET efficiencies, etc. * - * @param cb[in] Object that computes the value on a 1D histogram. + * @param callback[in] object that computes the value on a 1D histogram. */ void set_callback(PdaCallback* cb){ _histogram_function = cb; @@ -193,10 +181,9 @@ class Pda { } /*! - * \brief Returns the amplitudes of the species. - * - * @param output_view[out] A C type array containing the amplitude of the species. - * @param n_output[out] The number of species. + * Returns the amplitudes of the species + * @param output[out] A C type array containing the amplitude of the species + * @param n_output[out] The number of species */ void get_probabilities_ch1(double **output_view, int *n_output) { *n_output = _probability_ch1.size(); @@ -204,11 +191,11 @@ class Pda { } /*! - * \brief Sets the theoretical probabilities for detecting a species in the + * Sets the theoretical probabilities for detecting a the species in the * first channel. * - * @param input[in] A C type array that contains the probabilities of the species. - * @param n_input[in] The number of species. + * @param input[in] A C type array that contains the probabilities of the species + * @param n_input[in] The number of species */ void set_probabilities_ch1(double *input, int n_input) { _probability_ch1.clear(); @@ -219,14 +206,14 @@ class Pda { /*! - * \brief Get the theoretical probability spectrum of detecting a photon in the - * first channel. + * Get the theoretical probability spectrum of detecting a photon in the + * first channel * * The probability spectrum is an interleaved array of the amplitudes and - * the probabilities of detecting a photon in the first channel. + * the probabilities of detecting a photon in the first channel * - * @param output[out] Array containing the probability spectrum. - * @param n_output[out] Number of elements in the output array. + * @param output[out] array containing the probability spectrum + * @param n_output[out] number of elements in the output array */ void get_probability_spectrum_ch1(double** output, int* n_output) { int n = (int)_amplitudes.size() * 2; @@ -240,10 +227,10 @@ class Pda { } /*! - * \brief Set the probability P(F). + * Set the probability P(F) * - * @param input[in] A C type array containing the probability P(F). - * @param n_input[in] The number of elements in the input array. + * @param input[in] + * @param n_input[in] */ void setPF(double *input, int n_input){ #ifdef VERBOSE_TTTRLIB @@ -253,45 +240,39 @@ class Pda { pF.assign(input, input + n_input); } - /*! - * \brief Get the probability P(F). - * - * @param output_view[out] A C type array containing the probability P(F). - * @param n_output[out] The number of elements in the output array. - */ + /// Set the probability P(F) void getPF(double** output_view, int* n_output){ *n_output = pF.size(); *output_view = pF.data(); } /*! - * \brief Computes a 1D histogram from the 2D counting array of the two channels. - * - * This method calculates a 1D histogram based on the 2D counting array of the - * two channels. - * - * @param histogram_x[out] Histogram X-axis. - * @param n_histogram_x[out] Dimension of the X-axis. - * @param histogram_y[out] Array containing the computed histogram. - * @param n_histogram_y[out] Dimension of the histogram. - * @param x_max[in] Maximum x-value of the histogram. - * @param x_min[in] Minimum x-value of the histogram. - * @param n_bins[in] Number of histogram bins. - * @param log_x[in] If set to true (default is true), x-axis values are - * logarithmically spaced; otherwise, linear spacing. - * @param s1s2[in] Optional input for the S1S2 matrix. If nullptr (default), the - * Pda object's S1S2 matrix is used for computation. If not nullptr and both - * n_histogram_x and n_histogram_y > 0, this input is used as the S1S2 matrix. - * Input matrix must be quadratic. - * @param n_min[in] Minimum number of photons in the histogram. If -1 (default), - * the number set when the Pda object was instantiated is used. - * @param skip_zero_photon[in] When true, only s1s2 matrix elements i,j (i>0 and - * j>0) are considered. - * @param amplitudes[in] Species amplitudes (optional). Updates the s1s2 matrix - * of the object. - * @param probabilities_ch1[in] Theoretical probabilities of detecting the - * species in channel 1 (optional). Updates the s1s2 matrix of the object. - */ + * Returns a one dimensional histogram of the 2D counting array of the + * two channels. + * + * @param histogram_x[out] histogram X axis + * @param n_histogram_x[out] dimension of the x-axis + * @param histogram_y[out] array containing the computed histogram + * @param n_histogram_y[out] dimension of the histogram + * @param x_max[in] maximum x value of the histogram + * @param x_min[in] minimum x value of the histogram + * @param nbins[int] number of histogram bins + * @param log_x[in] If set to true (default is true) the values on the + * x-axis are logarithmically spaced otherwise they have a linear spacing. + * @param s1s2[in] Optional input for the S1S2 matrix. If this is set + * to a nullptr (default) the S1S2 matrix of the Pda object is used to + * compute the 1D histogram. If this is not set to nullptr and both dimensions + * set by n_input1 and n_input2 are larger than zero. The input is used as + * S1S2 matrix. The input matrix must be quadratic. + * @param n_min[in] Minimum number of photons in the histogram. If set to -1 + * the number set when the Pda object was instancitated is used. + * @param skip_zero_photon[in] When this option is set to true only elements + * of the s1s2 matrix i,j (i>0 and j>0) are considered. + * @param amplitudes[in] The species amplitudes (optional). This updates the + * s1s2 matrix of the object. + * @param probabilities_ch1[in] The theoretical probabilities of detecting the + * species in channel 1(optional)This updates the s1s2 matrix of the object. + */ void get_1dhistogram( double **histogram_x, int *n_histogram_x, double **histogram_y, int *n_histogram_y, @@ -305,30 +286,25 @@ class Pda { ); /*! - * \brief Computes experimental histograms. * - * This static method computes experimental histograms based on the provided TTTR data. - * - * @param tttr_data[in] TTTR data input. - * @param s1s2[out] Output S1S2 matrix. - * @param dim1[out] Output dimension 1 of the S1S2 matrix. - * @param dim2[out] Output dimension 2 of the S1S2 matrix. - * @param ps[out] Output PS matrix. - * @param dim_ps[out] Output dimension of the PS matrix. - * @param tttr_indices[out] Output TTTR indices. - * @param n_tttr_indices[out] Output number of TTTR indices. - * @param channels_1[in] Routing channel numbers used for the first channel in - * the S1S2 matrix. Photons with this channel number are counted and increment + * @param tttr_data[in] + * @param s1s2[out] + * @param dim1[out] + * @param dim2[out] + * @param ps[out] + * @param dim_ps[out] + * @param channels_1 routing channel numbers that are used for the first channel + * in the S1S2 matrix. Photons with this channel number are counted and increment * values in the S1S2 matrix. - * @param channels_2[in] Routing channel numbers used for the second channel in - * the S1S2 matrix. Photons with this channel number are counted and increment + * @param channels_2 routing channel numbers that are used for the second channel + * in the S1S2 matrix.Photons with this channel number are counted and increment * values in the S1S2 matrix. - * @param maximum_number_of_photons[in] Maximum number of photons in the computed - * S1S2 matrix. - * @param minimum_number_of_photons[in] Minimum number of photons in a time window - * and in the S1S2 matrix. - * @param minimum_time_window_length[in] Minimum length of a time window in - * milliseconds. + * @param maximum_number_of_photons The maximum number of photons in the computed + * S1S2 matrix + * @param minimum_number_of_photons The minimum number of photons in a time window + * and in the S1S2 matrix + * @param minimum_time_window_length The minimum length of a time windows in + * units of milli seconds. */ static void compute_experimental_histograms( TTTR* tttr_data, @@ -343,17 +319,15 @@ class Pda { ); /*! - * \brief Calculates p(G,R) for several ratios using the same P(F). - * - * This static method calculates p(G,R) for several ratios using the same P(F). - * - * @param S1S2[in] See sgsr_pN. - * @param pF[in] Input P(F). - * @param Nmax[in] Maximum number of photons. - * @param background_ch1[in] Background in the green channel. - * @param background_ch2[in] Background in the red channel. - * @param p_ch1[in] Input probabilities for channel 1. - * @param amplitudes[in] Corresponding amplitudes. + * calculating p(G,R), several ratios using the same same P(F) + * + * @param S1S2[] see sgsr_pN + * @param pF[in] input: p(F) + * @param Nmax[in] + * @param background_ch1[in] + * @param background_ch2[in] + * @param p_ch1[in] + * @param amplitudes[in] corresponding amplitudes */ static void S1S2_pF( std::vector &S1S2, @@ -366,17 +340,14 @@ class Pda { ); /*! - * \brief Convolves the fluorescence matrix F1F2 with the background - * to yield the signal matrix S1S2. - * - * This static method convolves the fluorescence matrix F1F2 with the background - * to produce the signal matrix S1S2. - * - * @param S1S2[out] Output signal matrix. - * @param F1F2[in] Input fluorescence matrix. - * @param Nmax Maximum number of photons. - * @param background_ch1 Background in the green channel. - * @param background_ch2 Background in the red channel. + * Convolves the Fluorescence matrix F1F2 with the background + * to yield the signal matrix S1S2 + * + * @param S1S2[out] + * @param F1F2[in] + * @param Nmax + * @param background_ch1 + * @param background_ch2 */ static void conv_pF( std::vector &S1S2, @@ -387,17 +358,13 @@ class Pda { ); /*! - * \brief Writes a Poisson distribution with an average lam for 0..N - * into a vector starting at a specified index. - * - * This static method generates a Poisson distribution with an average lam - * for values 0 to N and writes it into the vector starting at the specified index. - * - * @param return_p[in,out] Vector to store the Poisson distribution. - * @param start_idx Starting index in the vector. - * @param lam Average lambda for the Poisson distribution. - * @param return_dim Dimension of the vector. - */ + * Writes a Poisson distribution with an average lam, for 0..N + * into a vector starting at a specified index. + * + * @param return_p[in,out] + * @param lam[in] + * @param return_dim[in] + */ static void poisson_0toN( std::vector &return_p, int start_idx, @@ -406,27 +373,18 @@ class Pda { ); - /*! - * \brief Get the maximum number of photons in the S1S2 matrix. - * - * This method returns the maximum number of photons that the S1S2 matrix can - * accommodate. - * - * @return The maximum number of photons in the S1S2 matrix. - */ + /// The maximum number of photons in the SgSr matrix unsigned int get_max_number_of_photons() const{ return _n_2d_max; } /*! - * \brief Set the maximum number of photons in the S1S2 matrix. + * Set the maximum number of photons in the S1S2 matrix * - * This method sets the maximum number of photons that the S1S2 matrix can - * accommodate. It also resizes the internal S1S2 matrix accordingly. + * Note: the size of the pF array must agree with the maximum number + * of photons! * - * Note: The size of the pF array must agree with the maximum number of photons. - * - * @param nmax[in] The maximum number of photons. + * @param nmax[in] the maximum number of photons */ void set_max_number_of_photons(unsigned int nmax){ _n_2d_max = nmax; @@ -434,99 +392,47 @@ class Pda { _is_valid_sgsr = false; } - /*! - * \brief Get the minimum number of photons in the S1S2 matrix. - * - * This method retrieves the minimum number of photons that the S1S2 matrix can - * have. - * - * @return The minimum number of photons. - */ + /// The minimum number of photons in the SgSr matrix unsigned int get_min_number_of_photons() const{ return this->_n_2d_min; } - /*! - * \brief Set the minimum number of photons in the S1S2 matrix. - * - * This method sets the minimum number of photons that the S1S2 matrix can have. - * It also invalidates the current S1S2 matrix to ensure it is recomputed with - * the new minimum number of photons. - * - * @param nmin The minimum number of photons to set. - */ + /// Set the minimum number of photons in the SgSr matrix void set_min_number_of_photons(unsigned int nmin){ this->_n_2d_min = nmin; _is_valid_sgsr = false; } - /*! - * \brief Get the background in the green channel. - * - * This method returns the background value in the green channel. - * - * @return The background value in the green channel. - */ + /// Get the background in the green channel double get_ch1_background() const{ return _bg_ch1; } - /*! - * \brief Set the background in the first channel. - * - * This method sets the background value in the green channel. - * - * @param bg The background value to be set in the green channel. - */ + /// Set the background in the green channel void set_ch1_background(double bg){ _is_valid_sgsr = false; _bg_ch1 = bg; } - /*! - * \brief Get the background in the second channel. - * - * This method returns the background value in the second channel. - * - * @return The background value in the second channel. - */ + /// Get the background in the red channel double get_ch2_background() const{ return _bg_ch2; } - /*! - * \brief Set the background in the second channel. - * - * This method sets the background value in the second channel. - * - * @param br The background value to be set. - */ + /// Set the background in the red channel void set_ch2_background(double br) { _bg_ch2 = br; _is_valid_sgsr = false; } - /*! - * \brief Check if the S1S2 histogram is valid. - * - * This method returns true if the S1S2 histogram is considered valid, - * meaning that it provides correct output for the given input parameters. - * The validity is set to true after calling the evaluate method. - * - * @return True if the S1S2 histogram is valid, false otherwise. - */ + /// Returns true if the + /// SgSr histogram is valid, i.e., if output is correct + /// for the input parameter. This value is set to true by evaluate. bool is_valid_sgsr() const{ return _is_valid_sgsr; } - /*! - * \brief Set the S1S2 histogram validity (for testing purposes). - * - * This method allows setting the validity of the S1S2 histogram explicitly, - * primarily intended for testing purposes. - * - * @param v[in] True to set the S1S2 histogram as valid, false otherwise. - */ + /// Set the SgSr histogram to valid (only used for testing) void set_valid_sgsr(bool v){ _is_valid_sgsr = v; } diff --git a/include/TTTR.h b/include/TTTR.h index 4ca4fdd3..740a3dc0 100644 --- a/include/TTTR.h +++ b/include/TTTR.h @@ -70,57 +70,47 @@ void selection_by_count_rate( /*! - * \brief Returns time windows (tw), i.e., the start and stop indices for a - * minimum tw size and a minimum number of photons in a tw. - * - * @param output [out] Array containing the interleaved start and stop indices - * of the time windows in the TTTR object. - * @param n_output [out] Length of the output array. - * @param input [in] Array containing the macro times. - * @param n_input [in] Number of macro times. - * @param minimum_window_length [in] Minimum length of a time window (mandatory). - * @param maximum_window_length [in] Maximum length of a time window (optional). - * @param minimum_number_of_photons_in_time_window [in] Minimum number of - * photons a selected time window must contain (optional). - * @param maximum_number_of_photons_in_time_window [in] Maximum number of - * photons a selected time window can contain (optional). - * @param macro_time_calibration [in] Calibration factor for macro times (default is 1.0). - * @param invert [in] If set to true, the selection criteria are inverted. - */ +* @brief Returns time windows (tw), i.e., the start and the stop indices for a +* minimum tw size, a minimum number of photons in a tw. +* +* @param output [out] Array containing the interleaved start and stop indices +* of the tws in the TTTR object. +* @param n_output [out] Length of the output array +* @param input [in] Array containing the macro times +* @param n_input [in] Number of macro times +* @param minimum_window_length [in] Minimum length of a tw (mandatory). +* @param maximum_window_length [in] Maximum length of a tw (optional). +* @param minimum_number_of_photons_in_time_window [in] Minimum number of +* photons a selected tw contains (optional) +* @param maximum_number_of_photons_in_time_window [in] Maximum number of +* photons a selected tw contains (optional) +* @param invert [in] If set to true, the selection criteria are inverted. +*/ 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 + 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 ); /*! - * \brief Computes the intensity trace for a sequence of time events. + * Computes a intensity trace for a sequence of time events * - * The intensity trace is calculated by partitioning the time events into - * time windows with a minimum specified length and counting the number - * of photons in each window. + * The intensity trace is computed by splitting the trace of time events into + * time windows (tws) with a minimum specified length and counts the number + * of photons in each tw. * - * \param output Pointer to an array storing the number of photons in each time window. - * \param n_output Pointer to the variable storing the number of time windows. - * \param input Array of time points representing the time events. - * \param n_input Number of time points in the input array. - * \param time_window_length Size of the time window in units of the macro time resolution. - * \param macro_time_resolution The resolution of the macro time clock (default is 1.0). - * - * The function calculates the intensity trace by dividing the time events into - * non-overlapping time windows of the specified length. The output array holds - * the count of photons in each time window, and n_output is updated accordingly. - * The input array contains the time points of events, and n_input is the total - * number of events. The time_window_length parameter defines the size of the - * time windows, and macro_time_resolution specifies the resolution of the macro - * time clock (default is 1.0). The calculated intensity trace is stored in the - * output array, and the total number of time windows is updated in n_output. + * @param output number of photons in each time window + * @param n_output number of time windows + * @param input array of time points + * @param n_input number number of time points + * @param time_window_length time window size in units of the macro time resolution + * @param macro_time_resolution the resolution of the macro time clock */ void compute_intensity_trace( int **output, int *n_output, @@ -130,68 +120,33 @@ void compute_intensity_trace( ); -/*! - * \brief Extracts a subarray of valid events from the input array. - * - * This function takes an array of type T, representing events, and extracts - * a subarray containing the first `n_valid_events` elements. The size of the - * output array is updated in `n_out`. Memory is allocated for the output array, - * and the caller is responsible for freeing this memory when it is no longer needed. - * - * \tparam T The data type of the array elements. - * \param n_valid_events Number of valid events to extract. - * \param array Pointer to the input array containing events of type T. - * \param[out] out Pointer to the output array holding the extracted subarray. - * \param[out] n_out Pointer to the variable storing the size of the output array. - * - * The function allocates memory for the output array and copies the first - * `n_valid_events` elements from the input array. The size of the output array - * is updated in `n_out`. It is the responsibility of the caller to free the - * allocated memory using `free(*out)` when the output array is no longer needed. - */ + +// Seems unused +// * Get the ranges in for a specific channel number +// * +// * @param[out] ranges +// * @param[out] n_range +// * @param[in] channel +// * @param[in] n_channel +// * @param[in] channel +// */ +//void get_ranges_channel( +// unsigned int **ranges, int *n_range, +// short *channel, int n_channel, +// int selection_channel +//); +// + + template -inline void get_array( - size_t n_valid_events, ///< [in] Number of valid events to extract. - T *array, ///< [in] Pointer to the input array containing events of type T. - T **out, ///< [out] Pointer to the output array holding the extracted subarray. - int *n_out ///< [out] Pointer to the variable storing the size of the output array. -) { - *n_out = static_cast(n_valid_events); - *out = static_cast(malloc(sizeof(T) * n_valid_events)); - - for (size_t i = 0; i < n_valid_events; ++i) { - (*out)[i] = array[i]; - } +inline void get_array(size_t n_valid_events, T *array, T **out, int *n_out){ + *n_out = (int) n_valid_events; + (*out) = (T*) malloc(sizeof(T) * n_valid_events); + for(size_t i=0; i{ friend class CLSMImage; @@ -230,8 +185,7 @@ class TTTR : public std::enable_shared_from_this{ {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} + {BH_RECORD_TYPE_SPC130, ProcessSPC130} }; /*! @@ -245,7 +199,6 @@ class TTTR : public std::enable_shared_from_this{ * * BH_SPC600_256_CONTAINER 3 * * BH_SPC600_4096_CONTAINER 4 * * PHOTON_HDF5_CONTAINER 5 - * * CZ_CONFOCOR3_CONTAINER 6 * * The numbers correspond to the numbers that should be used when * initializing the class. @@ -306,462 +259,296 @@ class TTTR : public std::enable_shared_from_this{ /// the number of valid read records (excluded overflow and invalid records) size_t n_valid_events = 0; - /*! - * \brief Allocates memory for storing time-tagged records. - * - * This method allocates memory to store a specified number of time-tagged records. - * The number of records to be allocated is specified by the parameter `n_rec`. - * - * \param n_rec Number of records to allocate memory for. - * - * \note Call this method to allocate memory before storing time-tagged records. - * \warning Ensure to free the allocated memory when it is no longer needed. - * - * \see deallocate_memory_for_records - */ + /// allocates memory for the records. @param n_rec are the number of records. void allocate_memory_for_records(size_t n_rec); - /*! - * \brief Deallocates memory used for storing time-tagged records. - * - * This method frees the memory that was previously allocated for storing time-tagged records. - * Call this method when the memory is no longer needed to prevent memory leaks. - * - * \note Ensure to call this method only when the records are no longer in use. - * \see allocate_memory_for_records - */ + /// deallocate memory of records void deallocate_memory_of_records(); /*! - * \brief Reads the essential content from a Photon HDF file. + * Reads the content of a Photon HDF file. * - * Reads the micro time, macro time, and routing channel number from the specified Photon HDF file. - * This method only processes the fundamental data, excluding meta data. + * WARNING: Only the micro time, the macro time, and the routing channel + * number are read. The meta data is not proccessed. * - * \param fn Filename pointing to the Photon HDF file. - * \return Returns an integer indicating the success or failure of the file reading operation. + * @param fn filename pointing to the Photon HDF file + * @return */ int read_hdf_file(const char *fn); - /*! - * \brief Reads a specified number of records from the file. - * - * Reads 'n_rec' records from the file. If 'n_rec' is not specified, all records in the file - * are read. If 'rewind' is true (default behavior), the file is read from the beginning - * of the records until the end of the file or until 'n_rec' records have been read. If 'rewind' - * is false, the records are read from the current location of the file pointer until the end of the file. - * - * \param n_rec Number of records to read. If not specified, all records in the file are read. - * \param rewind If true (default), the file is read from the beginning; if false, reads from the current position. - * \param chunk The size of the chunk to read at a time. - */ + /// Reads n_records records of the file (n_records is the number of records) + /// @param n_rec is the number of records that are being read. If no number + /// of records to be read is specified all records in the file are being read. + /// If the parameter @param rewind is true (default behaviour) the file is read + /// from the beginning of the records till the end of the file or till n_red + /// records have been read. If @param rewind is false the records are being + /// read from the current location of the file pointer till the end of the file. void read_records(size_t n_rec, bool rewind, size_t chunk); - - /*! - * \brief Reads a specified number of records from the file. - * - * Reads 'n_rec' records from the file. If 'n_rec' is not specified, all records in the file - * are read. - * - * \param n_rec Number of records to read. If not specified, all records in the file are read. - */ void read_records(size_t n_rec); - - /*! - * \brief Reads records from the current file position to the end. - * - * Reads records from the current file position to the end of the file. - * No specific number of records is specified. - */ void read_records(); protected: /*! - * \brief Traverses the routing channel array and identifies used routing channel numbers. - * - * Traverses the routing channel array and populates the protected attribute - * used_routing_channels with the routing channel numbers that are in use. - */ + * Traverses the routing channel array and lists the used routing channel + * numbers in the protected attribute used_routing_channels. + */ void find_used_routing_channels(); - /// \brief A routing channel is a numeric identifier associated with each photon - /// in the time-tagged time-resolved (TTTR) data. It signifies the path - /// or channel through which the photon is detected or routed. + /// a vector containing the used routing channel numbers in the TTTR file std::vector used_routing_channels; public: - /// \brief Returns a shared pointer to the current instance of TTTR. - /// - /// This function is used to create a shared pointer to the current instance of - /// the TTTR class. It allows managing the ownership of the object using - /// shared pointers. - /// - /// \return A shared pointer to the current instance of TTTR. - std::shared_ptr Get() { return shared_from_this(); } + /// Make shared pointer + std::shared_ptr Get() {return shared_from_this();} /*! - * \brief Copies information from another TTTR object. - * - * This function allows copying information from another TTTR object, including - * optional components based on the specified parameters. - * - * @param p2 The TTTR object from which the information is copied. - * @param include_big_data If true, macro time, micro time, etc., are also copied. - * Otherwise, only essential information is copied. - */ + * Copy the information from another TTTR object + * + * @param p2 the TTTR object which which the information is copied from + * @param include_big_data if this is true also the macro time, micro time + * etc. are copied. Otherwise all other is copied + */ void copy_from(const TTTR &p2, bool include_big_data = true); /*! - * \brief Reads TTTR data from a file into the TTTR object. - * - * This function reads TTTR data from the specified file into the TTTR object. - * If the filename is not provided (default is nullptr), the filename attribute - * of the TTTR object is used. The container_type parameter specifies the type - * of container used in the file. - * - * @param fn The filename to read. If nullptr (default), the TTTR object's filename is used. - * @param container_type The container type. - * @return Returns 1 if the file is read without errors; otherwise, returns 0. - */ + * Reads the TTTR data contained in a file into the TTTR object + * + * @param fn The filename that is read. If fn is a nullptr (default value + * is nullptr) the filename attribute of the TTTR object is used as + * filename. + * + * @param container_type The container type. + * @return Returns 1 in case the file was read without errors. Otherwise 0 is returned. + */ int read_file(const char *fn = nullptr, int container_type = -1); /*! - * \brief Determines the number of records in a TTTR file (not for use with HDF5). - * - * Calculates the number of records in the file based on the file size. If the offset - * is passed, the number of records is calculated using the file size, offset, and - * bytes_per_record. If the offset is not specified, the current location of the file - * pointer is used. If bytes_per_record is not specified, the attribute value - * bytes_per_record of the class instance is used. - * - * @param fp The file pointer to the TTTR file. - * @param offset The offset for calculating the number of records. - * @param bytes_per_record The number of bytes per record. - * @return Returns the calculated number of records. - */ + * Determines the number of records in a TTTR files (not for use with HDF5) + * + * Calculates the number of records in the file based on the file size. + * if @param offset is passed the number of records is calculated by the file size + * the number of bytes in the file - offset and @param bytes_per_record. + * If @param offset is not specified the current location of the file pointer + * is used as an offset. If @param bytes_per_record is not specified + * the attribute value bytes_per_record of the class instance is used. + * + * @param offset + * @param bytes_per_record + */ static size_t get_number_of_records_by_file_size( - std::FILE *fp, - size_t offset, - size_t bytes_per_record + std::FILE *fp, + size_t offset, + size_t bytes_per_record ); - /*! - * \brief Appends events to the TTTR object. - * - * Appends events represented by macro_times, micro_times, routing_channels, - * and event_types to the TTTR object. The sizes of the input arrays - * (n_macrotimes, n_microtimes, n_routing_channels, n_event_types) must be equal. - * - * @param macro_times Array of macro time values. - * @param n_macrotimes Number of elements in the macro_times array. - * @param micro_times Array of micro time values. - * @param n_microtimes Number of elements in the micro_times array. - * @param routing_channels Array of routing channel values. - * @param n_routing_channels Number of elements in the routing_channels array. - * @param event_types Array of event type values. - * @param n_event_types Number of elements in the event_types array. - * @param shift_macro_time Flag indicating whether to shift macro times. - * @param macro_time_offset Offset applied to macro times if shift_macro_time is true. - */ 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 + 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 ); - /*! - * \brief Appends a single event to the TTTR object. - * - * Appends a single event represented by macro_time, micro_time, routing_channel, - * and event_type to the TTTR object. - * - * @param macro_time Macro time value for the event. - * @param micro_time Micro time value for the event. - * @param routing_channel Routing channel value for the event. - * @param event_type Event type value for the event. - * @param shift_macro_time Flag indicating whether to shift macro time. - * @param macro_time_offset Offset applied to macro time if shift_macro_time is true. - */ 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 + 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 ); - /*! - * \brief Appends events from another TTTR object to the current TTTR object. - * - * Appends events from another TTTR object (`other`) to the current TTTR object. - * Optionally shifts macro times and applies an offset to the macro times. - * - * @param other Pointer to the TTTR object containing events to append. - * @param shift_macro_time Flag indicating whether to shift macro times. - * @param macro_time_offset Offset applied to macro times if shift_macro_time is true. - */ void append( const TTTR *other, bool shift_macro_time=true, long long macro_time_offset=0 ); - /*! - * \brief Returns the number of valid events in the TTTR data. - * - * This function is a wrapper for the get_n_valid_events() method and returns - * the total number of valid events in the TTTR data. - * - * @return The number of valid events. - */ - size_t size() { - return get_n_valid_events(); - } + size_t size(){ + return get_n_valid_events(); + } - /*! - * \brief Retrieves the used routing channel numbers from the TTTR data. - * - * This function populates the provided output array with the routing channel - * numbers that are used in the TTTR file. The number of elements in the output - * array is stored in the n_output parameter. - * - * @param output Pointer to the output array to be populated. - * @param n_output Pointer to the number of elements in the output array. - */ - void get_used_routing_channels(signed char **output, int *n_output); + /*! + * Returns an array containing the routing channel numbers + * that are contained (used) in the TTTR file. + * + * @param output Pointer to the output array + * @param n_output Pointer to the number of elements in the output array + */ + void get_used_routing_channels(signed char **output, int *n_output); - /*! - * \brief Retrieves the macro times of valid TTTR events. - * - * This function populates the provided output array with the macro times - * of the valid TTTR events. The number of elements in the output array - * is stored in the n_output parameter. - * - * @param output Pointer to the output array to be populated. - * @param n_output Pointer to the number of elements in the output array. - */ - void get_macro_times(unsigned long long **output, int *n_output); + /*! + * Returns an array containing the macro times of the valid TTTR + * events. + * + * @param output Pointer to the output array + * @param n_output Pointer to the number of elements in the output array + */ + void get_macro_times(unsigned long long **output, int *n_output); - /*! - * \brief Retrieves the micro times of valid TTTR events. - * - * This function populates the provided output array with the micro times - * of the valid TTTR events. The number of elements in the output array - * is stored in the n_output parameter. - * - * @param output Pointer to the output array to be populated. - * @param n_output Pointer to the number of elements in the output array. - */ - void get_micro_times(unsigned short **output, int *n_output); + /*! + * Returns an array containing the micro times of the valid TTTR + * events. + * + * @param output Pointer to the output array + * @param n_output Pointer to the number of elements in the output array + */ + void get_micro_times(unsigned short **output, int *n_output); - /*! - * \brief Computes and returns an intensity trace for a specified integration window. - * - * The intensity trace is calculated based on the integration time windows, - * and the result is stored in the output array. The number of points in the - * intensity trace is returned through the n_output parameter. - * - * @param output Pointer to the array to store the intensity trace. - * @param n_output Pointer to the number of points in the intensity trace. - * @param time_window_length The length of the integration time windows in - * units of milliseconds. - */ - void get_intensity_trace(int **output, int *n_output, double time_window_length = 1.0); + /*! + * Returns a intensity trace that is computed for a specified integration + * window + * + * @param output the returned intensity trace + * @param n_output the number of points in the intensity trace + * @param time_window_length the length of the integration time windows in + * units of milliseconds. + */ + void get_intensity_trace(int **output, int *n_output, double time_window_length=1.0); - /*! - * \brief Returns an array containing the routing channel numbers of the valid TTTR events. - * - * The routing channel numbers are stored in the output array, and the number of - * elements in the array is returned through the n_output parameter. - * - * @param output Pointer to the array to store the routing channel numbers. - * @param n_output Pointer to the number of elements in the output array. - */ - void get_routing_channel(signed char** output, int* n_output); + /*! + * Returns an array containing the routing channel numbers of the + * valid TTTR events. + * + * @param output Pointer to the output array + * @param n_output Pointer to the number of elements in the output array + */ + void get_routing_channel(signed char** output, int* n_output); - /*! - * \brief Returns an array containing the event types of the valid TTTR events. - * - * The event types are stored in the output array, and the number of elements in - * the array is returned through the n_output parameter. - * - * @param output Pointer to the array to store the event types. - * @param n_output Pointer to the number of elements in the output array. - */ - void get_event_type(signed char** output, int* n_output); + /*! + * + * @param output Pointer to the output array + * @param n_output Pointer to the number of elements in the output array + */ + void get_event_type(signed char** output, int* n_output); - /*! - * \brief Returns the number of micro time channels that fit between two macro time clocks. - * - * This function calculates and returns the maximum valid number of micro time channels - * that fit between two macro time clocks. - * - * @return Maximum valid number of micro time channels. - */ - unsigned int get_number_of_micro_time_channels(); + /*! + * Returns the number of micro time channels that fit between two + * macro time clocks. + * + * @return maximum valid number of micro time channels + */ + unsigned int get_number_of_micro_time_channels(); - /*! - * \brief Returns the number of valid events in the TTTR file. - * - * This function retrieves and returns the total number of valid events present in - * the TTTR (Time-Tagged Time-Resolved) file. - * - * @return Number of valid events in the TTTR file. - */ - size_t get_n_valid_events(); + /*! + * @return number of valid events in the TTTR file + */ + size_t get_n_valid_events(); - /*! - * \brief Returns the container type used to open the TTTR file. - * - * This function retrieves and returns the container type that was used to open - * the TTTR (Time-Tagged Time-Resolved) file. - * - * @return Container type used to open the TTTR file. - */ - std::string get_tttr_container_type(){ + /*! + * @return the container type that was used to open the file + */ + std::string get_tttr_container_type(){ return tttr_container_type_str; } - /*! - * \brief Creates a new TTTR object by selecting specific events based on the provided indices. - * - * This function creates a new TTTR (Time-Tagged Time-Resolved) object by selecting specific events - * from the current TTTR object based on the provided indices. - * - * @param selection Pointer to an array containing the indices of selected events. - * @param n_selection Number of elements in the selection array. - * @return Shared pointer to the newly created TTTR object containing selected events. - */ - std::shared_ptr select(int *selection, int n_selection); + std::shared_ptr select(int *selection, int n_selection); - /*! - * \brief Default constructor for the TTTR (Time-Tagged Time-Resolved) class. - * - * This constructor initializes a TTTR object with default values. + /*! Constructor */ TTTR(); - /*! - * \brief Copy constructor for the TTTR (Time-Tagged Time-Resolved) class. - * - * This constructor creates a new TTTR object by copying the information from another TTTR object. - * - * @param p2 The TTTR object from which the information is copied. - */ + /// Copy constructor TTTR(const TTTR &p2); - /*! - * Constructor that can read a file. - * - * @param filename TTTR filename. - * @param container_type Container type as int: - * - 0: PicoQuant PTU Container (PQ_PTU_CONTAINER) - * - 1: PicoQuant HT3 Container (PQ_HT3_CONTAINER) - * - 2: Becker & Hickl SPC-130 Container (BH_SPC130_CONTAINER) - * - 3: Becker & Hickl SPC-600 with 256 channels Container (BH_SPC600_256_CONTAINER) - * - 4: Becker & Hickl SPC-600 with 4096 channels Container (BH_SPC600_4096_CONTAINER) - * - 5: Photon-HDF5 Container (PHOTON_HDF5_CONTAINER) - * - 6: Carl Zeiss ConfoCor3 (CZ_CONFOCOR3_CONTAINER) - * @param read_input If true, reads the content of the file. - */ + /*! + * Constructor that can read a file + * + * @param filename TTTR filename + * @param container_type container type as int (0 = PTU; 1 = HT3; + * 2 = SPC-130; 3 = SPC-600_256; 4 = SPC-600_4096; 5 = PHOTON-HDF5) + * @param read_input if true reads the content of the file + * + * PQ_PTU_CONTAINER 0 + * PQ_HT3_CONTAINER 1 + * BH_SPC130_CONTAINER 2 + * BH_SPC600_256_CONTAINER 3 + * BH_SPC600_4096_CONTAINER 4 + */ TTTR(const char *filename, int container_type, bool read_input); /*! - * Constructor for TTTR object that reads the content of the file. * - * @param filename TTTR filename. - * @param container_type Container type as int: - * - 0: PicoQuant PTU Container (PQ_PTU_CONTAINER) - * - 1: PicoQuant HT3 Container (PQ_HT3_CONTAINER) - * - 2: Becker & Hickl SPC-130 Container (BH_SPC130_CONTAINER) - * - 3: Becker & Hickl SPC-600 with 256 channels Container (BH_SPC600_256_CONTAINER) - * - 4: Becker & Hickl SPC-600 with 4096 channels Container (BH_SPC600_4096_CONTAINER) - * - 5: Photon-HDF5 Container (PHOTON_HDF5_CONTAINER) - * - 6: Carl Zeiss ConfoCor3 (CZ_CONFOCOR3_CONTAINER) + * @param filename TTTR filename + * @param container_type container type as int (0 = PTU; 1 = HT3; + * 2 = SPC-130; 3 = SPC-600_256; 4 = SPC-600_4096; 5 = PHOTON-HDF5) */ TTTR(const char *filename, int container_type); /*! - * Constructor for TTTR object. * - * @param filename TTTR filename. - * @param container_type Container type as string: - * - "PTU": PicoQuant PTU Container - * - "HT3": PicoQuant HT3 Container - * - "SPC-130": Becker & Hickl SPC-130 Container - * - "SPC-600_256": Becker & Hickl SPC-600 with 256 channels Container - * - "SPC-600_4096": Becker & Hickl SPC-600 with 4096 channels Container - * - "PHOTON-HDF5": Photon-HDF5 Container - * - "CZ_CONFOCOR3_CONTAINER": Carl Zeiss ConfoCor3 Container + * @param filename TTTR filename + * @param container_type container type as string (PTU; HT3; + * SPC-130; SPC-600_256; SPC-600_4096; PHOTON-HDF5) */ TTTR(const char *filename, const char* container_type); - /*! - * Constructor for TTTR object using arrays of TTTR events. - * - * If arrays of different sizes are used to initialize a TTTR object, - * the shortest array among all provided arrays is used to construct the TTTR object. - * - * @param macro_times Array containing the macro times. - * @param n_macrotimes Number of macro times. - * @param micro_times Array containing the microtimes. - * @param n_microtimes Length of the micro time array. - * @param routing_channels Routing channel array. - * @param n_routing_channels Length of the routing channel array. - * @param event_types Array of event types. - * @param n_event_types Number of elements in the event type array. - * @param find_used_channels If set to true (default), searches all indices to find the used routing channels. - */ - 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 - ); - - /*! - * Constructor for creating a new TTTR object containing records specified in the selection array. - * - * The selection array is an array of indices. The events with indices - * in the selection array are copied in the order of the selection array - * to a new TTTR object. - * - * @param parent Parent TTTR object from which to select records. - * @param selection Array of indices specifying the selected records. - * @param n_selection Number of elements in the selection array. - * @param find_used_channels If set to true (default), searches all indices to find the used routing channels. - */ - TTTR(const TTTR &parent, - int *selection, int n_selection, - bool find_used_channels = true); /*! - * Destructor for TTTR class. - * Releases any allocated resources and cleans up the TTTR object. + * Constructor of TTTR object using arrays of the TTTR events + * + * If arrays of different size are used to initialize a TTTR object + * the shortest array of all provided arrays is used to construct the + * TTTR object. + * + * @param macro_times input array containing the macro times + * @param n_macrotimes number of macro times + * @param micro_times input array containing the microtimes + * @param n_microtimes length of the of micro time array + * @param routing_channels routing channel array + * @param n_routing_channels length of the routing channel array + * @param event_types array of event types + * @param n_event_types number of elements in the event type array + * @param find_used_channels if set to true (default) searches all indices + * to find the used routing channels */ - ~TTTR(); + 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 + ); /*! - * Getter for the filename of the TTTR file. + * This constructor can be used to create a new TTTR object that only + * contains records that are specified in the selection array. * - * @return The filename of the TTTR file. + * The selection array is an array of indices. The events with indices + * in the selection array are copied in the order of the selection array + * to a new TTTR object. + * + * @param parent + * @param selection + * @param n_selection + * @param find_used_channels if set to true (default) searches all indices + * to find the used routing channels + * + */ + TTTR(const TTTR &parent, + int *selection, int n_selection, + bool find_used_channels = true); + + /// Destructor + ~TTTR(); + + /*!getFilename + * Getter for the filename of the TTTR file + * + * @return The filename of the TTTR file */ std::string get_filename(); /*! - * Get a pointer to a TTTR object that is based on a selection on the current + * Get a ptr to a TTTR object that is based on a selection on the current * TTTR object. A selection is an array of indices of the TTTR events. * - * @param selection Array of indices of TTTR events. - * @param n_selection Number of elements in the selection array. - * @return A shared pointer to a new TTTR object based on the specified selection. + * @param selection + * @param n_selection + * @return */ std::shared_ptr get_tttr_by_selection(int *selection, int n_selection){ auto p = std::make_shared(*this, selection, n_selection, true); @@ -769,23 +556,20 @@ class TTTR : public std::enable_shared_from_this{ } /*! - * @brief Returns time windows (tw), i.e., the start and the stop indices for a - * minimum tw size, a minimum number of photons in a tw. - * - * @param output [out] Array containing the interleaved start and stop indices - * of the tws in the TTTR object. - * @param n_output [out] Length of the output array - * @param minimum_window_length [in] Minimum length of a tw (mandatory). - * @param maximum_window_length [in] Maximum length of a tw (optional). - * @param minimum_number_of_photons_in_time_window [in] Minimum number of - * photons a selected tw contains (optional) - * @param maximum_number_of_photons_in_time_window [in] Maximum number of - * photons a selected tw contains (optional) - * @param macro_time_calibration [in] Macro time calibration in units of the - * macro time resolution. If negative, the macro time resolution from the TTTR - * header is used. - * @param invert [in] If set to true, the selection criteria are inverted. - */ + * @brief Returns time windows (tw), i.e., the start and the stop indices for a + * minimum tw size, a minimum number of photons in a tw. + * + * @param output [out] Array containing the interleaved start and stop indices + * of the tws in the TTTR object. + * @param n_output [out] Length of the output array + * @param minimum_window_length [in] Minimum length of a tw (mandatory). + * @param maximum_window_length [in] Maximum length of a tw (optional). + * @param minimum_number_of_photons_in_time_window [in] Minimum number of + * photons a selected tw contains (optional) + * @param maximum_number_of_photons_in_time_window [in] Maximum number of + * photons a selected tw contains (optional) + * @param invert [in] If set to true, the selection criteria are inverted. + */ void get_ranges_by_time_window( int **output, int *n_output, double minimum_window_length, @@ -810,73 +594,51 @@ class TTTR : public std::enable_shared_from_this{ ); } - /*! - * @brief Get events indices by the routing channel number - * - * This method retrieves an array containing the event/ photon indices - * of events with routing channel numbers found in the selection input array. - * - * @param output [out] Indices of the selected events - * @param n_output [out] Number of selected events - * @param input [in] Routing channel numbers for selecting events - * @param n_input [in] Number of routing channels for selection - */ - void get_selection_by_channel( - int **output, int *n_output, - signed char *input, int n_input - ); - - /*! - * @brief Get a TTTR object based on a selection by routing channel numbers - * - * This method creates and returns a shared pointer to a TTTR object that - * contains only the events with routing channel numbers specified in the input array. - * - * @param input [in] Routing channel numbers for selecting events - * @param n_input [in] Number of routing channels for selection - * @return Shared pointer to the new TTTR object based on the specified selection - */ - std::shared_ptr 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); - } - - /*! - * @brief Get indices where the count rate is below a specified maximum + /*! + * Get events indices by the routing channel number * - * This method returns an array of indices where the count rate, calculated - * within a sliding time window, is below a specified maximum. + * This returns an array that contains the event / photon indices + * of events with routing channel numbers that are found in the selection + * input array. * - * @param output [out] Array containing the selected indices - * @param n_output [out] Number of elements in the output array - * @param time_window [in] Length of the time window in milliseconds - * @param n_ph_max [in] Maximum number of photons within a time window - * @param invert [in] If set to true, the selection criteria are inverted - * @param make_mask [in] If set to true, the output array will be a boolean mask + * @param output indices of the events + * @param n_output number of selected events + * @param input routing channel number for selection of events + * @param n_input number of routing channels for selection of events */ - 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 - ); + void get_selection_by_channel( + int **output, int *n_output, + signed char *input, int n_input + ); + std::shared_ptr 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); + } - /*! - * @brief Get a TTTR object filtered by count rate criteria - * - * This method returns a TTTR object filtered based on count rate criteria. - * - * @param time_window [in] Length of the time window in milliseconds - * @param n_ph_max [in] Maximum number of photons within a time window - * @param invert [in] If set to true, the count rate criteria are inverted - * @param make_mask [in] If set to true, the output array will be a boolean mask - * @return A shared pointer to the filtered TTTR object - */ - std::shared_ptr get_tttr_by_count_rate( - double time_window, int n_ph_max, - bool invert=false, bool make_mask=false - ){ + /*! + * List of indices where the count rate is smaller than a maximum count + * rate + * + * The count rate is specified by providing a time window that slides over + * the time array and the maximum number of photons within the time window. + * + * @param output the output array that will contain the selected indices + * @param n_output the number of elements in the output array + * @param time_window the length of the time window in milliseconds + * @param n_ph_max the maximum number of photons within a time window + */ + 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 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, @@ -885,265 +647,192 @@ class TTTR : public std::enable_shared_from_this{ return get_tttr_by_selection(sel, nsel); } - /*! - * @brief Get time windows (tw) based on specified criteria - * - * Returns time windows (tw), i.e., the start and stop indices for a minimum tw size, - * a minimum number of photons in a tw. - * - * @param output[out] Array containing the interleaved start and stop indices - * of the tws in the TTTR object. - * @param n_output[out] Length of the output array - * @param minimum_window_length[in] Minimum length of a tw in units of ms (mandatory). - * @param minimum_number_of_photons_in_time_window[in] Minimum number of - * photons a selected tw contains (optional) in units of seconds - * @param maximum_number_of_photons_in_time_window[in] Maximum number of - * photons a selected tw contains (optional) - * @param maximum_window_length[in] Maximum length of a tw (optional). - * @param macro_time_calibration[in] Macro time calibration in units of seconds. - * If negative, the macro time resolution from the header is used. - * @param invert[in] If set to true, the selection criteria are inverted. - */ - 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 - ); - /*! - * @brief Get the header as a map of strings. - * - * @return Pointer to the TTTRHeader object representing the header information. - * If no header is present, returns nullptr. - */ - TTTRHeader* get_header(); + * Returns time windows (tw), i.e., the start and the stop indices for a + * minimum tw size, a minimum number of photons in a tw. + * + * @param output[out] Array containing the interleaved start and stop indices + * of the tws in the TTTR object. + * @param n_output[out] Length of the output array + * @param minimum_window_length[in] Minimum length of a tw in units of ms (mandatory). + * @param maximum_window_length[in] Maximum length of a tw (optional). + * @param minimum_number_of_photons_in_time_window[in] Minimum number of + * photons a selected tw contains (optional) in units of seconds + * @param maximum_number_of_photons_in_time_window[in] Maximum number of + * photons a selected tw contains (optional) + * @param invert[in] If set to true, the selection criteria are inverted. + */ + 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 + ); - /*! - * @brief Set the header for the TTTR object. - * - * @param v Pointer to the TTTRHeader object containing the header information. - */ - void set_header(TTTRHeader* v); + /// Get header returns the header (if present) as a map of strings. + TTTRHeader* get_header(); - /*! - * @brief Returns the number of events in the TTTR file, or the number of selected events if a selection is applied. - * - * @return Number of events in the TTTR file or the number of selected events. - */ - size_t get_n_events(); + /// Set header + void set_header(TTTRHeader* v); /*! - * @brief Writes the contents of an opened TTTR file to a new TTTR file. - * - * @param filename The filename for the new TTTR file. - * @param header Optional TTTRHeader to be written. If set to nullptr, no header is written (default is nullptr). - * @return True if the write operation is successful, false otherwise. + * Returns the number of events in the TTTR file for cases no selection + * is specified otherwise the number of selected events is returned. + * @return */ - bool write(std::string filename, TTTRHeader* header = nullptr); + size_t get_n_events(); /*! - * @brief Write events from the TTTR object to a file as SPC-132. - * - * @param fp The FILE pointer for the output file. - * @param tttr The TTTR object containing the events to be written. + * Write the contents of a opened TTTR file to a new + * TTTR file. + * + * @param fn filename + * @param container_type container type (PTU; HT3; + * SPC-130; SPC-600_256; SPC-600_4096; PHOTON-HDF5) + * @oaram write_a_header if set to false no header is written - Writing correct + * headers is not implemented. Therefore, the default value is false. + * @return */ + bool write(std::string filename, TTTRHeader* header = nullptr); + void write_spc132_events(FILE* fp, TTTR* tttr); - /*! - * @brief Write events from the TTTR object to a file as HHT3v2. - * - * @param fp The FILE pointer for the output file. - * @param tttr The TTTR object containing the events to be written. - */ void write_hht3v2_events(FILE* fp, TTTR* tttr); - /*! - * @brief Writes the header information to a TTTR file. - * - * @param fn The filename to write the header to. - * @param header Pointer to the TTTRHeader object containing header information. - */ - void write_header(std::string &fn, TTTRHeader* header = nullptr); - - /*! - * @brief Shifts the macro time by adding an integer value to each macro time entry. - * - * @param shift The integer value added to each macro time entry. - */ - void shift_macro_time(int shift); + void write_header(std::string &fn, TTTRHeader* header = nullptr); /*! - * @brief Adds the events of another TTTR object to the current TTTR object. - * - * @param other Pointer to the TTTR object whose events will be added. - * @return Pointer to a new TTTR object containing the combined events. - */ - TTTR* operator+(const TTTR* other) const { + * Shift the macro time by a constant + * @param shift + */ + 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; } - /*! - * @brief Computes a histogram of the TTTR data's micro times. - * - * @param tttr_data Pointer to the TTTR object containing the data. - * @param output Pointer to which the histogram will be written (memory is allocated by the method). - * @param n_output Pointer to the number of points in the histogram. - * @param time Pointer to the time axis of the histogram (memory is allocated by the method). - * @param n_time Pointer to the number of points in the time axis. - * @param micro_time_coarsening A factor by which the micro times in the TTTR object are divided (default value is 1). - * @param tttr_indices Optional pointer to store the indices of TTTR events used in the histogram. - */ - 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 *tttr_indices = nullptr - ); - - /*! - * @brief Computes and returns a histogram of the TTTR data's micro times. - * - * @param histogram Pointer to which the histogram will be written (memory is allocated by the method). - * @param n_histogram Pointer to the number of points in the histogram. - * @param time Pointer to the time axis of the histogram (memory is allocated by the method). - * @param n_time Pointer to the number of points in the time axis. - * @param micro_time_coarsening A factor by which the micro times in the TTTR object are divided (default value is 1). - */ - 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 - ); - } - - /*! - * @brief Computes the mean lifetime by the moments of the decay and the instrument response function. - * - * The computed lifetime is the first lifetime determined by the method of moments (Irvin Isenberg, - * 1973, Biophysical journal). - * - * @param tttr_data TTTR object for which the lifetime is computed. - * @param tttr_irf TTTR object that is used as IRF. - * @param m0_irf Number of counts in the IRF (used if no TTTR object for IRF provided). - * @param m1_irf First moment of the IRF (used if no TTTR object for IRF provided). - * @param tttr_indices Optional list of indices for selecting a subset of the TTTR. - * @param dt Time resolution of the micro time. If not provided, extracted from the header (slow). - * @param minimum_number_of_photons Minimum number of photons. If fewer photons are in the dataset, - * returns -1 as computed lifetime. - * @param background Background pattern. - * @param m0_bg Sum of background photons (overwritten if the background pattern is not empty). - * @param m1_bg First moment of the background pattern (overwritten if the background - * pattern is not empty). - * @param background_fraction Background fraction (if negative, the background is not scaled). - * @return The computed lifetime. - */ - static double compute_mean_lifetime( - TTTR *tttr_data, - TTTR *tttr_irf = nullptr, - double m0_irf = 1, double m1_irf = 0, - std::vector *tttr_indices = nullptr, - double dt = -1.0, - int minimum_number_of_photons = 1, - std::vector *background = nullptr, - double m0_bg = 0.0, double m1_bg = 0.0, - double background_fraction = -1.0 - ); - - /*! - * @brief Computes the mean lifetime by moments of decay and instrument response. - * - * @param tttr_irf TTTR object used as IRF. - * @param m0_irf Counts in the IRF (used if no TTTR object for IRF provided). - * @param m1_irf First moment of the IRF (used if no TTTR object for IRF provided). - * @param tttr_indices Optional indices for selecting a subset of the TTTR. - * @param dt Time resolution of the micro time. If not provided, extracted from the header (slow). - * @param min_ph Minimum number of photons. If fewer photons are in the dataset, returns -1 as computed lifetime. - * @return Computed mean lifetime. - */ - double mean_lifetime( - TTTR *tttr_irf = nullptr, - int m0_irf = 1, int m1_irf = 1, - std::vector *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 - ); - } - - /*! - * @brief Computes the count rate. - * - * @param tttr_data TTTR object for which the count rate is computed. - * @param tttr_indices Optional indices for selecting a subset of the TTTR. - * @param macrotime_resolution If negative (default), reads macrotime resolution from header (slow). - * @return Count rate. - */ - static double compute_count_rate( - TTTR *tttr_data, - std::vector *tttr_indices = nullptr, - double macrotime_resolution = -1.0 - ); - - /*! - * @brief Gets the count rate. - * - * @param tttr_indices Optional indices for selecting a subset of the TTTR. - * @param macrotime_resolution If negative (default), reads macrotime resolution from header (slow). - * @return Count rate. - */ - double get_count_rate( - std::vector *tttr_indices = nullptr, - double macrotime_resolution = -1.0 - ){ - return compute_count_rate(this, tttr_indices, macrotime_resolution); - } - - /*! - * @brief Computes the mean microtime. - * - * @param tttr_data TTTR object for which the mean microtime is computed. - * @param tttr_indices Optional indices for selecting a subset of the TTTR. - * @param microtime_resolution If negative (default), reads microtime resolution from header (slow). - * @param minimum_number_of_photons Minimum number of photons. If less, returns -1 as computed mean microtime. - * @return The computed mean microtime. - */ - static double compute_mean_microtime( - TTTR *tttr_data, - std::vector *tttr_indices = nullptr, - double microtime_resolution = -1.0, - int minimum_number_of_photons = 1 - ); + /*! + * Computes a histogram of the TTTR data's micro times + * + * @param tttr_data a pointer to the TTTR data + * @param output pointer to which the histogram will be written (the memory + * is allocated but the method) + * @param n_output the number of points in the histogram + * @param time pointer to the time axis of the histogram (the memory is allocated + * by the method) + * @param n_time the number of points in the time axis + * @param micro_time_coarsening a factor by which the micro times in the TTTR + * object are divided (default value is 1). + */ + 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 *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 + ); + } /*! - * @brief Gets the mean microtime. - * - * @param tttr_indices Optional indices for selecting a subset of the TTTR. - * @param microtime_resolution If negative (default), reads microtime resolution from header (slow). - * @param minimum_number_of_photons Minimum number of photons. If less, returns -1 as computed mean microtime. - * @return The computed mean microtime. - */ + * Compute a mean lifetime by the moments of the decay and the instrument + * response function. + * + * The computed lifetime is the first lifetime determined by the method of + * moments (Irvin Isenberg, 1973, Biophysical journal). + * + * @param tttr_data TTTR object for which the lifetime is computed + * @param tttr_irf TTTR object that is used as IRF + * @param m0_irf[in] Number of counts in the IRF (used if no TTTR object for IRF provided. + * @param m1_irf[in] First moment of the IRF (used if no TTTR object for IRF provided. + * @param tttr_indices[in] Optional list of indices for selecting a subset of the TTTR + * @param dt[in] Time resolution of the micro time. If not provided extracted from the header (slow) + * @param minimum_number_of_photons[in] Minimum number of photons. If less photons are in the dataset + * returns -1 as computed lifetime + * @param background background pattern + * @param m0_bg sum of background photons (overwritten if background pattern not empty) + * @param m1_bg first moment of background pattern (overwritten if background pattern not empty) + * @param background_fraction background fraction (if negative background is not scaled) + * @return The computed lifetime + */ + static double compute_mean_lifetime( + TTTR *tttr_data, + TTTR *tttr_irf = nullptr, + double m0_irf = 1, double m1_irf = 0, + std::vector *tttr_indices = nullptr, + double dt = -1.0, + int minimum_number_of_photons = 1, + std::vector *background = nullptr, + double m0_bg = 0.0, double m1_bg = 0.0, + double background_fraction = -1.0 + ); + + /*! + * Compute the mean lifetime by the moments of the decay and the instrument + * response function. + */ + double mean_lifetime( + TTTR *tttr_irf = nullptr, + int m0_irf = 1, int m1_irf = 1, + std::vector *tttr_indices = nullptr, + double dt = -1.0, + int minimum_number_of_photons = 1 + ){ + return compute_mean_lifetime( + this, + tttr_irf, m0_irf, m1_irf, + tttr_indices, dt, minimum_number_of_photons + ); + } + + /*! + * Compute the count rate + * + * @param tttr_data[in] TTTR object for which the lifetime is computed + * @param macrotime_resolution[in] If negative (default) reads macrotime resolution from header (slow) + * @return Count rate + */ + static double compute_count_rate( + TTTR *tttr_data, + std::vector *tttr_indices = nullptr, + double macrotime_resolution = -1.0 + ); + + double get_count_rate( + std::vector *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 *tttr_indices = nullptr, + double microtime_resolution = -1.0, + int minimum_number_of_photons = 1 + ); + double get_mean_microtime( - std::vector *tttr_indices = nullptr, - double microtime_resolution = -1.0, - int minimum_number_of_photons = 1 + std::vector *tttr_indices = nullptr, + double microtime_resolution = -1.0, + int minimum_number_of_photons = 1 ){ return compute_mean_microtime( this, tttr_indices, diff --git a/include/TTTRHeader.h b/include/TTTRHeader.h index 732d6f8a..e7b7fa5c 100644 --- a/include/TTTRHeader.h +++ b/include/TTTRHeader.h @@ -14,9 +14,6 @@ #include #include #include -#include -#include // std::stringstream -#include /* std::setfill */ #include /* ifstream */ #include @@ -49,7 +46,6 @@ class TTTRHeader { friend class TTTR; protected: - // JSON object used to store all the header information nlohmann::json json_data; @@ -245,14 +241,15 @@ class TTTRHeader { TTTRHeader(std::string fn, int tttr_container_type=0); ~TTTRHeader() = default; - /*! - * @brief Reads the header of a PTU file and sets the reading routing. + /*! Reads the header of a ptu file and sets the reading routing for * - * @param fpin File pointer to the PTU file. - * @param tttr_record_type Output parameter for the TTTR record type. - * @param json_data Output parameter for JSON data. - * @param rewind Flag to indicate whether to rewind the file (default is true). - * @return The position of the file pointer at the end of the header. + * @param fpin + * @param rewind + * @param tttr_record_type + * @param json_data + * @param macro_time_resolution + * @param micro_time_resolution + * @return The position of the file pointer at the end of the header */ static size_t read_ptu_header( std::FILE *fpin, @@ -261,27 +258,26 @@ class TTTRHeader { bool rewind = true ); - /*! - * @brief Reads the header of an HT3 file and sets the reading routing. + /*! Reads the header of a ht3 file and sets the reading routing for * - * @param fpin File pointer to the HT3 file. - * @param data Output parameter for JSON data. - * @param rewind Flag to indicate whether to rewind the file (default is true). - * @return The position of the file pointer at the end of the header. + * @param fpin + * @param rewind + * @param tttr_record_type + * @param data + * @return The position of the file pointer at the end of the header */ static size_t read_ht3_header( std::FILE *fpin, nlohmann::json &data, - bool rewind = true + bool rewind=true ); - /*! - * @brief Reads the header of a Becker & Hickel SPC132 file and sets the reading routing. + /*! Reads the header of a Becker&Hickel SPC132 file and sets the reading routing * - * @param fpin File pointer to the SPC132 file. - * @param data Output parameter for JSON data. - * @param rewind Flag to indicate whether to rewind the file (default is true). - * @return The position of the file pointer at the end of the header. + * @param fpin + * @param rewind + * @param tttr_record_type + * @param data JSON dictionary that will contain the header information */ static size_t read_bh132_header( std::FILE *fpin, @@ -289,20 +285,6 @@ class TTTRHeader { bool rewind = true ); - /*! - * @brief Reads the header of a Carl Zeiss (CZ) Confocor3 file and sets the reading routing. - * - * @param fpin File pointer to the Confocor3 file. - * @param data Output parameter for JSON data. - * @param rewind Flag to indicate whether to rewind the file (default is true). - * @return The position of the file pointer at the end of the header. - */ - static size_t read_cz_confocor3_header( - std::FILE *fpin, - nlohmann::json &data, - bool rewind = true - ); - /*! * Write a spc132 header to a file * diff --git a/include/TTTRHeaderTypes.h b/include/TTTRHeaderTypes.h index e0aaf26c..1fc2489b 100644 --- a/include/TTTRHeaderTypes.h +++ b/include/TTTRHeaderTypes.h @@ -37,7 +37,6 @@ #define BH_SPC600_256_CONTAINER 3 #define BH_SPC600_4096_CONTAINER 4 #define PHOTON_HDF_CONTAINER 5 -#define CZ_CONFOCOR3_CONTAINER 6 // tttrlib record type identifier definitions #define PQ_RECORD_TYPE_HHT2v2 1 @@ -49,7 +48,6 @@ #define BH_RECORD_TYPE_SPC130 7 #define BH_RECORD_TYPE_SPC600_256 8 #define BH_RECORD_TYPE_SPC600_4096 9 -#define CZ_RECORD_TYPE_CONFOCOR3 10 /* @@ -61,6 +59,7 @@ typedef struct { int32_t Show; } CurveMapping_t; + typedef struct { float Start; float Step; @@ -72,6 +71,7 @@ typedef struct{ int32_t VersionCode; } pq_ht3_board_settings_t; + /// The following represents the readable ASCII file header portion in a HT3 file typedef struct { char Ident[16]; //"PicoHarp 300" @@ -139,25 +139,6 @@ typedef struct { } pq_ht3_TTModeHeader_t; -/// Carl Zeiss Confocor3 raw data -typedef union cz_confocor3_settings{ - uint32_t allbits; - struct{ - char Ident[52]; - char dummy1[11]; - unsigned channel :8; - // 64 byte - uint32_t measure_id[4]; // 16 - uint32_t measurement_position; // 8 - uint32_t kinetic_index; // 8 - uint32_t repetition_number; // 8 - uint32_t frequency; // 8 - char dummy2[32]; //32 - // 64 + 64 byte - } bits; -} cz_confocor3_settings_t; - - /// Becker&Hickl SPC132 Header typedef union bh_spc132_header{ uint32_t allbits; diff --git a/include/TTTRMask.h b/include/TTTRMask.h index b4159a0f..9627df11 100644 --- a/include/TTTRMask.h +++ b/include/TTTRMask.h @@ -41,23 +41,17 @@ class TTTRMask{ void set_tttr(TTTR* tttr); /*! - * @brief Selects a subset of indices by a list of routing channel numbers. + * Selects a subset of indices by a list of routing channel numbers. * * The returned set of indices will have routing channel numbers that are in * the list of the provided routing channel numbers. * - * @param tttr Pointer to TTTR object. - * @param routing_channels Array of routing channel numbers. A subset of this + * @param tttr pointer to TTTR object + * @param routing_channels[int] routing channel numbers. A subset of this * array will be selected by the input. - * @param n_routing_channels Length of the routing channel number array. - * @param mask Default value if a channel is selected. + * @param n_routing_channels[int] length of the routing channel number array. */ - void select_channels( - TTTR* tttr, - signed char *routing_channels, - int n_routing_channels, - bool mask = false - ); + void select_channels(TTTR* tttr, signed char *routing_channels, int n_routing_channels, bool mask=false); /*! * Selects a subset of indices a count rate of a sliding time-window diff --git a/include/TTTRRange.h b/include/TTTRRange.h index 900a502c..43a128c7 100644 --- a/include/TTTRRange.h +++ b/include/TTTRRange.h @@ -9,39 +9,19 @@ #include "TTTR.h" -/** - * @brief Represents a range of TTTR indices. - */ + class TTTRRange { protected: //boost::container::flat_set _tttr_indices{}; //std::flat_set _tttr_indices{}; - - /// Set of TTTR indices in the range. itlib::flat_set _tttr_indices{}; public: - /** - * @brief Constructs a TTTRRange with the specified start and stop indices. - * - * @param start The start index of the range. - * @param stop The stop index of the range. - */ TTTRRange(int start, int stop); - /** - * @brief Constructs a TTTRRange. - * - * If both `start` and `stop` are non-negative, inserts them into the `_tttr_indices` set. - * If `other` is not nullptr, inserts its start and stop indices into the set. - * - * @param start The start index of the range. - * @param stop The stop index of the range. - * @param other Pointer to another TTTRRange (optional). - */ TTTRRange(int start=-1, int stop=-1, TTTRRange* other = nullptr){ if((start >=0) && (stop >= 0)){ _tttr_indices.insert(start); @@ -52,37 +32,20 @@ class TTTRRange { } } - /** - * @brief Gets the number of TTTR indices in the range. - * - * @return The size of the `tttr_indices` set. - */ virtual size_t size(){ return _tttr_indices.size(); } - /** - * @brief Copy constructor. - * - * @param p2 Reference to another TTTRRange to copy. - */ + /// Copy constructor TTTRRange(const TTTRRange& p2); - /** - * @brief Gets the vector of TTTR indices assigned to the range. - * - * @return A vector containing the TTTR indices in the set. - */ + /// A vector containing a set of TTTR indices that was assigned to the range std::vector get_tttr_indices(){ std::vector v(_tttr_indices.begin(), _tttr_indices.end()); return v; } - /** - * @brief Gets the start index of the TTTR range. - * - * @return The start index or -1 if the set is empty. - */ + /// The start index of the TTTR range object int get_start() const{ if(!_tttr_indices.empty()){ return *_tttr_indices.begin(); @@ -91,11 +54,7 @@ class TTTRRange { } } - /** - * @brief Gets the stop index of the TTTR range. - * - * @return The stop index or -1 if the set is empty. - */ + /// The stop index of the TTTR range object int get_stop() const{ if(!_tttr_indices.empty()){ return *_tttr_indices.rbegin(); @@ -104,11 +63,7 @@ class TTTRRange { } } - /** - * @brief Gets a vector of the start and stop TTTR indices of the range. - * - * @return A vector containing the start and stop indices. - */ + /// A vector of the start and the stop TTTR index of the range std::vector get_start_stop(){ return { get_start(), @@ -116,12 +71,7 @@ class TTTRRange { }; } - /** - * @brief Gets the stop time of the TTTR range. - * - * @param tttr Pointer to a TTTR object. - * @return The stop time or 0 if tttr is nullptr or the set is empty. - */ + /// The stop time of the TTTR range object unsigned long get_stop_time(TTTR* tttr) const{ unsigned long time = 0; if(tttr!= nullptr){ @@ -132,12 +82,7 @@ class TTTRRange { return time; } - /** - * @brief Gets the start time of the TTTR range. - * - * @param tttr Pointer to a TTTR object. - * @return The start time or 0 if tttr is nullptr or the set is empty. - */ + /// The start time of the TTTR range object unsigned long get_start_time(TTTR* tttr) const{ unsigned long start_time = 0; if(tttr!= nullptr){ @@ -148,12 +93,7 @@ class TTTRRange { return start_time; } - /** - * @brief Gets a vector of the start and stop times of the TTTR range. - * - * @param tttr Pointer to a TTTR object. - * @return A vector containing the start and stop times. - */ + /// A vector of the start and stop time std::vector get_start_stop_time(TTTR* tttr){ return { get_start_time(tttr), @@ -161,41 +101,23 @@ class TTTRRange { }; } - /** - * @brief Gets the duration between the start and stop times of the TTTR range. - * - * @param tttr Pointer to a TTTR object. - * @return The duration or 0 if tttr is nullptr or the set is empty. - */ + /// The difference between the start and the stop time of a range unsigned int get_duration(TTTR* tttr){ return get_stop_time(tttr) - get_start_time(tttr); } - /** - * @brief Inserts an index into the TTTR index vector. - * - * @param idx The index to insert. - */ + /// Append a index to the TTTR index vector void insert(int idx){ _tttr_indices.insert(idx); } - /** - * @brief Clears the TTTR index set. - */ + /// Clears the TTTR index vector void clear(){ _tttr_indices.clear(); } - /** - * @brief Strips TTTR indices from a range starting at tttr_indices[offset]. - * - * The tttr_indices need to be sorted in ascending size. - * - * @param tttr_indices Vector of TTTR indices. - * @param offset Offset index. - * @return Updated offset index. - */ + /// Strip tttr_indices from a range starting at tttr_indices[offset] + /// the tttr_indices need to be sorted in ascending size int strip(const std::vector &tttr_indices, int offset = 0){ if(!_tttr_indices.empty()){ for(; offset < tttr_indices.size(); offset++){ @@ -210,16 +132,14 @@ class TTTRRange { return offset; } - /** - * @brief Computes the mean microtime in units of the microtime resolution. + /*! + * Computes to the mean micro time (in units of the micro channel resolution). * - * If there are fewer than the minimum number of photons in a TTTRRange, + * If there are less then the minimum number of photons in a TTTRRange * the function returns zero. * - * @param tttr_data Pointer to a TTTR object. - * @param microtime_resolution Microtime resolution. - * @param minimum_number_of_photons Minimum number of photons in a micro time. - * @return The mean microtime. + * @param tttr_data[in] pointer to a TTTR object + * @param minimum_number_of_photons[in] the minimum number of photons in a micro time */ double get_mean_microtime( TTTR* tttr_data, @@ -234,16 +154,6 @@ class TTTRRange { ); } - /** - * @brief Gets the microtime histogram for the TTTRRange. - * - * @param tttr Pointer to a TTTR object. - * @param histogram Pointer to the histogram array. - * @param n_histogram Pointer to the size of the histogram array. - * @param time Pointer to the time array. - * @param n_time Pointer to the size of the time array. - * @param micro_time_coarsening Microtime coarsening factor. - */ void get_microtime_histogram( std::shared_ptr tttr, double** histogram, int* n_histogram, @@ -260,25 +170,20 @@ class TTTRRange { ); } - /** - * @brief Computes the mean lifetime for the TTTRRange. + /*! + * Return the average lifetime * - * If a TTTRRange has not enough photons, returns -1. + * If a TTTRRange has not enough photons return -1 * - * By default, fluorescence lifetimes are computed in units of the micro time + * By default the fluorescence lifetimes are computed in units of the micro time * if no dt is provided. * - * @param tttr_data Pointer to a TTTR object. - * @param minimum_number_of_photons Minimum number of photons in a micro time. - * @param tttr_irf Pointer to a TTTR object of the IRF. - * @param m0_irf Zero moment of the IRF (optional, default=1). - * @param m1_irf First moment of the IRF (optional, default=1). - * @param dt Time resolution of the micro time. - * @param background Vector of background values (optional). - * @param m0_bg Zero moment of the background (optional, default=0). - * @param m1_bg First moment of the background (optional, default=0). - * @param background_fraction Fraction of background pattern in data (if negative, no background). - * @return The mean lifetime. + * @param tttr_data[in] pointer to a TTTR object + * @param tttr_irf[in] pointer to a TTTR object of the IRF + * @param minimum_number_of_photons[in] the minimum number of photons in a micro time + * @param m0_irf is the zero moment of the IRF (optional, default=1) + * @param m1_irf is the first moment of the IRF (optional, default=1) + * @param dt time resolution of the micro time */ double get_mean_lifetime( TTTR *tttr_data, @@ -291,29 +196,25 @@ class TTTRRange { double background_fraction = -1.0 ); - /** - * @brief Computes the mean lifetime for a set of TTTR indices. + /*! + * Compute the average lifetime for a set of TTTR indices * * The average lifetimes are computed (not fitted) by the methods of - * moments (Irvin Isenberg, 1973, Biophysical journal). + * moments (Irvin Isenberg, 1973, Biophysical journal). This approach + * does not consider scattered light. * - * If a TTTRRange has not enough photons, it is filled with zeros. + * If a TTTRRange has not enough photons it is filled with zeros. * - * By default, fluorescence lifetimes are computed in units of the micro time + * By default the fluorescence lifetimes are computed in units of the micro time * if no dt is provided. * - * @param tttr_indices Vector of TTTR indices. - * @param tttr_data Pointer to a TTTR object. - * @param minimum_number_of_photons Minimum number of photons in a micro time. - * @param tttr_irf Pointer to a TTTR object of the IRF. - * @param m0_irf Zero moment of the IRF (optional, default=1). - * @param m1_irf First moment of the IRF (optional, default=1). - * @param dt Time resolution of the micro time. - * @param background Vector of background values (optional). - * @param m0_bg Zero moment of the background (optional, default=0). - * @param m1_bg First moment of the background (optional, default=0). - * @param background_fraction Fraction of background pattern in data (if negative, no background). - * @return The mean lifetime. + * @param tttr_data[in] pointer to a TTTR object + * @param tttr_irf[in] pointer to a TTTR object of the IRF + * @param minimum_number_of_photons[in] the minimum number of photons in a micro time + * @param m0_irf is the zero moment of the IRF (optional, default=1) + * @param m1_irf is the first moment of the IRF (optional, default=1) + * @param dt time resolution of the micro time + * @param background_fraction fraction of background pattern in data (if negative no background) */ static double compute_mean_lifetime( std::vector &tttr_indices, @@ -327,33 +228,15 @@ class TTTRRange { double background_fraction = -1.0 ); - /** - * @brief Equality operator. - * - * @param other Another TTTRRange to compare. - * @return True if the two TTTRRanges are equal, false otherwise. - */ bool operator==(const TTTRRange& other) const { return _tttr_indices == other._tttr_indices; } - /** - * @brief Inequality operator. - * - * @param other Another TTTRRange to compare. - * @return True if the two TTTRRanges are not equal, false otherwise. - */ bool operator!=(const TTTRRange& other) const { return !operator==(other); } - /** - * @brief Compound assignment addition operator. - * - * @param rhs Another TTTRRange to add. - * @return Reference to the modified TTTRRange. - */ TTTRRange& operator+=(const TTTRRange& rhs){ for(auto &v: rhs._tttr_indices){ _tttr_indices.insert(v); diff --git a/include/TTTRRecordReader.h b/include/TTTRRecordReader.h index dc248786..027a18a4 100644 --- a/include/TTTRRecordReader.h +++ b/include/TTTRRecordReader.h @@ -6,15 +6,12 @@ #include "TTTRRecordTypes.h" +/*********************************************/ +/*** ***/ +/*** HT3 HHv1.0 ***/ +/*** https://github.com/tsbischof/libpicoquant/blob/master/src/hydraharp/hh_v20.h ***/ +/*********************************************/ -bool ProcessCzRaw( - uint32_t &TTTRRecord, - uint64_t &overflow_counter, - uint64_t &true_nsync, - uint32_t µ_time, - int16_t &channel, - int16_t &record_type -); bool ProcessSPC130( uint32_t &TTTRRecord, @@ -43,8 +40,6 @@ bool ProcessSPC600_256( int16_t &record_type ); -/* See: https://github.com/tsbischof/libpicoquant/blob/master/src/hydraharp/hh_v20.h ***/ - bool ProcessHHT2v2( uint32_t &TTTRRecord, uint64_t &overflow_counter, diff --git a/include/TTTRRecordTypes.h b/include/TTTRRecordTypes.h index d4fc3937..13b6329b 100644 --- a/include/TTTRRecordTypes.h +++ b/include/TTTRRecordTypes.h @@ -115,12 +115,5 @@ typedef union bh_overflow{ } bh_overflow_t; -// Carl Zeiss Confocor3 raw dat -typedef union cz_confocor3_raw_record{ - uint32_t allbits; - struct { - unsigned mt :32; - } bits; -} cz_confocor3_raw_record_t; #endif //TTTRLIB_TTTRRECORDTYPES_H diff --git a/include/i_lbfgs.h b/include/i_lbfgs.h index 6bccaf3d..fc0856db 100644 --- a/include/i_lbfgs.h +++ b/include/i_lbfgs.h @@ -1,5 +1,5 @@ -#ifndef TTTRLIB_I_BFGS_H -#define TTTRLIB_I_BFGS_H +#ifndef FIT2X_I_BFGS_H +#define FIT2X_I_BFGS_H // minimize f(x,p) using BFGS algorithm @@ -146,4 +146,4 @@ class bfgs }; -#endif //TTTRLIB_I_BFGS_H +#endif //FIT2X_I_BFGS_H