From 2561f0099c71fb08cbc37f7109d1d217ad4a46d6 Mon Sep 17 00:00:00 2001 From: LTLA Date: Thu, 15 Aug 2024 13:15:01 -0700 Subject: [PATCH] Improvements to the Doxygen configuration: - Exclude internal-only SPTree.hpp. - Added knncolle tagfile for nice links. - Minor clean-ups to various docstrings. --- .github/workflows/doxygenate.yaml | 5 +++++ docs/Doxyfile | 10 +++++++--- include/qdtsne/Options.hpp | 3 +-- include/qdtsne/Status.hpp | 4 ++-- include/qdtsne/utils.hpp | 18 +++++++++--------- 5 files changed, 24 insertions(+), 16 deletions(-) diff --git a/.github/workflows/doxygenate.yaml b/.github/workflows/doxygenate.yaml index 5464fff..ea3e9f2 100644 --- a/.github/workflows/doxygenate.yaml +++ b/.github/workflows/doxygenate.yaml @@ -16,6 +16,11 @@ jobs: with: args: -O docs/doxygen-awesome.css https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/main/doxygen-awesome.css + - name: Add knncolle tagfile + uses: wei/wget@v1 + with: + args: -O docs/knncolle.tag https://knncolle.github.io/knncolle/knncolle.tag + - name: Doxygen Action uses: mattnotmitt/doxygen-action@v1 with: diff --git a/docs/Doxyfile b/docs/Doxyfile index 5b7b73a..a5f1960 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -917,7 +917,11 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../include/qdtsne \ +INPUT = ../include/qdtsne/qdtsne.hpp \ + ../include/qdtsne/Options.hpp \ + ../include/qdtsne/Status.hpp \ + ../include/qdtsne/initialize.hpp \ + ../include/qdtsne/utils.hpp \ ../README.md # This tag can be used to specify the character encoding of the source files @@ -2370,13 +2374,13 @@ SKIP_FUNCTION_MACROS = YES # the path). If a tag file is not located in the directory in which doxygen is # run, you must also specify the path to the tagfile here. -TAGFILES = +TAGFILES = knncolle.tag=https://knncolle.github.io/knncolle/ # When a file name is specified after GENERATE_TAGFILE, doxygen will create a # tag file that is based on the input files it reads. See section "Linking to # external documentation" for more information about the usage of tag files. -GENERATE_TAGFILE = +GENERATE_TAGFILE = html/qdtsne.tag # If the ALLEXTERNALS tag is set to YES, all external class will be listed in # the class index. If set to NO, only the inherited external classes will be diff --git a/include/qdtsne/Options.hpp b/include/qdtsne/Options.hpp index 64f0d58..0be2525 100644 --- a/include/qdtsne/Options.hpp +++ b/include/qdtsne/Options.hpp @@ -3,14 +3,13 @@ /** * @file Options.hpp - * * @brief Options for the t-SNE algorithm. */ namespace qdtsne { /** - * @param Options for `initialize()`. + * @brief Options for `initialize()`. */ struct Options { /** diff --git a/include/qdtsne/Status.hpp b/include/qdtsne/Status.hpp index 20cbe90..26eb9f5 100644 --- a/include/qdtsne/Status.hpp +++ b/include/qdtsne/Status.hpp @@ -45,13 +45,13 @@ /** * @file Status.hpp - * @brief Status of the t-SNE algorithm. + * @brief Status of the t-SNE iterations. */ namespace qdtsne { /** - * @brief Current status of the t-SNE iterations. + * @brief Status of the t-SNE iterations. * * @tparam num_dim_ Number of dimensions in the t-SNE embedding. * @tparam Index_ Integer type for the neighbor indices. diff --git a/include/qdtsne/utils.hpp b/include/qdtsne/utils.hpp index 57d0d72..e54ecaa 100644 --- a/include/qdtsne/utils.hpp +++ b/include/qdtsne/utils.hpp @@ -27,7 +27,7 @@ using NeighborList = std::vector > >; /** * Determines the appropriate number of neighbors, given a perplexity value. - * Useful when the neighbor search is conducted outside of the `Tsne` class. + * Useful when the neighbor search is conducted outside of `initialize()`. * * @param perplexity Perplexity to use in the t-SNE algorithm. * @return Number of nearest neighbors to find. @@ -44,16 +44,16 @@ inline int perplexity_to_k(double perplexity) { * @tparam num_dim_ Number of embedding dimensions. * @tparam Float_ Floating-point type to use for the calculations. * - * @param[out] Y Pointer to a 2D array with number of rows and columns equal to `num_dim` and N`, respectively. + * @param[out] Y Pointer to a 2D array with number of rows and columns equal to `num_dim` and `num_points`, respectively. * On output, `Y` is filled with random draws from a standard normal distribution. - * @param N Number of observations. + * @param num_points Number of points in the embedding. * @param seed Seed for the random number generator. */ template void initialize_random(Float_* Y, size_t N, int seed = 42) { std::mt19937_64 rng(seed); - size_t total = N * num_dim_; + size_t total = num_pts * num_dim_; bool odd = total % 2; if (odd) { --total; @@ -81,15 +81,15 @@ void initialize_random(Float_* Y, size_t N, int seed = 42) { * @tparam num_dim_ Number of embedding dimensions. * @tparam Float_ Floating-point type to use for the calculations. * - * @param N Number of observations. + * @param num_points Number of observations. * @param seed Seed for the random number generator. * - * @return A vector of length `N * num_dim_` containing random draws from a standard normal distribution. + * @return A vector of length `num_points * num_dim_` containing random draws from a standard normal distribution. */ template -std::vector initialize_random(size_t N, int seed = 42) { - std::vector Y(num_dim_ * N); - initialize_random(Y.data(), N, seed); +std::vector initialize_random(size_t num_points, int seed = 42) { + std::vector Y(num_dim_ * num_points); + initialize_random(Y.data(), num_points, seed); return Y; }