# Plotting an ordered set goes through qeviz. These functions keep the API

# ONA has always had -- plot() on a set, then edges(), nodes() and units()

# chained onto it -- and translate each call into the matching qe_*() call.

# The returned object is a qeviz `qe_plot` with the class "enaplot" in front,

# so every qeviz chain function (qe_edges(), qe_group(), qe_axes(),

# qe_export_html(), ...) works on it as well.

#' Plot an ONA set

#'

#' Creates a [qeviz::qe_plot()] for an ordered set. The plot starts empty:

#' add the mean network with [edges()], the code nodes with [nodes()] and the

#' unit points with [units()]. Any qeviz chain function can be used on the

#' result too, for example `qe_edges("FirstGame", compare = "SecondGame")`.

#'

#' @param x An `ena.ordered.set` from [model()].

#' @param y Ignored (present for the `plot()` generic).

#' @param ... Passed to [qeviz::qe_plot()] (e.g. `title`, `width`, `height`,

#'   `range`).

#' @param dimensions The two dimensions to plot, by name (e.g.

#'   `c("SVD2", "SVD3")`). Default: the first two.

#' @param group_col Metadata column that groups the units, used for qeviz's

#'   group means and `qe_edges(group =)`. Default: `"Condition"` when the set

#'   has that column, otherwise none.

#' @param scale_points Whether qeviz rescales the points to the extent of the

#'   nodes. Default `FALSE`: ONA's node positions are already fitted to the

#'   points, so both are drawn as they are in the set.

#' @param legacy Draw the plot the way ONA 0.1 did: axes fixed at

#'   `c(-max_axis_marker, max_axis_marker)` with the axis cross shown, and

#'   edge widths and node sizes in data units (a weight of 1 is as wide as one

#'   unit of the axes). Default `FALSE`: qeviz fits the axes to the plot and

#'   draws a weight of 1 as 4% of the plot width. Use it to keep figures

#'   comparable with ones made before plotting moved to qeviz.

#' @param max_axis_marker Half the axis range when `legacy = TRUE`.

#'

#' @return An object of classes `enaplot` and `qe_plot`.

#' @seealso [edges()], [nodes()], [units()], [qeviz::qe_plot()]

#' @export

'plot.ena.ordered.set' <- function(x, y, ..., dimensions = NULL, group_col = NULL,

                                   scale_points = FALSE, legacy = FALSE,

                                   max_axis_marker = 3) {

  }

  }

  }

  # In data units, a weight of 1 spans one axis unit of the 2 * max_axis_marker

  # wide plot.

}

# Every chain function accepts the set itself as well as a plot of it.

as_enaplot <- function(x, fn) {

}

# A network as one weight per edge column, named "A & B": a vector is used as

# is, rows of line weights (the whole table or a subset such as

# `set$line.weights$Condition$FirstGame`) are averaged.

mean_network <- function(weights) {

  }

}

#' Draw a network's edges

#'

#' Adds a directed edge network to the plot through [qeviz::qe_edges()]. By

#' default it is the mean network of every unit in the set; `weights` draws

#' another network, typically one group's rows of `set$line.weights`. Node

#' sizes follow the drawn network (each node's diameter is the summed width

#' of the edges directed at it, plus its self-connection).

#'

#' @param x An `ena.ordered.set`, or a plot of one from [plot.ena.ordered.set()].

#' @param ... Passed to [qeviz::qe_edges()] (e.g. `threshold`, `name`,

#'   `color_scale`, `self_size`, `edge_width`; a legacy plot sets

#'   `edge_width` to its data-unit scale unless given here).

#' @param weights The network to draw: a numeric vector of edge weights in the

#'   set's edge-column order, or rows of line weights to average (e.g.

#'   `set$line.weights$Condition$FirstGame`). Default: the mean of all units.

#' @param edge_color One colour, or `c(positive, negative)` colours for the

#'   edge weights.

#' @param multiplier Magnifies the edge widths and node sizes of the plot (the

#'   plot is labelled with the factor).

#' @param nodes Node positions to draw the edges between, in place of the

#'   set's (a table like `set$rotation$nodes`).

#'

#' @return The plot, with the network added.

#' @export

edges <- function(x, ..., weights = NULL, edge_color = c("#FF0000", "#0000FF"),

                  multiplier = 1, nodes = NULL) {

  }

  }

}

#' Draw the code nodes

#'

#' Shows the code nodes through [qeviz::qe_nodes()]. Nodes are drawn whenever

#' a network is, so this is only needed to show them without one, to move

#' them, or to hide their labels.

#'

#' @param x An `ena.ordered.set`, or a plot of one from [plot.ena.ordered.set()].

#' @param ... Passed to [qeviz::qe_nodes()] (e.g. `labels`, `sizes`,

#'   `unconnected`).

#' @param node_labels Whether to label the nodes with their codes.

#' @param nodes Node positions in place of the set's (a table like

#'   `set$rotation$nodes`).

#' @param node_position_multiplier Scales `nodes` (or the set's positions)

#'   before drawing.

#'

#' @return The plot, with the nodes shown.

#' @export

nodes <- function(x, ..., node_labels = TRUE, nodes = NULL, node_position_multiplier = 1) {

  }

  }

}

#' Draw the units' points and their mean

#'

#' Adds the units' points as a point set ([qeviz::qe_points()]) and their mean

#' with its confidence interval as a group mean ([qeviz::qe_group()]). Call it

#' once per group of units to compare, with `points` and `points_color`.

#'

#' @param x An `ena.ordered.set`, or a plot of one from [plot.ena.ordered.set()].

#' @param ... Passed to [qeviz::qe_points()] (e.g. `size`, `labels`).

#' @param points The points to draw, default all of `set$points`; a subset such

#'   as `set$points$Condition$FirstGame` draws one group.

#' @param points_color Colour of the points and their mean.

#' @param show_points Whether to draw the points.

#' @param show_mean Whether to draw their mean.

#' @param with_ci Whether to draw the mean's 95% confidence interval.

#' @param point_shape `"circle"`, `"square"`, `"triangle"` or `"diamond"`.

#' @param name Name of the point set; default `"points 1"`, `"points 2"`, ...

#' @param label Label of the mean; default `"mean 1"`, `"mean 2"`, ...

#'

#' @return The plot, with the points and mean added.

#' @export

units <- function(x, ..., points = NULL, points_color = "#FF0000",

                  show_points = TRUE, show_mean = TRUE, with_ci = TRUE,

                  point_shape = "circle", name = NULL, label = NULL) {

  }

  }

}

#' Print an ONA plot

#'

#' Renders the plot in the viewer or browser, as [qeviz::qe_plot()] objects

#' print.

#'

#' @param x An `enaplot` from [plot.ena.ordered.set()].

#' @param ... Passed on to qeviz's print method.

#'

#' @return `x`, invisibly.

#' @export

'print.enaplot' <- function(x, ...) {

}

#' Re-class vector as ena.co.occurrence

#'

#' @param x Vector to re-class

#'

#' @return re-classed vector

#' @export

as.ena.co.occurrence <- function(x) {

  }

}

# Direction helpers ----------------------------------------------------------

#

# The original ONA model() stacked one row per unit per direction and tagged

# them with an ENA_DIRECTION column ("ground"/"response"). Since model() became

# a wrapper around rENA::model(), an ordered set has one row per unit and no

# such column. The plot code keeps working with both shapes by

# going through these helpers: when the column is absent every row is treated

# as the "response" direction, which is what the original produced by default

# (rotation_on = "response").

#

# rENA's `$` method on ena.matrix objects raises an error for an absent column

# rather than returning NULL, so the column is always checked by name first.

has_direction <- function(x) {

}

n_directions <- function(x) {

}

direction_rows <- function(x, direction) {

  }

}

response_rows <- function(x) {

}

##' Calculate correlations between SVD and centroid differences in ONA model

##'

##' Computes Pearson and Spearman correlations between pairwise differences of points and centroids along specified dimensions in an Epistemic Network Analysis (ENA) model.

##'

##' @param enaset An ENA set object containing points and model centroids (typically output from ENA model fitting).

##' @param pts Optional data frame of points to use. If NULL, points are selected from `enaset$points` matching the specified direction.

##' @param cts Optional data frame or matrix of centroids to use. If NULL, centroids are taken from `enaset$model$centroids`.

##' @param dims Integer vector specifying which dimensions to use for the correlation (default: c(1,2)).

##' @param direction Character string specifying which direction(s) to include from `enaset$points$ENA_DIRECTION` (default: "response").

##'

##' @return A data frame with Pearson and Spearman correlations for each specified dimension.

##' @export

correlations <- function(enaset, pts = NULL, cts = NULL, dims = c(1:2), direction = "response") {

    # Not every ordered set carries an ENA_DIRECTION column -- a model with one

    # row per unit has no directions to separate. Check for the column by name

    # rather than reading it: filtering on an absent column would drop every

    # row, and rENA's `$.ena.points` raises an error rather than returning NULL.

    } else {

    }

  }

  # svdDiff/optDiff have one column per requested dimension, so index them by

  # position rather than by the caller's dimension number. Indexing by `dims`

  # only works for the default c(1,2); any other pair reads past the end.

    });

}

###

#' ona writeup

#'

#' @description provide writeup of the provided model

#'

#' @param enaset ENAset to view methods of

#' @param tool c("rENA","webENA")

#' @param tool.version as.character(packageVersion(tool))

#' @param comparison character string representing the comparison used, c(NULL, "parametric", "non-parametric"). Default NULL

#' @param comparison.groups Groups that were used for the comparison

#' @param sig.dig Integer for the number of digits to round to

#' @param output_dir Where to save the output file

#' @param type c("file","stream") File will save to a file in output_dir, Stream returns the contents directly

#' @param theory Logical indicating whether to include theory in the writeup

#' @param methods Logical indicating whether to include methods in the writeup

#' @param params additional parameters for rmarkdown::render

#' @param output_file character

#' @param output_format character

#' 

#' @importFrom utils packageVersion

#'

#' @export

#'

#' @return String representing the methods used to generate the model

ona.writeup <- function(

    enaset,

    tool = "ona", tool.version = as.character(packageVersion(tool)),

    comparison = NULL, comparison.groups = NULL, sig.dig = 2,

    output_dir = getwd(), type = c("file","stream"), theory = T, methods = T,

    params = NULL, output_file = NULL, output_format = NULL

) {

  }

                           # ,output_format = ifelse(type == "file", rENA::methods_report, rENA::methods_report_stream)

  )

}

#' @title methods_report

#' @description Output format for methods report in R Markdown (Word/docx)

#' @param toc Logical; include a table of contents (default: FALSE).

#' @param toc_depth Integer; depth of table of contents (default: 3).

#' @param fig_width Numeric; width (in inches) of figures (default: 5).

#' @param fig_height Numeric; height (in inches) of figures (default: 4).

#' @param keep_md Logical; keep the intermediate markdown file (default: FALSE).

#' @param md_extensions Character vector of additional markdown extensions to use (default: NULL).

#' @param pandoc_args Character vector of additional Pandoc command line arguments (default: NULL).

#'

#' @return An R Markdown output format object for use with `rmarkdown::render` (Word/docx output).

#' @export

methods_report <- function(toc = FALSE,

                           toc_depth = 3,

                           fig_width = 5,

                           fig_height = 4,

                           keep_md = FALSE,

                           md_extensions = NULL,

                           pandoc_args = NULL) {

  # knitr options and hooks

  )

  # build pandoc args

  # table of contents

  # pandoc args

  # pre_processor <- function(metadata, input_file, runtime, knit_meta,

  #                           files_dir, output_dir) {

  #   preserved_chunks <<- extract_preserve_chunks(input_file, knitr::extract_raw_output)

  #   NULL

  # }

  # post_processor <- function(metadata, input_file, output_file, clean, verbose) {

  #   output_str <- readLines(output_file, encoding = 'UTF-8')

  #   output_res <- knitr::restore_raw_output(output_str, preserved_chunks)

  #   if (!identical(output_str, output_res))

  #     writeLines(enc2utf8(output_res), output_file, useBytes = TRUE)

  #   output_file

  # }

  # return output format

    # ,pre_processor = pre_processor,

    # post_processor = post_processor

  )

}

#' @title methods_report_stream

#' @description Output format for methods report in R Markdown (plain text stream)

#' @param toc Logical; include a table of contents (default: FALSE).

#' @param toc_depth Integer; depth of table of contents (default: 3).

#' @param fig_width Numeric; width (in inches) of figures (default: 5).

#' @param fig_height Numeric; height (in inches) of figures (default: 4).

#' @param keep_md Logical; keep the intermediate markdown file (default: FALSE).

#' @param md_extensions Character vector of additional markdown extensions to use (default: NULL).

#' @param pandoc_args Character vector of additional Pandoc command line arguments (default: NULL).

#'

#' @return An R Markdown output format object for use with `rmarkdown::render` (plain text output).

#' @export

methods_report_stream <- function(toc = FALSE,

                                  toc_depth = 3,

                                  fig_width = 5,

                                  fig_height = 4,

                                  keep_md = FALSE,

                                  md_extensions = NULL,

                                  pandoc_args = NULL) {

  # knitr options and hooks

  )

  # build pandoc args

  # table of contents

  # pandoc args

  # return output format

  )

}

# R-level wrappers replacing the former C++ exports in src/optim.cpp.

# These preserve backward compatibility for any code calling these functions

# directly as ona::accum_stanza_window(), ona::vector_to_ut(), etc.

#' Accumulate Stanza Window (directed, full-square output)

#'

#' For each row, accumulates co-occurrences over a backward stanza window.

#' Preserves directionality: the output columns are the n_codes x n_codes

#' adjacency matrix in column-major order, ground codes as rows and response

#' codes as columns, so 0-based column (j*n_codes + i) represents code i

#' (context/ground) co-occurring with code j (current row/response).

#' Returns a matrix with \code{n_codes²} columns (full square adjacency).

#'

#' Delegates to \code{\link[tma]{accumulate_stanza}(ordered = TRUE)}.

#'

#' @param df         A data frame of code columns (one row per utterance)

#' @param windowSize Number of prior rows in the window (default 1; use

#'   \code{Inf} for all prior rows in the stanza)

#' @param binary     Logical; binarise non-zero co-occurrences (default TRUE)

#' @return Numeric matrix with \code{nrow(df)} rows and \code{ncol(df)²} columns

#' @importFrom tma accumulate_stanza

#' @export

accum_stanza_window <- function(df, windowSize = 1, binary = TRUE) {

  )

}

#' Upper Triangle from Vector (numeric)

#'

#' Compute pairwise products \code{v[i] * v[j]} for all \code{i < j}.

#' Thin wrapper around \code{\link[rENA]{vector_to_ut}}.

#'

#' @param v Numeric vector or single-row matrix of code values

#' @return Numeric row vector of pairwise products (length choose_two(length(v)))

#' @export

vector_to_ut <- function(v) {

}

#' Least-squares node positions for directed ENA

#'

#' Thin wrapper around \code{\link[rENA]{directed_node_positions}}.

#'

#' @param line_weights Numeric matrix (units x connections)

#' @param points       Numeric matrix of rotated points (units x dims)

#' @param numDims      Number of dimensions

#' @return List with nodes, centroids, weights, points

#' @export

directed_node_positions <- function(line_weights, points, numDims) {

}

#' Directed node positions with ground+response rows combined

#'

#' Thin wrapper around

#' \code{\link[rENA]{directed_node_positions_with_ground_response_added}}.

#'

#' @param line_weights Numeric matrix (units x connections)

#' @param points       Numeric matrix of rotated points (units x dims)

#' @param numDims      Number of dimensions

#' @return List with nodes, centroids, weights, points

#' @export

directed_node_positions_with_ground_response_added <- function(line_weights,

                                                                points,

                                                                numDims) {

}

#' Normalize and optimize a directed (ordered) network accumulation

#'

#' Thin wrapper around \code{\link[rENA]{model}} that applies the ONA-specific

#' defaults: SVD rotation, zero-network exclusion from centering, and

#' center-to-origin post-processing.

#'

#' @param x     An \code{ena.ordered.set} produced by

#'   \code{\link[rENA]{accumulate}(ordered = TRUE)} or

#'   \code{tma::accumulate_contexts}.

#' @param ...   Additional arguments forwarded to \code{rENA::model}.

#' @param rotate.using Character. \code{"svd"} (default) for standard principal

#'   components rotation; \code{"mean"} for means rotation.

#' @param rotation.params Additional parameters for the rotation function

#'   (passed as \code{rotate_params} to \code{rENA::model}). Required with

#'   \code{rotate.using = "mean"}: \code{list(list(a, b))}, the two groups whose

#'   means define the first dimension, as logical vectors over the units or

#'   as unit names.

#' @param rotation.set Optional rotation to reuse instead of fitting one: a

#'   fitted \code{ena.ordered.set} (its \code{$rotation} is used), that

#'   \code{$rotation} list, or an rENA \code{ENARotationSet}. The data are

#'   normalised and centred as usual, projected with the supplied rotation

#'   matrix, and the supplied node positions are kept rather than

#'   re-optimised, so new units can be placed in an existing model's space.

#' @param center_to_origin Logical. When \code{TRUE} (default) the projected

#'   space is translated so the mean of all points is at the origin.

#'

#' @return An \code{ena.ordered.set} with calculated points and node positions.

#' @export

model <- function(

  x, ...,

  rotate.using     = "svd",

  rotation.params  = NULL,

  rotation.set     = NULL,

  center_to_origin = TRUE

) {

    }

  } else {

  }

    # Custom rotation, as in ONA 0.1.1: normalise and centre this data, then

    # project it with the supplied rotation and keep the supplied node

    # positions instead of re-optimising them. A fitted set's $rotation, the

    # fitted set itself, or an ENARotationSet all work; rENA::model() has no

    # equivalent path, so the steps are spelled out here.

    }

  } else {

    )

  }

}

# Accept the ways a rotation can be handed to model(): a fitted set (use its

# $rotation), that $rotation list, or an rENA ENARotationSet. Anything with a

# rotation.matrix qualifies; nodes and eigenvalues are optional.

as_rotation_set <- function(rotation.set) {

  }

  }

}

# Translate the projected space so the mean of all points sits at the origin,

# moving the node positions with it. Same as the center_to_origin step inside

# rENA::model(), for the custom-rotation path that does not go through it.

center_points_to_origin <- function(x) {

  }

}

###

#' ONA rotation by mean difference

#'

#' Computes a dimensional reduction (rotation) such that the first dimension

#' passes through the means of two groups. Subsequent dimensions use SVD on

#' the deflated data. Thin wrapper around \code{\link[rENA]{ena.rotate.by.mean}};

#' kept for backward compatibility with existing ONA scripts.

#'

#' @param x      A matrix or \code{ena.points} data table of ENA points

#'   (typically centered and normalized). Metadata columns are stripped

#'   automatically via \code{as.matrix}.

#' @param groups A list of length 2 (or more), each element being a length-2

#'   list \code{list(a, b)} where \code{a} and \code{b} are logical vectors or

#'   character unit IDs identifying the two groups.

#' @param codes  Character vector of code names corresponding to columns of

#'   \code{x}; used to label the rows of the returned rotation matrix.

#'

#' @return A list with \code{rotation}, \code{codes}, \code{eigenvalues}, and

#'   \code{node.positions = NULL}.

#' @export

###

ona.rotate.by.mean <- function(x, groups, codes) {

  # Construct a minimal enaset-compatible list so we can delegate to

  # rENA::ena.rotate.by.mean (means_rotation, in rENA's libena).

  )

}

.onLoad <- function(libname, pkgname) {

  ))

}

.onAttach <- function(libname, pkgname) {

}