R/get_allocations.R

In Ingenuity-Inc/artlookR: Work with artlook data

#' artlookR allocations data
#'
#' The \code{allocations} table in artlookR stores information about resources (i.e., \code{resourceable_type}s) that have been
#' allocated to schools, organizations, programs, partnerships, and profiles (i.e., \code{allocateable_type}s).
#' @usage get_allocations(
#'
#'     comm_name = NULL
#'
#'     school_org_prog_part = c("Organization", "Partnership", "Profile", "Program", "School")
#'
#'     type_of_resource = c("Approach","Discipline","EngagementType","FinancialAssistanceType","FundingType","Governance",
#'     "IdentityFrequency","IntegrationType","LeadershipCharacteristic","Obstacle","OutcomeType","ProgramType","ScheduleType",
#'     "SpaceType","Standard","SubDiscipline")
#'
#'     table_of_resource = c("approaches","disciplines","engagement_types","financial_assistance_types","funding_types",
#'     "governances","identity_frequencies","integration_types","leadership_characteristics","obstacles","outcome_types",
#'     "program_types","schedule_types","space_types","standards","sub_disciplines")
#'
#' )
#' @param comm_name The community name as recognized by artlookR
#' @param school_org_prog_part The \code{allocateable_type} to filter the allocations table by. In other words, what type of entity should the data you
#' download apply *to*?
#' @param type_of_resource The \code{resourceable_type} to filter the allocations table by. In other words, what type of resource is being provided to
#' the identified \code{school_org_prog_part}?
#' @param table_of_resource The meta-data table to which the \code{resourceable_type} must be connected to make sense of it. In other words, the
#' table_of_resource *must* correspond to the type_of_resource or the description of the \code{resourceable_type} will be wrong.
#'
#' The contents of these meta-data tables can be separately checked with a call to an artlookR meta-data function that starts with *meta_()*
#' (e.g., \code{meta_approaches}). Whether they are stored in the public schema or in community-specific schema impacts the call to the meta-data
#' function, but not the call to the table itself in this \code{get_allocations} function.
#'   * **Public schema:** table_of_resource <-> type_of_resource (\code{meta-data function}):
#'     * disciplines <-> Discipline (\code{meta_disc(...)})
#'     * engagement_types <-> EngagementType (\code{meta_engage(...)})
#'     * integration_types <-> IntegrationType (\code{meta_integration(...)})
#'     * program_types <-> ProgramType (\code{meta_prog(...)})
#'     * schedule_types <-> ScheduleType (\code{meta_schedule(...)})
#'     * space_types <-> SpaceType (\code{meta_space(...)})
#'     * sub_disciplines <-> SubDiscipline (\code{meta_subdisc(...)})
#'   * **Community schema:** table_of_resource <-> type_of_resource (\code{meta-data function}):
#'     * approaches <-> Approach (\code{meta_approaches(comm_name)})
#'     * financial_assistance_types <-> FinancialAssistanceType (\code{meta_financial_assistance_types(comm_name)})
#'     * funding_types <-> FundingType (\code{meta_funding(comm_name)})
#'     * governances <-> Governance (\code{meta_governances(comm_name)})
#'     * identity_frequencies <-> IdentityFrequency (\code{meta_identity_frequencies(comm_name)})
#'     * leadership_characteristics <-> LeadershipCharacteristic (\code{meta_leadership_characteristics(comm_name)})
#'     * obstacles <-> Obstacle (\code{meta_obstacles(comm_name)})
#'     * outcome_types <-> OutcomeType (\code{meta_outcome(comm_name)})
#'     * standards <-> Standard (\code{meta_standards(comm_name)})
#' @return A tibble / data frame with the following columns:
#'   * allocateable_type: should be only the value provided in \code{school_org_prog_part}
#'   * allocateable_id: the artlookR ID for the school/org/partnership/program/profile to which the resource is allocated
#'   * resourceable_type: should only be the value provided in \code{type_of_resource}
#'   * resourceable_id: the artlookR ID for the resource
#'   * school_year_id: artlookR school year in which the resource was allocated
#'   * tag: where applicable (e.g., SubDiscipline in Schools can be tagged as in_school, out_of_school, or both)
#'   * other_text: where applicable
#'   * name: the text name (level) of the resource
#' @details * You will need to run the \code{connection.R} script and create a connection object named \code{myconn} for this script to run.
#' * There is a variable in the allocations table called \code{focus}, which in years 2018-19 and earlier used to indicate the focus area for a partner's programs.
#' This variable is excluded as an output from this data pull because it became obsolete in 2019-20. For data prior to 2019-20, a separate data pull must be run to
#' access the data stored in the \code{focus} variable. There may be some data stored in this field even after 2019-20 because it was carried over as part of a partner
#' copying a program from a prior year where there was info in the field. In such cases, the data in this field should not be used.
#'
#' @examples
#' get_allocations("chicago", "Program", "ProgramType", "program_types")
#' get_allocations("houston", "Organization", "LeadershipCharacteristic", "leadership_characteristics")
#'
#' # does not work because ProgramTypes are not allocated to Schools
#' get_allocations("chicago", "School", "ProgramType", "program_types")
#' @export

get_allocations <- function(comm_name, school_org_prog_part, type_of_resource, table_of_resource) {

  community_specific_tables <- c("approaches",
                                 "funding_types",
                                 "financial_assistance_types",
                                 "governances",
                                 "identity_frequencies",
                                 "leadership_characteristics",
                                 "obstacles",
                                 "outcome_types",
                                 "standards")

  schema_to_query <- if_else(table_of_resource %in% community_specific_tables, comm_name, "public")

  temp <- tbl(myconn, in_schema(comm_name, "allocations")) %>%
    filter(state == "approved",
           allocateable_type == school_org_prog_part,
           resourceable_type == type_of_resource) %>%
    select(-c(created_at, updated_at, state, focus)) %>%
    left_join(tbl(myconn, in_schema(schema_to_query, table_of_resource)) %>%
                select(id,
                       name),
              by=c("resourceable_id" = "id")) %>%
    collect() %>%
    select(-id) %>%
    mutate(comm_name = comm_name) #used when compiling across communities - not needed otherwise but still here
  #janitor::remove_empty("cols", quiet = T)

  temp
}