Package 'sonata'

Title: Interagir com MozART 2.0
Description: Provides a set of utilities and functions for connecting, querying, and analyzing data from the Mozambique MozART 2.0 database.
Authors: Joe Lara [aut, cre], Karishma Srikanth [aut], Baboyma Kagniniwa [aut], Timothy Essam [aut]
Maintainer: Joe Lara <[email protected]>
License: MIT + file LICENSE
Version: 1.0.0
Built: 2026-05-15 06:24:54 UTC
Source: https://github.com/usaid-mozambique/sonata

Help Index

Calcular a idade do cliente

Description

Calcular a idade do cliente

Usage

calc_age_var(
  df,
  birth_date = "birthdate",
  ref_date = Sys.Date(),
  variable_name = "age"
)

Arguments

df

Quadro de dados contendo a data de nasicmento do cliente
birth_date

Coluna do quadro de dados utilizada para introduzir a data de nascimento do cliente (default = birthdate)
ref_date

Data de referência para calcular a idade do cliente (default = Sys.Date())
variable_name

Nome da variável que será criada no quadro de dados com a idade do cliente em anos (default = 'age')

Value

Quadro de dados com a idade do cliente em anos

Examples

## Not run: 

 df <- calc_age_var(df)
## End(Not run)

Query levantamentos TARV

Description

calc_arv_pickups() devolve uma listagem dos levantamentos ARV feito during um período especificado pelo utilizador

Usage

calc_arv_pickups(
  con,
  enddate,
  opendate,
  arv_pickup_source = "FILA",
  filter_by_location = TRUE,
  location_uuid = "e5f01eee-2392-49b4-a5bf-5cf593fc8f21"
)

Arguments

con

Ligação à base de dados MozART 2.0
enddate

Data do fecho do período (introduzir como “AAAA-MM-DD”)
opendate

Data da abertura do período (introduzir como “AAAA-MM-DD”)
arv_pickup_source

Fonte de levantamento de ARV. Opções são "FILA", "Reception", "Any". Default é "FILA

  • "FILA" por defeito, devolve levantamentos documentados na FILA ou fonte alternativa da farmácia

  • "Reception" devolve levantamentos documentados na Ficha de Seguimento, Mapa dos Levantamentos

  • "Any" devolve todos levantamentos

filter_by_location

FALSE por defeito

  • TRUE executa sobre uma US específica

  • FALSE executa sobre todas as US contidas no MozART 2.0

location_uuid

location_uuid da US a filtrar quando filter_by_location é definido como TRUE

Value

Um quadro de dados contendo uma listagem individual dos levantamentos TARV

Examples

## Not run: 

 df <- calc_arv_pickups(
          con
          opendate = '2024-06-20',
          enddate = '2024-09-20',
          arv_pickup_source = "FILA",
          filter_by_location = TRUE,
          location_uuid = location_meripo)
## End(Not run)

Query consultas clínicas HIV

Description

calc_consults() devolve uma listagem das consultas clínicas do HIV realizadas por um grupo de clientes definido pelo utilizador (activos em TARV ou todos clientes)

Usage

calc_consults(
  con,
  client_status = "All",
  defaulter_tolerance = 28,
  opendate = NULL,
  enddate = Sys.Date(),
  filter_by_location = TRUE,
  location_uuid = "e5f01eee-2392-49b4-a5bf-5cf593fc8f21"
)

Arguments

con

Ligação à base de dados MozART 2.0
client_status

Estado do cliente em TARV

  • "All", por defeito, devolve todos clientes tendo realizado consultas clínicas

  • "Active", devolve apenas os clientes activos em TARV

defaulter_tolerance

Número de dias de tolerância antes dos faltosos serem considerados inactivos (abandonos)

  • "28" por defeito

opendate

Data da abertura do período (introduzir como “AAAA-MM-DD”)
enddate

Data do fecho do período usado para avialar o estado activo do client

  • "Sys.Date" Por defeito

  • Data customizada em formato (introduzir como “AAAA-MM-DD”)

  • Número customizado (por exemplo "59" na definição de MISAU)

filter_by_location

Se TRUE, o query corre sobre uma unidade sanitária específica. Se FALSE, o query corre sobre todas as unidade sanitária contidas no MozART 2.0
location_uuid

location_uuid da unidade sanitária a filtrar quando filter_by_location é definido como TRUE

Value

Um quadro de dados contendo uma listagem das consultas clínicas HIV realizadas

Examples

## Not run: 
 # Caso de uso simples executado sobre todas US
 df <- calc_consults(con)

 # Caso de uso de activos, tolerância 59 dias, executado sobre uma US
 df <- calc_consults(
          con,
          enddate = '2024-09-20',
          client_status = "Active",
          defaulter_tolerance = 59,
          filter_by_location = TRUE,
          location_uuid = 'e3eb1a1b-be07-4af2-9360-5d7046910576')

 # Caso de uso de activos, limitando as consultas a 2022 para frente
 df <- calc_consults(
          con,
          client_status = "Active",
          enddate = '2024-09-20',
          opendate = '2022-01-10',
          filter_by_location = FALSE)
## End(Not run)

Query clientes activos em TARV

Description

calc_tx_active() devolve uma listagem dos clientes activos em TARV a partir de uma data definida pelo utilizador

Usage

calc_tx_active(
  con,
  enddate,
  defaulter_tolerance = 28,
  filter_by_location = TRUE,
  location_uuid = "e5f01eee-2392-49b4-a5bf-5cf593fc8f21"
)

Arguments

con

Ligação à base de dados MozART 2.0
enddate

Data de fecho do período (introduzir como “AAAA-MM-DD”)
defaulter_tolerance

Número de dias de tolerância antes dos faltosos serem considerados inactivos (abandonos)
filter_by_location

Lógico. Se TRUE, o query corre sobre uma unidade sanitária específica. Se FALSE, o query corre sobre todas as unidade sanitária contidas na base de dados
location_uuid

location_uuid da unidade sanitária a filtrar quando filter_by_location é definido como TRUE

Value

Um quadro de dados contendo uma listagem individual dos pacientes activos em TARV

Examples

## Not run: 

#' Caso de uso simples executado sobre uma US, tolerância de 28 dias
df <- calc_tx_active(con,
                     enddate = '2024-09-20',
                     defaulter_tolerance = 28,
                     filter_by_location = TRUE,
                     location_uuid = 'e3eb1a1b-be07-4af2-9360-5d7046910576')

#' Caso de uso simples executado paras todas US, tolerância de 59 dias
df <- calc_tx_active(con,
                     enddate = '2024-09-20',
                     defaulter_tolerance = 59,
                     filter_by_location = FALSE)
## End(Not run)

Query novos inícios ao TARV

Description

calc_tx_new() devolve uma listagem dos clientes que iniciaram o TARV durante um período de tempo especificado pelo utilizador

Usage

calc_tx_new(
  con,
  opendate,
  enddate,
  filter_by_location = TRUE,
  location_uuid = "e5f01eee-2392-49b4-a5bf-5cf593fc8f21"
)

Arguments

con

Ligação à base de dados MozART 2.0
opendate

Data de abertura do período (introduzir como “AAAA-MM-DD”)
enddate

Data de fecho do período (introduzir como “AAAA-MM-DD”)
filter_by_location

Se TRUE, o query corre sobre uma unidade sanitária específica. Se FALSE, o query corre sobre todas as unidade sanitária contidas no MozART 2.0
location_uuid

location_uuid da unidade sanitária a filtrar quando filter_by_location é definido como TRUE

Value

Um quadro de dados contendo uma listagem individual dos pacientes iniciados em TARV

Examples

## Not run: 

 # Caso de uso simples executado sobre todas US
 df <- calc_tx_new(con,
                   opendate = "2024-06-21",
                    enddate = "2024-09-20")

 # Caso de uso simples executado sobre uma US
df <- calc_tx_new(con,
                  opendate = "2024-06-21",
                  enddate = "2024-09-20",
                  filter_by_location = TRUE,
                  location_uuid = 'e3eb1a1b-be07-4af2-9360-5d7046910576')
          
## End(Not run)

Referência: location_uuid

Description

Source: R/data.R.

Usage

data(data_location_lookup)

Format

Quadro de dados com variáveis:

location_uuid

código único de identificação do local

datim_id

Código único de identificação do Datim do local

sisma_id

Código único de identificação do SISMA do local

province

Província onde se situa o local

district

Distrito em que o local está situado

datim_name

Nome do local no Datim

mozart_name

Nome do local no MozART

Referência: data_observation_lookup

Description

Source: R/data.R.

Usage

data(data_observation_lookup)

Format

Quadro de dados com variáveis:

concept_id

Identificador do conceito

concept_name

Nome do conceito

Referência: data_type_id_lookup

Description

Source: R/data.R.

Usage

data(data_type_id_lookup)

Format

Quadro de dados com variáveis:

id

id

table_name

Nome do formulário específico (por exemplo, form)

column_name

Código único do formulário específico (por exemplo, form_id)

id_type_lookup

Código numérico do formulário específico (por exemplo, 60)

id_type_desc

Descrição do formulário específico - inglês

id_type_lookup_pt

Descrição do formulário específico - português

notes

Notas

Passar de forma segura credenciais e estabelecer coneção ao MozART 2.0

Description

mysql_connection() cria uma ligação com o MozART 2.0 com base num conjunto de credenciais armazenadas de forma segura e definidas pelo utilizador

Usage

mysql_connection(
  db_name,
  db_user,
  db_pass,
  db_host = "localhost",
  db_port = 3306
)

Arguments

db_name

Nome da base de dados
db_user

Utilizador da base de dados
db_pass

Senha da base de dados
db_host

Host da base de dados
db_port

Porta da base de dados

Value

Uma conexão ao MozART 2.0

Examples

## Not run: 

con <- mysql_connection(db_name = acct_db$dbname,
                        db_user = acct_db$username,
                        db_pass = acct_db$password,
                        db_host = acct_db$host,
                        db_port = acct_db$port)
## End(Not run)

Detectar transição etária

Description

project_age_out() devolve idades projectadas bem como colunas para indicar transição da idade pediátrica para adulta e transição entre faixas etárias de 5 anos

Usage

project_age_out(df, ref_date)

Arguments

df

Quadro de dados contendo a data de nasicmento do cliente
ref_date

Data de referência para calcular a idade projectada do cliente

Value

Quadro de dados com variáveis idade, idade projectada, faixa etária, faixa etária projectada, e colunas que indicam casos de transição etária

Examples

## Not run: 

#' Caso de uso simples projectando idades ate o início do ano 2026
 df <- project_age_out(df
                       ref_date = "2026-01-01")
## End(Not run)

Query uuids dos activos no TARV

Description

pull_active_uuid() devolve um vector dos uuid's dos clientes activos em TARV a partir de uma data definida pelo utilizador

Usage

pull_active_uuid(
  con,
  enddate,
  defaulter_tolerance = 28,
  filter_by_location = TRUE,
  location_uuid = "e5f01eee-2392-49b4-a5bf-5cf593fc8f21"
)

Arguments

con

Ligação à base de dados MozART 2.0
enddate

Data de fecho do período (introduzir como “AAAA-MM-DD”)
defaulter_tolerance

Número de dias de tolerância antes dos faltosos serem considerados inactivos (abandonos)
filter_by_location

Lógico. Se TRUE, o query corre sobre uma unidade sanitária específica. Se FALSE, o query corre sobre todas as unidade sanitária contidas na base de dados
location_uuid

location_uuid da unidade sanitária a filtrar quando filter_by_location é definido como TRUE

Value

pull_active_uuid devolve um vector contendo os patient_uuid unicos dos pacientes activos em TARV

Examples

## Not run: 

#' Caso de uso simples executado sobre uma US, tolerância de 28 dias
 df <- pull_active_uuid(
          con,
          enddate = '2024-09-20',
          defaulter_tolerance = 28)
## End(Not run)

Query uuids para activos ou novos inícios ao TARV

Description

Esta função funciona como um invólucro para devolver UUIDs de clientes com base no seu estado (“Active” ou “New”). Ela chama pull_active_uuid() para clientes ativos ou pull_new_uuid() para novos clientes, dependendo do argumento client_status.

Usage

pull_client_uuid(
  con,
  opendate = NULL,
  enddate = Sys.Date(),
  client_status = "Active",
  defaulter_tolerance = 28,
  filter_by_location = TRUE,
  location_uuid = "e5f01eee-2392-49b4-a5bf-5cf593fc8f21"
)

Arguments

con

Ligação à base de dados MozART 2.0
opendate

Data de abertura do período (introduzir como “AAAA-MM-DD”)
enddate

Data de fecho do período (introduzir como “AAAA-MM-DD”)
client_status

Character. Defines which UUIDs to pull. Options: "Active" (default) to retrieve active clients, "New" to retrieve new clients.
defaulter_tolerance

Numeric. Number of days used to define a defaulter when client_status = "Active". Defaults to 28 days.
filter_by_location

Se TRUE, o query corre sobre uma unidade sanitária específica. Se FALSE, o query corre sobre todas as unidade sanitária contidas no MozART 2.0
location_uuid

location_uuid da unidade sanitária a filtrar quando filter_by_location é definido como TRUE

Value

Um vector de UUIDs de clientes que correspondem aos critérios especificados.

Examples

## Not run: 
# Caso de uso simples executado sobre todas US
active_uuids <- pull_client_uuid(con,
                                 enddate = "2024-09-20",
                                 filter_by_location = FALSE)

# Devolver novos clientes a partir de uma data de abertura especificada
new_uuids <- pull_client_uuid(con,
                              opendate = "2024-01-01",
                              enddate = "2024-09-20",
                              client_status = "New")

# Devolver clientes activos para uma US específica com uma tolerância de 59 dias
active_uuids <- pull_client_uuid(con,
                                 enddate = "2024-09-20",
                                 defaulter_tolerance = 59,
                                 location_uuid = "custom-location-uuid")
## End(Not run)

Query uuids dos novos inícios ao TARV

Description

pull_new_uuid() devolve um vector dos uuid's dos clientes activos em TARV a partir de uma data definida pelo utilizador

Usage

pull_new_uuid(
  con,
  opendate,
  enddate,
  filter_by_location = TRUE,
  location_uuid = "e5f01eee-2392-49b4-a5bf-5cf593fc8f21"
)

Arguments

con

Ligação à base de dados MozART 2.0
opendate

Data de abertura do período (introduzir como “AAAA-MM-DD”)
enddate

Data de fecho do período (introduzir como “AAAA-MM-DD”)
filter_by_location

Se TRUE, o query corre sobre uma unidade sanitária específica. Se FALSE, o query corre sobre todas as unidade sanitária contidas no MozART 2.0
location_uuid

location_uuid da unidade sanitária a filtrar quando filter_by_location é definido como TRUE

Value

pull_new_uuid devolve um vector contendo os patient_uuid unicos dos pacientes activos em TARV

Examples

## Not run: 

# Caso de uso simples executado sobre todas US
uuids <- pull_new_uuid(con, opendate = "2024-06-21", enddate = "2024-09-20", filter_by_location = FALSE)

# # Caso de uso simples executado sobre uma US
uuids <- pull_new_uuid(con, opendate = "2024-06-21", enddate = "2024-09-20",
                       filter_by_location = TRUE, location_uuid = 'e3eb1a1b-be07-4af2-9360-5d7046910576')

## End(Not run)

Recodificar idade

Description

recode_age() devolve a idade e a faixa etária do cliente

Usage

recode_age(df, age_column = "age", variable_name = "age_band")

Arguments

df

Quadro de dados contendo a variável a recodificar
age_column

Variável no quadro de dados introduzido contendo a idade do cliente
variable_name

Nome da variável que será criada no quadro de dados com a faixa etária do cliente (default = 'age_band')

Value

recode_age devolve um quadro de dados com a coluna idade recodificada

Examples

## Not run: 

 df <- recode_age(
          df = df,
          age_column = "age")
## End(Not run)

Recodificar várias colunas utilizando vectores custimizados

Description

recode_cols() reatribui valores para colunas codificadas tal como especificado pela entrada “cols” fornecida pelo utilizador

Usage

recode_cols(
  df,
  cols = c("mode_dispensation_id", "regimen_id", "location_uuid", "age", "form_id",
    "state_id", "sex"),
  options = list(df_disp_mode = data_type_id_lookup, df_regimen = data_type_id_lookup,
    df_form = data_type_id_lookup, df_state = data_type_id_lookup, df_location =
    data_location_lookup, age_column = "age", sex_column = "sex")
)

Arguments

df

Quadro de dados contendo colunas a serem recodificadas
cols

Vector de strings contendo os nomes das colunas a recodificar
options

Lista de parâmetros opcionais para personalizar a recodificação

Value

recode_cols() devolve um quadro de dados com colunas recodificadas

Examples

## Not run: 
 # Caso de uso para recodificar dispensation_id, regimen_id, location_uuid, age, form_id, state_id, and sex
 df <- recode_cols(
          df = df,
          cols = c("mode_dispensation_id",
                   "regimen_id",
                   "location_uuid",
                   "age",
                   "form_id",
                   "state_id",
                   "sex"))
## End(Not run)

Recodificar modo de dispensa TARV

Description

recode_disp_mode() retorna uma apresentação mais compreensível do modo de dispensa do ARV

Usage

recode_disp_mode(df, df_disp_mode = data_type_id_lookup, keep_id = FALSE)

Arguments

df

Quadro de dados contendo a variável a recodificar
df_disp_mode

Objecto de tabela de pesquisa usado para recodificação
keep_id

Manter a coluna regimen_id após a recodificação (Logical T/F)

Value

recode_disp_mode devolve um quadro de dados com a coluna regimen recodificada

Examples

## Not run: 

 df <- recode_disp_mode(
          df = df,
          df_disp_mode = data_type_id_lookup,
          keep_id = FALSE)
## End(Not run)

Recodificar formulario primario

Description

recode_form() devolve uma apresentação mais compreensível do documento de fonte primária

Usage

recode_form(df, df_form = data_type_id_lookup, keep_id = FALSE)

Arguments

df

Quadro de dados contendo a variável a recodificar
df_form

Objecto de tabela de pesquisa usado para recodificação
keep_id

Manter a coluna regimen_id após a recodificação (Logical T/F)

Value

recode_form devolve um quadro de dados com a coluna regimen recodificada

Examples

## Not run: 

 df <- recode_form(
          df = df,
          df_form = data_type_id_lookup,
          keep_id = FALSE)
## End(Not run)

Recodificar location_uuid's

Description

recode_location() devolve um conjunto de informações mais facilmente compreensíveis sobre a localização

Usage

recode_location(df, df_location = data_location_lookup)

Arguments

df

Quadro de dados contendo a variável a recodificar
df_location

Objecto de tabela de pesquisa usado para recodificação

Value

recode_location devolve um quadro de dados com a coluna location_uuid recodificada

Examples

## Not run: 

 df <- recode_location(
          df = df,
          df_location = data_location_lookup)
## End(Not run)

Recodificar regimen TARV

Description

recode_regimen() devolve uma apresentação mais compreensível do regime ART do cliente

Usage

recode_regimen(df, df_regimen = data_type_id_lookup, keep_id = FALSE)

Arguments

df

Quadro de dados contendo a variável a recodificar
df_regimen

Objecto de tabela de pesquisa usado para recodificação
keep_id

Manter a coluna regimen_id após a recodificação (Logical T/F)

Value

recode_regimen devolve um quadro de dados com a coluna regimen recodificada

Examples

## Not run: 

 df <- recode_regimen(
          df = df,
          df_regimen = data_type_id_lookup,
          keep_id = FALSE)
## End(Not run)

Recodificar sexo

Description

recode_sex() devolve o sexo do cliente escrito por extenso

Usage

recode_sex(df, sex_column = "sex")

Arguments

df

Quadro de dados contendo a variável a recodificar
sex_column

Variável no quadro de dados introduzido contendo o sexo do cliente

Value

recode_sex devolve um quadro de dados com a coluna sexo recodificada

Examples

## Not run: 

 df <- recode_sex(
          df = df,
          sex_column = "sex")
## End(Not run)

Recodificar estado do cliente

Description

recode_state() devolve uma apresentação mais compreensível do estado do cliente

Usage

recode_state(df, df_state = data_type_id_lookup, keep_id = FALSE)

Arguments

df

Quadro de dados contendo a variável a recodificar
df_state

Objecto de tabela de pesquisa usado para recodificação
keep_id

Manter a coluna state_id após a recodificação (Logical T/F)

Value

recode_state devolve um quadro de dados com a coluna state recodificada

Examples

## Not run: 

 df <- recode_state(
          df = df,
          df_state = data_type_id_lookup,
          keep_id = FALSE)
## End(Not run)