stashR                package:stashR                R Documentation

_C_l_a_s_s_e_s "_r_e_m_o_t_e_D_B" _a_n_d "_l_o_c_a_l_D_B"

_D_e_s_c_r_i_p_t_i_o_n:

     These functions create an interface for a simple file-based 
     key-value database using remote storage via http

_O_b_j_e_c_t_s _f_r_o_m _t_h_e "_r_e_m_o_t_e_D_B" _a_n_d "_l_o_c_a_l_D_B" _c_l_a_s_s_e_s:

     Objects can be created by calls of the form  'new("remoteDB",
     ...)' and 'new("localDB", ...)' respectively.

_S_l_o_t_s:

     '_u_r_l': Object of class '"character"',  url of the remote database

     '_d_i_r': Object of class '"character"',  local directory in which to
          download the data or local  directory in which to create a
          database

_M_e_t_h_o_d_s:

     _d_b_D_e_l_e_t_e 'signature(db = "remoteDB", key = "character")':  Calling
          'dbDelete' on a 'remoteDB' object returns an error.

     _d_b_D_e_l_e_t_e 'signature(db = "localDB", key = "character")':  Calling
          'dbDelete' on a 'localDB' deletes the specified key from the
          database and updates the repository version.

     _d_b_E_x_i_s_t_s 'signature(db = "remoteDB", key = "character")':  For
          each element in the vector 'key', 'dbExists' returns TRUE if
          the key is in the database and otherwise returns FALSE.

     _d_b_E_x_i_s_t_s 'signature(db = "localDB", key = "character")':  For each
          element in the vector 'key', 'dbExists' returns TRUE if the
          key is in the database and otherwise returns FALSE. 

     _d_b_F_e_t_c_h 'signature(db = "remoteDB", key = "character")':  Checks
          if the provided character value 'key' exists in the local 
          directory. If not, 'dbFetch' downloads the data files for the
          current version. Otherwise, 'dbFetch' reads the file from the
          local directory. The function returns the data object
          associated with the 'key'.

     _d_b_F_e_t_c_h 'signature(db = "localDB", key = "character")':  Checks if
          the provided character value 'key' exists in the local 
          directory. If the 'key' exists in the local directory, then 
          'dbFetch' reads the file from the local directory. The
          function  returns the data object associated with the 'key'. 

     _d_b_I_n_s_e_r_t 'signature(db = "remoteDB", key = "character",  value =
          "ANY")': Calling 'dbInsert' on a 'remoteDB' object returns an
          error. 

     _d_b_I_n_s_e_r_t 'signature(db = "localDB", key = "character",  value =
          "ANY")': Calling 'dbInsert' on a 'localDB' object writes the
          value to a file corresponding to the specified key in the
          local directory and updates the version of the repository. 

     _d_b_L_i_s_t 'signature(db = "remoteDB")':  The method 'dbList' returns
          a character vector of all the keys in the database.

     _d_b_L_i_s_t 'signature(db = "localDB")':  The method 'dbList' returns a
          character vector of all the keys in the database.

     _d_b_S_y_n_c 'signature(db = "remoteDB", key = "character")':  If 'key =
          NULL', Updates all key/data pairs in the local directory to
          the most recent repository version on the remote server.  If
          'key' is a character vector, then it only updates the
          specified key/data pairs (in which case, it first checks to
          ensure that all specified keys' files have been previously
          saved). 

     _d_b_C_r_e_a_t_e 'signature(db = "remoteDB")':  Calling 'dbCreate' on a
          'remoteDB' object creates the  local main directory and data
          sub-directory for storing the  data files and saves the url
          associated with the 'remoteDB' object in the R workspace
          format in the local main directory. 'dbCreate' is called
          implicitly when 'new' is called to create the 'remoteDB'
          object so calling 'dbCreate' explicitly is usually not
          necessary.

     _d_b_C_r_e_a_t_e 'signature(db = "localDB")':  Calling 'dbCreate' on a
          'localDB' object creates the  local main directory and data
          sub-directory to in which to store the  data files. 
          'dbCreate' is called implicitly when 'new' is called to
          create the 'localDB' object so calling 'dbCreate' explicitly
          is usually not necessary.

_A_u_t_h_o_r(_s):

     Sandy Eckel, Roger D. Peng

_E_x_a_m_p_l_e_s:

     ## Not run: 
     ## Objects of the class localDB

     wd <- getwd()
     dir <- file.path(wd,"localDBExample")

     ## Create local stashR data repository 'localDBExample'
     fhLocal <- new("localDB", dir = dir, name = "localDBExample")

     ## Insert key-value data into 'localDBExample' 
     v <- 1:10
     dbInsert(fhLocal,key = "vector", value = v)
     m <- matrix(1:20,5,4)
     dbInsert(fhLocal,key = "matrix", value = m)
     d <- data.frame(cbind(id = 1:5, age=c(12,11,15,11,14), sex = c(1,1,0,1,0)))
     dbInsert(fhLocal,key = "dataframe", value = d)
     l <- list(v = v, m = m, df = d)
     dbInsert(fhLocal, key = "list", value = l)

     dbList(fhLocal)

     dbFetch(fhLocal, "dataframe") 
     dbDelete(fhLocal, "vector")
     dbExists(fhLocal, "vector")
     dbList(fhLocal) 

     ## Objects of the class remoteDB

     ## The same key-value data used in the previous example for localDB
     ## has been stored in a remoteDB repository on the internet at:
     myurl <- "http://www.biostat.jhsph.edu/~seckel/remoteDBExample"

     wd <- getwd()
     dir <- file.path(wd,"remoteDBExample") 
     ## Create local copy of data repository 'remoteDBExample'
     fhRemote <- new("remoteDB", url= myurl, 
                 dir = dir, name= "remoteDBExample")

     dbList(fhRemote)
     dbExists(fhRemote,c("vector", "array","list", "function"))
     ## downloads 'vector' data from the remoteDB repository
     dbFetch(fhRemote, "vector") 
     ## fetches without downloading again 
     dbFetch(fhRemote, "vector") 
     ## synchronize all local copies of the data to the remote version
     dbSync(fhRemote, key = NULL)
     ## End(Not run)

