# TODO: Document the names/items in each list that are returned

#' Create default parameters for a FIMS model

#'

#' @description

#' This function generates a Fisheries Integrated Modeling System (FIMS) model

#' configuration with detailed parameter specifications. This function takes a

#' high-level configuration `tibble` and generates the corresponding parameters

#' with default initial values and estimation settings required to build and run

#' the model.

#'

#' @details

#' The function processes the input `configurations` tibble, which defines the

#' modules for different model components (e.g., `"Selectivity"`, `"Recruitment"`).

#' For each module specified, it calls internal helper functions to create a

#' default set of parameters. For example, if a fleet's selectivity is configured

#' as `"Logistic"`, it generates initial values for `"inflection_point"` and

#' `"slope"`.

#'

#' @param configurations A tibble of model configurations. Typically created

#'   by [create_default_configurations()]. Users can modify this tibble

#'   to customize the model structure before generating default parameters.

#' @param data An S4 object. FIMS input data.

#' @return A `tibble` with default model parameters. The tibble has a nested

#'   structure with the following top-level columns.

#' \describe{

#'   \item{\code{model_family}:}{The specified model family (e.g.,

#'     "catch_at_age").}

#'   \item{\code{module_name}:}{The name of the FIMS module (e.g.,

#'     "Data", "Selectivity", "Recruitment", "Growth", "Maturity").}

#'   \item{\code{fleet_name}:}{The name of the fleet the module applies to. This

#'     will be `NA` for non-fleet-specific modules like "Recruitment".}

#'   \item{\code{data}:}{A list-column containing a `tibble` with detailed

#'     parameters. Unnesting this column reveals:

#'     \describe{

#'       \item{\code{module_type}:}{The specific type of the module (e.g.,

#'         "Logistic" for a "Selectivity" module).}

#'       \item{\code{label}:}{The name of the parameter (e.g., "inflection_point").}

#'       \item{\code{distribution_link}:}{The component the distribution module

#'         links to.}

#'       \item{\code{age}:}{The age the parameter applies to.}

#'       \item{\code{length}:}{The length bin the parameter applies to.}

#'       \item{\code{time}:}{The time step (i.e., year) the parameter applies to.}

#'       \item{\code{value}:}{The initial value of the parameter.}

#'       \item{\code{estimation_type}:}{The type of estimation (e.g.,

#'         "constant", "fixed_effects", "random_effects").}

#'       \item{\code{distribution_type}:}{The type of distribution (e.g., "Data",

#'         "process").}

#'       \item{\code{distribution}:}{The name of distribution (e.g.,

#'         "Dlnorm", `Dmultinom`).}

#'     }

#'   }

#' }

#' @export

#' @seealso

#' * [FIMSFrame()]

#' * [create_default_configurations()]

#' @examples

#' \dontrun{

#' # Load the example dataset and create a FIMS data frame

#' data("data1")

#' fims_frame <- FIMSFrame(data1)

#'

#' # Create default configurations

#' default_configurations <- create_default_configurations(fims_frame)

#'

#' # Create default parameters

#' default_parameters <- create_default_parameters(

#'   configurations = default_configurations,

#'   data = fims_frame

#' ) |>

#'   tidyr::unnest(cols = data)

#'

#' # Update selectivity parameters for survey1

#' updated_parameters <- default_parameters |>

#'   dplyr::rows_update(

#'     tibble::tibble(

#'       fleet_name = "survey1",

#'       label = c("inflection_point", "slope"),

#'       value = c(1.5, 2)

#'     ),

#'     by = c("fleet_name", "label")

#'   )

#'

#' # Do the same as above except, model fleet1 with double logistic selectivity

#' # To see required parameters for double logistic selectivity, run

#' # show(DoubleLogisticSelectivity)

#' parameters_with_double_logistic <- default_configurations |>

#'   tidyr::unnest(cols = data) |>

#'   dplyr::rows_update(

#'     tibble::tibble(

#'       module_name = "Selectivity",

#'       fleet_name = "fleet1",

#'       module_type = "DoubleLogistic"

#'     ),

#'     by = c("module_name", "fleet_name")

#'   ) |>

#'   create_default_parameters(

#'     data = fims_frame

#'   )

#' }

create_default_parameters <- function(

  configurations,

  data

) {

  # FIXME: use default values if there are no fleets info passed into the

  # function or a fleet is not present but it has data? Maybe we don't want the

  # latter because it could be that we want to drop a fleet from a model but we

  # don't want to alter the data?

  # Check if configurations is a nested tibble. If so, unnest configurations

  } else {

  }

  # Create fleet parameters

      )

    }

  ) |>

    # bind_rows now directly takes the list of tibbles from map()

  # Create recruitment parameters

  )

  # Create maturity parameters

  )

  # Create population parameters

  # Handle population parameters based on recruitment form

  )

  # Compile temps

  )

  # Merge with configuration_unnest

  ) |>

    ) |>

    ) |>

}

#' Create default parameters for a FIMS model

#' @description

#' This function creates a template for default parameters used in a Fisheries

#' Integrated Modeling System (FIMS) model. The template includes fields for

#' module name, module type, label, fleet name, population name, age, length,

#' time, value, estimation type, distribution type, and distribution.

#' @param n_parameters An integer specifying the number of parameters in the template.

#' @return

#' A tibble template for a FIMS model.

#' @noRd

#' @examples

#' FIMS:::create_default_parameters_template(n_parameters = 3)

create_default_parameters_template <- function(n_parameters = 1) {

  ) |>

}

#' Create default population parameters

#'

#' @description

#' This function sets up default parameters for a population module.

#' @details

#' The natural log of the initial numbers at age (`log_init_naa.value`) is set based on

#' unexploited recruitment and natural mortality.

#' @param unnested_configurations A tibble of model configurations. Typically created

#'   by the `create_default_configurations()`.

#' @param data An S4 object. FIMS input data.

#' @param log_rzero A numeric value representing the natural log of unexploited

#'   recruitment.

#' @return

#' A tibble of default population parameters, including initial numbers at

#' age and natural mortality rate.

#' @noRd

create_default_Population <- function(

  unnested_configurations,

  data,

  log_rzero

) {

  # Input checks

  # Check if log_rzero is numeric

    )

  }

  # Extract necessary values from data

  # Define age and year vectors needed for the rep() calls ===

  # Set natural mortality rate

  # Calculate initial numbers at age based on log_rzero and M_value

  # Create a list of default parameters

  ) |>

    # Add the module type, label, value, and estimation type

    ) |>

    ) |>

    )

}

#' Create default logistic parameters

#'

#' @description

#' This function sets up default parameters for a logistic function. There are

#' two specified parameters, the inflection point and slope.

#' @return

#' A tibble containing the default logistic parameters, with inflection_point and

#' slope values and their estimation status.

#' @noRd

create_default_Logistic <- function() {

  # Create a template for default parameters

    # Add the module type, label, value, and estimation type

    )

}

#' Create default double logistic parameters

#'

#' @description

#' This function sets up default parameters for a double logistic function.

#' There four specified parameters, two for the ascending and two for the

#' descending inflection points and slopes.

#' @return

#' A tibble containing the default double logistic parameters,

#' inflection_point_asc, slope_asc, inflection_point_desc, and slope_desc

#' values and their estimation status.

#' @noRd

create_default_DoubleLogistic <- function(module_name = NA_character_) {

      # TODO: Determine if inflection_point_desc should really be 4?

    )

}

#' Create default selectivity parameters

#'

#' @description

#' This function sets up default parameters for a selectivity module.

#' @param form A string specifying the desired form of selectivity. Allowable

#'   forms include `r toString(formals(create_default_selectivity)[["form"]])`

#'   and the default is

#'   `r toString(formals(create_default_selectivity)[["form"]][1])`.

#' @return

#' A tibble is returned with the default parameter values for the specified form

#' of selectivity.

#' @noRd

create_default_selectivity <- function(

  form = c("Logistic", "DoubleLogistic")

) {

  # Input checks

  # NOTE: All new forms of selectivity must be placed in the vector of default

  # arguments for `form` and their methods but be placed below in the call to

  # `switch`

  ) |>

    )

}

#' Create default fleet parameters

#'

#' @description

#' This function sets up default parameters for a fleet module. It compiles

#' selectivity parameters along with distributions for each type of data that

#' are present for the given fleet.

#'

#' @param unnested_configurations A tibble of model configurations. Typically

#'   created by the `create_default_configurations()`.

#' @param fleet_name A character. Name of the fleet.

#' @param data An S4 object. FIMS input data.

#' @return

#' A tibble with default parameters for the fleet.

#' @noRd

create_default_fleet <- function(unnested_configurations,

                                 current_fleet_name,

                                 data) {

  # Input checks

    ))

  }

    ))

  }

  # Create default selectivity parameters

  ) |>

    # Add fleet name

    )

  # Get types of data for this fleet from the data object

  # Get data likelihood distributions assigned for this fleet

  # Determine default fleet parameters based on types of data present

      )

      ) |>

      ),

      )

    ) |>

      )

  } else {

      )

  }

    ) |>

      )

      ),

      )

    ) |>

      )

  } else {

    ) |>

      )

  }

  # Compile all default parameters into a single list

  )

}

#' Create default maturity parameters

#'

#' @description

#' This function sets up default parameters for a maturity module.

#' @param form A string specifying the form of maturity (e.g.,

#' `"Logistic"`).

#' @return

#' A tibble containing the default maturity parameters.

#' @noRd

create_default_maturity <- function(

  unnested_configurations,

  data

) {

  # Input checks

    ))

  }

  # NOTE: All new forms of maturity must be placed in the vector of default

  # arguments for `form` and their methods but be placed below in the call to

  # `switch`

  ) |>

    # We don't have an option to input maturity data into FIMS, so the maturity

    # parameters aren't really estimable. The parameters should be constant for now.

    # See more details from https://github.com/orgs/NOAA-FIMS/discussions/944.

    )

}

#' Create default Beverton--Holt recruitment parameters

#'

#' @description

#' This function sets up default parameters for a Beverton--Holt recruitment

#' relationship. Parameters include the natural log of unfished recruitment,

#' the logit transformation of the slope of the stock--recruitment curve to

#' keep it between zero and one, and the time series of stock--recruitment

#' deviations on the natural log scale.

#' @param data An S4 object. FIMS input data.

#' @return

#' A tibble containing default recruitment parameters.

#' @noRd

create_default_BevertonHoltRecruitment <- function(data) {

  # Create default parameters for Beverton--Holt recruitment

  ) |>

    )

  ) |>

    )

  # TODO: Revisit the settings for log_r. Do we must set up log_r when

  # it is not random effect parameters?

  ) |>

      # TODO: should this be LogRecDev to match output?

    )

  ) |>

      # TODO: should this be LogRecDev to match output?

    )

  ) |>

    )

  ) |>

    )

}

#' Create default DnormDistribution parameters

#'

#' @description

#' This function sets up default parameters to calculate the density of a

#' normal distribution, i.e., `DnormDistribution`, module.

#' @param value A real number that is passed to `log_sd`. The default value is

#'   `0.1`.

#' @param data An S4 object. FIMS input data.

#' @param input_type A string specifying the input type. The available options

#'   are

#'   `r toString(formals(create_default_DnormDistribution)[["input_type"]])`.

#'   The default is

#'   `r toString(formals(create_default_DnormDistribution)[["input_type"]][1])`.

#' @return

#' A tibble of default parameters for Dnorm distribution.

#' @noRd

create_default_DnormDistribution <- function(

  value = 0.1,

  data,

  input_type = c("data", "process", "prior")

) {

  # Input checks

  # Create default parameters

  ) |>

    # Add the module type and label

    )

  # If input_type is 'process', add additional parameters

    ) |>

      ) |>

      )

    )

  }

}

#' Create default DlnormDistribution parameters

#'

#' @description

#' This function sets up default parameters to calculate the density of a

#' log-normal distribution, i.e., `DlnormDistribution`, module.

#' @param value Default value for `log_sd`.

#' @param data An S4 object. FIMS input data.

#' @param input_type A string specifying the input type. The available options

#'   are

#'   `r toString(formals(create_default_DlnormDistribution)[["input_type"]])`.

#'   The default is

#'   `r toString(formals(create_default_DlnormDistribution)[["input_type"]][1])`.

#' @return

#' A tibble of default parameters for Dlnorm distribution.

#' @noRd

create_default_DlnormDistribution <- function(

  value = 0.1,

  data,

  input_type = c("data", "process")

) {

  # Input checks

  # TODO: Determine if value can be a vector?

    ))

  }

  # Create the default list with log standard deviation

  ) |>

    # Add the module label and value

    )

  # Add additional parameters if input_type is "process"

      )

  }

    )

}

#' Create default recruitment parameters

#'

#' @description

#' This function sets up default parameters for a recruitment module.

#'

#' @param unnested_configurations A tibble of model configurations. Typically

#'   created by the `create_default_configurations()`.

#' @param data An S4 object. FIMS input data.

#' @return

#' A tibble with the default parameters for recruitment.

#' @noRd

create_default_recruitment <- function(

  unnested_configurations,

  data

) {

  # Input checks

    ))

  }

  # Create default parameters based on the recruitment form

  # NOTE: All new forms of recruitment must be placed in the vector of default

  # arguments for `form` and their methods but be placed below in the call to

  # `switch`

  )

      )

    )

        )

        # Create all combinations of the original rows and years

        ) |>

    }

  }

}

# This file contains many functions to reshape output from get_output()

# To remove the NOTE `no visible binding for global variable`

utils::globalVariables(c(

  "module_name", "module_id", "module_type",

  "parameter_min", "parameter_max", "label", "label_splits"

))

#' Reshape JSON estimates

#'

#' @description

#' This function processes the finalized FIMS JSON output and reshapes the

#' parameter estimates into a structured tibble for easier analysis and

#' manipulation.

#'

#' @param model_output A JSON object containing the finalized FIMS output as

#'   returned from `get_output()`, which is an internal function to each model

#'   family.

#' @return A tibble containing the reshaped parameter estimates.

reshape_json_estimates <- function(model_output) {

    )],

  )

  # Process the module parameters

        )

    ],

      )

    )

  ) |>

  # Process the fleet-level information

      )

    ) |>

    ) |>

        ) |>

    ) |>

    ) |>

    ) |>

    # Remove column ids that are not currently needed

      )

    ) |>

    ) |>

  # Process the data components

  # TODO: Data component needs actual uncertainty instead of 0

    ) |>

  # Process the density components

  # This is done above for fleet information but we will need to do it for

  # parameter-level information once we have a link to the parameter id

    ) |>

  # Process the population data

    ) |>

    # TODO: Think about these ids when we have more than one population

      )

    ) |>

  # TODO: Bring in TMB estimates

  # TODO: Change some column names

  # Bring everything together

    # density_information,

  ) |>

    )

}

#' Reshape TMB estimates

#'

#' @description

#' This function processes the TMB std and reshapes them into a structured

#' tibble for easier analysis and manipulation.

#'

#' @param obj An object returned from [TMB::MakeADFun()].

#' @param sdreport An object of the `sdreport` class as returned from

#'   [TMB::sdreport()].

#' @param opt An object returned from an optimizer, typically from

#'   [stats::nlminb()], used to fit a TMB model.

#' @param parameter_names A character vector of parameter names. This is used to

#'   identify the parameters in the `std` object.

#' @return A tibble containing the reshaped estimates (i.e., parameters and

#' derived quantities).

reshape_tmb_estimates <- function(obj,

                                  sdreport = NULL,

                                  opt = NULL,

                                  parameter_names) {

  # Outline for the estimates table

    # The FIMS Rcpp module

    # The unique ID of the module

    # The name of the parameter or derived quantity

    # The unique ID of the parameter

    # The initial value use to start the optimization procedure

    # The estimated parameter value, which would be the MLE estimate or the value

    # used for a given MCMC iteration

    # Estimated uncertainty, reported as a standard deviation

    # The pointwise log-likelihood used for the test or holdout data

    # The gradient component for that parameter, NA for derived quantities

  )

    # Number of rows for derived quantities: based on the difference

    # between the total number of rows in std and the length of parameter_names.

    # Create a tibble with the data from the std, and then apply transformations.

        # Use obj[["env"]][["parameters"]][["p"]] as this will return both initial

        # fixed and random effects while obj[["par"]] only returns initial fixed

        # effects

        ),

        )

      )

  } else {

      )

  }

    # Split labels and extract module, id, label, and parameter id

    # TODO: the code could be simplified using tidyr::separate_wider_*().

    # However, doing so would require avoiding pre-specification of these columns

    # in the estimates_outline tibble. Consider updating the code if we decide

    # not to create the `estimates_outline` tibble in advance.

    ) |>

}

#' Converts a dimension-folder section into a tibble

#'

#' This is an internal helper function that processes a complex list

#' structure read in from a json file containing dimensionality information, a

#' name, and either explicit values with a type or estimated values with

#' uncertainty.

#'

#' @param section A section of the json file represented as a list.

#' @return

#' A tibble containing the json output in a formatted structure listing the

#' dimensionality as columns rather than just row and column lengths.

#' @noRd

#'

#' @examples

#' # A simple example for a value with uncertainty:

#' section_derived <- list(

#'   name = "derived_quantity_name",

#'   dimensionality = list(

#'     unit = "m", symbol = "L", scale = 1.0, type = "length"

#'   ),

#'   value = 10.5,

#'   uncertainty = 0.5

#' )

#' dimension_folded_to_tibble(section_derived)

dimension_folded_to_tibble <- function(section) {

  }

  }

        # TODO: Need to rename

      ) |>

      ) |>

  } else {

      )

  }

}

#' Covert the dimension information from a FIMS json output into a tibble

#'

#' Dimensions in the json output are stored as a list of length two, with the

#' header information containing the name of the dimension and the dimensions

#' containing integers specifying the length for each dimension. The result

#' helps interpret how the FIMS output is structured given it is dimension

#' folded into a single vector in the json output.

#'

#' @details

#' The dimension index is returned not the actual year of the model. For

#' example, if the model starts in year 1900, then year_i of 1, which is what

#' is returned from this function will need to map to 1900 and that will need

#' to be done externally.

#' This function will accommodate dimensions of year-1 and year+1 where the

#' indexing of the former will start at 2 instead of 1.

#' @param data A list containing the header and dimensions information from a

#'   FIMS json output object.

#' @return

#' A tibble containing ordered rows for each combination of the dimensions.

#' @noRd

#' @examples

#' dummy_dimensions <- list(

#'   header = list("n_years", "n_ages"),

#'   dimensions = list(30L, 12L)

#' )

#' dimensions_to_tibble(dummy_dimensions)

#' # Example with n_years+1

#' dummy_dimensions <- list(

#'   header = list("n_years+1", "n_ages"),

#'   dimensions = list(31L, 12L)

#' )

#' dimensions_to_tibble(dummy_dimensions)

dimensions_to_tibble <- function(data) {

  #' Replace headers like "n_years" with "year_i".

  #' Example: "n_ages+1" with "age_i"

  #' This matches names starting with 'n' (with or without an underscore)

  #' and shortens them to a simple indexed form.

    # When the header is NULL

  }

    # When the dimensions are na because there is no associated indexing

  }

  # Accommodate any -1 by creating a different start value

  # Create the returned tibble by first sequencing from 1:n for each dimension

}

#' Convert the density component information into a tibble

#'

#' The density component information is stored in a single column but contains

#' a list of five elements. This function helps to widen that list into a

#' tibble and expand the `values`, `expected_values`, and `observed_values`

#' into long columns because they are all of the same length.

#'

#' @param data A list of lists from the json output that is titled

#'   `density_component`.

#' @return

#' A tibble is returned.

#' @noRd

#'

#' @examples

#' dummy_density <- list(

#'   name = "lpdf_vec",

#'   lpdf_value = -102.079,

#'   values = list(

#'     -1.39915, -2.44735, -2.93024, -3.21848, -2.95698, -3.51745

#'   ),

#'   expected_values = list(

#'     5.0854, 6.13354, 6.61636, 6.90467, 6.64311, 7.20302

#'   ),

#'   observed_values = list(

#'     161.646, 461.089, 747.29, 996.971, 767.548, 1343.86

#'   )

#' )

#' density_to_tibble(dummy_density)

#' @noRd

density_to_tibble <- function(data) {

}

# To remove the WARNING

# no visible binding for global variable

utils::globalVariables(c(

  "type", "name", "value", "unit", "uncertainty",

  "timing", "age", "length", "year",

  # Used in initialize_comp dplyr code

  "valid_n"

))

#' Initialize a generic module

#'

#' @description

#' Initializes a generic module by setting up its fields based on the provided

#' `module_name`.

#' @param parameters A tibble. Contains parameters and modules required for

#'   initialization.

#' @param data An S4 object. FIMS input data.

#' @param module_name A character. Name of the module to initialize (e.g.,

#'   "Population" or "Fleet").

#' @param fleet_name A character. Name of the fleet to initialize. If not

#'   specified, the module will be initialized without fleet-specific data.

#' @return

#' The initialized module as an object.

#' @noRd

initialize_module <- function(parameters, data, module_name, fleet_name = NA_character_) {

    # Using !! to unquote the variables

  }

    # Combine module_type and module_name into a single string

        # Replace NAs with ""

      )

    ) |>

    ))

  }

    # Remove certain fields for the Fleet module

    ))

      # Assign each value to the corresponding position in the parameter vector

      )

      # Set the estimation information for the entire parameter vector

    } else {

        # Right now we can also remove n_lengths because the default is 0

      ))

    }

    ))

  }

  # Populate fields based on common and specific settings

  # TODO:

  # - Population interface

  #   - Update the Population interface to consistently use n_ages and n_years,

  #     as done in the S4 data1 object.

  #     Update as needed.

  #   - Add n_fleets to data1. Should n_fleets include both

  #     fishing and survey fleets? Currently, data1@fleets equals 1.

  # - Fleet

  #   - Reconsider exposing `log_expected_index` and

  #     `agecomp_proportion` to users. Their IDs are linked with

  #     index and agecomp distributions. No input values are required.

  )

  )

  )

          # Or we can use get_n_fleets(data),

        )

      )

      )

      })

    } else {

      )

    }

  }

}

# TODO: Determine the relationship between distributions and the

# recruitment module, and implement the appropriate logic to retrieve

# distribution information.

#' Initialize a distribution module

#'

#' @description

#' Initializes a distribution module by setting up its fields based on the

#' distribution name and type. Supports both "data" and "process" types.

#' @param module_input A list. Contains parameters for initializing the

#'   distribution.

#' @param distribution_name A character. Name of the distribution to initialize.

#' @param distribution_type A character. Type of distribution, either "data" or

#'   "process".

#' @param linked_ids A vector. Named vector of linked IDs required for the

#'   distribution, such as data_link and fleet_link for setting up index

#'   distribution.

#' @rdname initialize_module

#' @return

#' The initialized distribution module as an object.

#' @noRd

initialize_distribution <- function(

  module_input,

  distribution_name,

  distribution_type = c("data", "process"),

  linked_ids

) {

  # Input checks

  # Check if distribution_name is provided

  }

  # Validate module_input

  }

  # Validate distribution_type as "data" or "process"

  # Validate linked_ids as a named vector with required elements for "data" type

  ) {

    )

  }

  # Get distribution value and initialize the module