% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/methods.R, R/methods_SE.R
\docType{methods}
\name{rotate_dimensions}
\alias{rotate_dimensions}
\alias{rotate_dimensions,spec_tbl_df-method}
\alias{rotate_dimensions,tbl_df-method}
\alias{rotate_dimensions,tidybulk-method}
\alias{rotate_dimensions,SummarizedExperiment-method}
\alias{rotate_dimensions,RangedSummarizedExperiment-method}
\title{Rotate two dimensions (e.g., principal components) of an arbitrary angle}
\usage{
rotate_dimensions(
  .data,
  dimension_1_column,
  dimension_2_column,
  rotation_degrees,
  .element = NULL,
  of_samples = TRUE,
  dimension_1_column_rotated = NULL,
  dimension_2_column_rotated = NULL,
  action = "add"
)

\S4method{rotate_dimensions}{spec_tbl_df}(
  .data,
  dimension_1_column,
  dimension_2_column,
  rotation_degrees,
  .element = NULL,
  of_samples = TRUE,
  dimension_1_column_rotated = NULL,
  dimension_2_column_rotated = NULL,
  action = "add"
)

\S4method{rotate_dimensions}{tbl_df}(
  .data,
  dimension_1_column,
  dimension_2_column,
  rotation_degrees,
  .element = NULL,
  of_samples = TRUE,
  dimension_1_column_rotated = NULL,
  dimension_2_column_rotated = NULL,
  action = "add"
)

\S4method{rotate_dimensions}{tidybulk}(
  .data,
  dimension_1_column,
  dimension_2_column,
  rotation_degrees,
  .element = NULL,
  of_samples = TRUE,
  dimension_1_column_rotated = NULL,
  dimension_2_column_rotated = NULL,
  action = "add"
)

\S4method{rotate_dimensions}{SummarizedExperiment}(
  .data,
  dimension_1_column,
  dimension_2_column,
  rotation_degrees,
  .element = NULL,
  of_samples = TRUE,
  dimension_1_column_rotated = NULL,
  dimension_2_column_rotated = NULL,
  action = "add"
)

\S4method{rotate_dimensions}{RangedSummarizedExperiment}(
  .data,
  dimension_1_column,
  dimension_2_column,
  rotation_degrees,
  .element = NULL,
  of_samples = TRUE,
  dimension_1_column_rotated = NULL,
  dimension_2_column_rotated = NULL,
  action = "add"
)
}
\arguments{
\item{.data}{A `tbl` (with at least three columns for sample, feature and transcript abundance) or `SummarizedExperiment` (more convenient if abstracted to tibble with library(tidySummarizedExperiment))}

\item{dimension_1_column}{A character string. The column of the dimension 1}

\item{dimension_2_column}{A character string. The column of the dimension 2}

\item{rotation_degrees}{A real number between 0 and 360}

\item{.element}{The name of the element column (normally samples).}

\item{of_samples}{A boolean. In case the input is a tidybulk object, it indicates Whether the element column will be sample or transcript column}

\item{dimension_1_column_rotated}{A character string. The column of the rotated dimension 1 (optional)}

\item{dimension_2_column_rotated}{A character string. The column of the rotated dimension 2 (optional)}

\item{action}{A character string. Whether to join the new information to the input tbl (add), or just get the non-redundant tbl with the new information (get).}
}
\value{
A tbl object with additional columns for the reduced dimensions. additional columns for the rotated dimensions. The rotated dimensions will be added to the original data set as `<NAME OF DIMENSION> rotated <ANGLE>` by default, or as specified in the input arguments.

A tbl object with additional columns for the reduced dimensions. additional columns for the rotated dimensions. The rotated dimensions will be added to the original data set as `<NAME OF DIMENSION> rotated <ANGLE>` by default, or as specified in the input arguments.

A tbl object with additional columns for the reduced dimensions. additional columns for the rotated dimensions. The rotated dimensions will be added to the original data set as `<NAME OF DIMENSION> rotated <ANGLE>` by default, or as specified in the input arguments.

A tbl object with additional columns for the reduced dimensions. additional columns for the rotated dimensions. The rotated dimensions will be added to the original data set as `<NAME OF DIMENSION> rotated <ANGLE>` by default, or as specified in the input arguments.

A `SummarizedExperiment` object

A `SummarizedExperiment` object
}
\description{
rotate_dimensions() takes as input a `tbl` formatted as | <DIMENSION 1> | <DIMENSION 2> | <...> | and calculates the rotated dimensional space of the transcript abundance.
}
\details{
`r lifecycle::badge("maturing")`

This function to rotate two dimensions such as the reduced dimensions.

Underlying custom method:
	rotation = function(m, d) {
		// r = the angle
		// m data matrix
   r = d * pi / 180
   ((dplyr::bind_rows(
	  c(`1` = cos(r), `2` = -sin(r)),
	  c(`1` = sin(r), `2` = cos(r))
  ) %>% as_matrix) %*% m)
 }
}
\examples{

counts.MDS =
 tidybulk::se_mini |>
 identify_abundant() |>
 reduce_dimensions( method="MDS", .dims = 3)

counts.MDS.rotated =  rotate_dimensions(counts.MDS, `Dim1`, `Dim2`, rotation_degrees = 45, .element = sample)


}
