Movatterモバイル変換

Exchange data between LabKey Server and R

Description

This package allows the transfer of data between a LabKey Server and an R session. Data can be retrieved from LabKey into a data frame in R by specifying the query schema information (labkey.selectRows andgetRows) or by using sql commands (labkey.executeSql). From an R session, existing data can be updated(labkey.updateRows), new data can be inserted (labkey.insertRows andlabkey.importRows) ordata can be deleted from the LabKey database (labkey.deleteRows). Interactive R users can discover available data viaschema objects (labkey.getSchema).

Details

The user must have appropriate authorization on the LabKey Server in order to access or modify data using these functions.All access to secure content on LabKey Server requires authentication via an api key (seelabkey.setDefaults formore details) or a properly configured netrc file that includes the user's login information.

The netrc file is a standard mechanism for conveying configuration and autologin information to the File Transfer Protocolclient (ftp) and other programs such as CURL. On a Linux or Mac system this file should be named .netrc (dot netrc) and onWindows it should be named _netrc (underscore netrc). The file should be located in the user's home directory and thepermissions on the file should be unreadable for everybody except the owner.

To create the _netrc on a Windows machine, first create an environment variable called 'HOME' set to your home directory(e.g., c:/Users/<User-Name> on recent versions of Windows) or any directory you want to use. In that directory, create atext file named _netrc (note that it's underscore netrc, not dot netrc like it is on Linux/Mac).

The following three lines must be included in the .netrc or _netrc file either separated by white space(spaces, tabs, or newlines) or commas.

machine <remote-machine-name>
login <user-email>
password <user-password>

One example would be:
machine localhost
login peter@labkey.com
password mypassword

Another example would be:
machine atlas.scharp.org login vobencha@fhcrc.org password mypassword

Multiple such blocks can exist in one file.

Author(s)

Valerie Obenchain

References

http://www.omegahat.net/RCurl/,
https://www.labkey.org/home/project-begin.view

See Also

labkey.selectRows,labkey.executeSql,makeFilter,labkey.insertRows,labkey.importRows,
labkey.updateRows,labkey.deleteRows

Returns the folder path associated with a session

Description

Returns the current folder path for a LabKey session

Usage

getFolderPath(session)

Arguments

Details

Returns a string containing the current folder path for the passed in LabKey session

Value

A character array containing the folder path, relative to the root.

Author(s)

Peter Hussey

References

https://www.labkey.org/Documentation/wiki-page.view?name=projects

See Also

getSessionlsFolders

Examples

## Not run: # library(Rlabkey)lks<- getSession("https://www.labkey.org", "/home")getFolderPath(lks)  #returns "/home"## End(Not run)

Get related data fields that are available to include in a query on a given query object

Description

Retrieve a related query object referenced by a lookup column in the current query

Usage

getLookups(session, lookupField)

Arguments

Details

Lookup fields in LabKey Server are the equivalent of declared foreign keys

Value

A query object representing the related data set. The fields of a lookup query object are usually added to the colSelect parameter in getRows, If a lookup query object is used as the query parameter ingetRows, the call will return all of the base query columns and all of the lookup query columns.A lookup query object is very similar to basequery objects that are named elemenets of a schema object, A lookup queryobject, however, does not have a parent schema object, it is only returned by getLookups. Also, the field names ina lookup query object are compound names relative to the base query object used in getLookups.

Author(s)

Peter Hussey

References

https://www.labkey.org/Documentation/wiki-page.view?name=propertyFields

See Also

getSession,getRowsgetSchema

Examples

## Not run: ##  get fields from lookup tables and add to query# library(Rlabkey)s<- getSession(baseUrl="http://localhost:8080/labkey",    folderPath="/apisamples") scobj <- getSchema(s, "lists")# can add fields from related querieslucols <- getLookups(s, scobj$AllTypes$Category)# keep going to other tableslucols2 <- getLookups(s, lucols[["Category/Group"]])cols <- c(names(scobj$AllTypes)[2:6], names(lucols)[2:4])getRows(s, scobj$AllTypes, colSelect=paste(cols, sep=","))## End(Not run)

Retrieve data from LabKey Server

Description

Retrive rows from a LabKey Server given a session and query object

Usage

getRows(session, query, maxRows=NULL, colNameOpt='fieldname', ...)

Arguments

Details

This function works as a shortcut wrapper tolabkey.selectRows. All of the arguments are the same as documented inlabkey.selectRows.

Seelabkey.selectRows for a discussion of the valid options and defaults forcolNameOpt. Note in particular that with getRows the default is 'fieldname' instead of 'caption'.

Value

A data frame containing the query results corresponding to the default view of the specified query.

Author(s)

Peter Hussey

See Also

getSession,getSchema,getLookups,saveResultslabkey.selectRows

Examples

## Not run: ## simple example of getting data using schema objects# library(Rlabkey)s<-getSession(baseUrl="http://localhost:8080/labkey",    folderPath="/apisamples")s  # shows schemasscobj <- getSchema(s, "lists")scobj   # shows available queriesscobj$AllTypes  ## this is the query objectgetRows(s, scobj$AllTypes)## End(Not run)

Returns an object representing a LabKey schema

Description

Creates and returns an object representing a LabKey schema, containing child objects representing LabKey queries

Usage

getSchema(session, schemaIndex)

Arguments

Details

Creates and returns an object representing a LabKey schema, containing child objects representing LabKey queries. This compound object is createdby callinglabkey.getQueries on the requested schema andlabkey.getQueryDetails on each returned query. The information returned in theschema objects is essentially the same as the schema and query objects shown in the Schema Browser on LabKey Server.

Value

an object representing the schema. The named elements of a schema are the queries within that schema.

Author(s)

Peter Hussey

References

https://www.labkey.org/Documentation/wiki-page.view?name=querySchemaBrowser

See Also

getSession

Examples

## Not run: ## the basics of using session, schema, and query objects# library(Rlabkey)s<- getSession(baseUrl="http://localhost:8080/labkey",    folderPath="/apisamples")sch<- getSchema(s, "lists")# can walk down the populataed schema tree from schema node or query nodesch$AllTypes$Categorysch$AllTypes$Category$captionsch$AllTypes$Category$type# can add fields from related querieslucols <- getLookups(s, sch$AllTypes$Category)cols <- c(names(sch$AllTypes[2:6]), names(lucols)[2:4])getRows(s, sch$AllTypes, colSelect=cols)## End(Not run)

Creates and returns a LabKey Server session

Description

The session object holds server address and folder context for a user working with LabKey Server. The session-based model supports more efficient interactive use of LabKey Server from R.

Usage

getSession(baseUrl, folderPath="/home",    curlOptions=NULL, lkOptions=NULL)

Arguments

Details

Creates a session key that is passed to all the other session-based functions. Associated with the key are a baseUrl and a folderPath whichdetermine the security context.

curlOptions

The curlOptions parameter gives a mechanism to pass control options down to the RCurl library used by Rlabkey. This can be very useful for debugging problems or setting proxy server properties. See example for debugging.

lkOptions

The lkOptions parameter gives a mechanism to change default behavior in the objects returned by Rlabkey. Currently the only available options arecolNameOpt, which affects the names of columns in the data frames returnedby getRows(), andmaxRows, which sets a default value for this parameter when calling getRows()

Value

getSession returns a session object that represents a specific user within a specific project folder within the LabKey Server identified by the baseUrl. The combination of user, server and project/folder determines the security context of the client program.

Author(s)

Peter Hussey

See Also

getRows,getSchema,getLookupssaveResults

Examples

## Not run: # library(Rlabkey)s <- getSession("https://www.labkey.org", "/home")s   #shows schemas## using the curlOptions for generating debug tracesof network trafficd<- debugGatherer()copt <- curlOptions(debugfunction=d$update, verbose=TRUE,    cookiefile='/cooks.txt')sdbg<- getSession(baseUrl="http://localhost:8080/labkey",    folderPath="/apisamples", curlOptions=copt)getRows(sdbg, scobj$AllTypes)strwrap(d$value(), 100)## End(Not run)

Convenience method to configure Rlabkey connections to accept self-signed certificates

Description

Rlabkey uses the package RCurl to connect to the LabKey Server. This is equivalent toexecuting the function: labkey.setCurlOptions(ssl_verifyhost=0, ssl_verifypeer=FALSE)

Usage

labkey.acceptSelfSignedCerts()

Returns the current set of Curl options that are being used in the existing session

Description

Rlabkey uses the package RCurl to connect to the LabKey Server.

Usage

labkey.curlOptions()

Delete rows of data from a LabKey database

Description

Specify rows of data to be deleted from the LabKey Server

Usage

labkey.deleteRows(baseUrl, folderPath,    schemaName, queryName, toDelete,    provenanceParams=NULL, options=NULL)

Arguments

Details

A single row or multiple rows of data can be deleted. For thetoDelete data frame, version 0.0.5 or later accepts either a single column of data containing the data identifiers (e.g., key or lsid) or the entire row of data to be deleted.The names of the data in the data frame must be the column names from the LabKey Server.The data frame must be created with thestringsAsFactors set to FALSE.

NOTE: Each variable in a dataset has both a column label and a column name. The column label is visible at the topof each column on the web page and is longer and more descriptive. The column name is shorter and is used “behind the scenes” for database manipulation. It is the column name that must be used inthe Rlabkey functions when a column name is expected. To identify a particular column name in a dataset ona web site, use the “export to R script” option available as a drop down option under the “views” tab for each dataset.

The list of valid options for each query will vary, but some common examples include:

• auditBehavior (string) : Can be used to override the audit behavior for the table the query is acting on.The set of types include: NONE, SUMMARY, and DETAILED.

• auditUserComment (string) : Can be used to provide a comment from the user that will be attached tocertain detailed audit log records.

Value

A list is returned with named categories ofcommand,rowsAffected,rows,queryName,containerPath andschemaName.TheschemaName,queryName andcontainerPath properties contain the same schema, query and folder path used in the request. TherowsAffected property indicates the number of rows affected by the API action. This will typically be the samenumber as passed in the request. Therows property contains a list of rows corresponding to the rowsdeleted.

Author(s)

Valerie Obenchain

See Also

labkey.selectRows,labkey.executeSql,makeFilter,labkey.insertRows,labkey.importRows,
labkey.updateRows,labkey.moveRows,
labkey.provenance.createProvenanceParams,labkey.provenance.startRecording,labkey.provenance.addRecordingStep,labkey.provenance.stopRecording

Examples

## Not run: ## Insert, update and delete## Note that users must have the necessary permissions in the LabKey Server## to be able to modify data through the use of these functions# library(Rlabkey)newrow <- data.frame(DisplayFld="Inserted from R", TextFld="how its done", IntFld= 98 , DoubleFld = 12.345, DateTimeFld = "03/01/2010", BooleanFld= FALSE, LongTextFld = "Four score and seven years ago"#, AttachmentFld = NA    #attachment fields not supported , RequiredText = "Veni, vidi, vici", RequiredInt = 0, Category = "LOOKUP2", stringsAsFactors=FALSE)insertedRow <- labkey.insertRows("http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists",    queryName="AllTypes", toInsert=newrow)newRowId <- insertedRow$rows[[1]]$RowIdselectedRow<-labkey.selectRows("http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",    colFilter=makeFilter(c("RowId", "EQUALS", newRowId)))selectedRowupdaterow=data.frame(RowId=newRowId, DisplayFld="Updated from R", TextFld="how to update", IntFld= 777 , stringsAsFactors=FALSE)updatedRow <- labkey.updateRows("http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists",    queryName="AllTypes", toUpdate=updaterow)selectedRow<-labkey.selectRows("http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",    colFilter=makeFilter(c("RowId", "EQUALS", newRowId)))selectedRowdeleterow <- data.frame(RowId=newRowId, stringsAsFactors=FALSE)result <- labkey.deleteRows(baseUrl="http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists",    queryName="AllTypes",  toDelete=deleterow)result## End(Not run)

Provide comparator access

Description

A list specifying permitted validator comparators.

Usage

labkey.domain.FILTER_TYPES

Details

This constant contains a list specifying the set of permitted validator operators, using names to mapconventional terms to the expressions used by LabKey filter URL formats. The values are intended to be used inconjunction with conditional formats or property validators.

Value

A named list of strings.

Author(s)

Rosaline Pyktel

See Also

labkey.domain.get,labkey.domain.create,labkey.domain.createDesign,labkey.domain.inferFields,labkey.domain.save,labkey.domain.drop,labkey.domain.createConditionalFormat,labkey.domain.createConditionalFormatQueryFilter

Examples

## Not run: library(Rlabkey)qf <- labkey.domain.FILTER_TYPES# Example of available comparatorscomparator1 <- qf$EQUALcomparator2 <- qf$GREATER_THANcomparator3 <- qf$DATE_LESS_THAN_OR_EQUALcomparator4 <- qf$STARTS_WITHcomparator5 <- qf$CONTAINS_ONE_OF## End(Not run)

Create a new LabKey domain

Description

Create a domain of the type specified by the domainKind and the domainDesign. A LabKey domain represents a table in a specific schema.

Usage

labkey.domain.create(baseUrl=NULL, folderPath,    domainKind=NULL, domainDesign=NULL, options=NULL,    module=NULL, domainGroup=NULL, domainTemplate=NULL,    createDomain=TRUE, importData=TRUE)

Arguments

Details

When creating a domain using a domainKind parameter, the domainDesign parameter will be required. If a domain template is beingused, then module, domainGroup, and domainTemplate are required.

Will create a domain of the specified domain type, valid types are

• "IntList": A list with an integer key field

• "VarList": A list with a string key field

• "StudyDatasetVisit": A dataset in a visit based study

• "StudyDatasetDate": A dataset in a date based study

• "IssueDefinition": An issue list domain

• "SampleSet": Sample set

• "DataClass": Data class

The domain design parameter describes the set of fields in the domain, seelabkey.domain.createDesign for the helperfunction that can be used to construct this data structure. The options parameter should contain a list of attributes that are specificto the domain kind specified. The list of valid options for each domain kind are:

• IntList and VarList

  • keyName (required) : The name of the field in the domain design which identifies the key field

• StudyDatasetVisit and StudyDatasetDate

  • datasetId : Specifies a dataset ID to use, the default is to auto generate an ID

  • categoryId : Specifies an existing category ID

  • categoryName : Specifies an existing category name

  • demographics : (TRUE | FALSE) Determines whether the dataset is created as demographic

  • keyPropertyName : The name of an additional key field to be used in conjunction with participantId and (visitId or date) to create unique records

  • useTimeKeyField : (TRUE | FALSE) Specifies to use the time portion of the date field as an additional key

  • isManagedField : (TRUE | FALSE) Specifies whether the field from keyPropertyName should be managed by LabKey.

• IssueDefinition

  • providerName : The type of issue list to create (IssueDefinition (default) or AssayRequestDefinition)

  • singularNoun : The singular name to use for items in the issue definition (defaults to issue)

  • pluralNoun : The plural name (defaults to issues)

• SampleSet

  • idCols : The columns to use when constructing the concatenated unique ID. Can be up to 3 numeric IDs which represent the zero-based position of the fields in the domain.

  • parentCol : The column to represent the parent identifier in the sample set. This is a numeric value representing the zero-based position of the field in the domain.

  • nameExpression : The name expression to use for creating unique IDs

• DataClass

  • sampleSet : The ID of the sample set if this data class is associated with a sample set.

  • nameExpression : The name expression to use for creating unique IDs

Value

A list containing elements describing the newly created domain.

Author(s)

Karl Lum

See Also

labkey.domain.get,labkey.domain.inferFields,labkey.domain.createDesign,labkey.domain.createIndices,labkey.domain.save,labkey.domain.drop,labkey.domain.createConditionalFormat,labkey.domain.createConditionalFormatQueryFilter,labkey.domain.FILTER_TYPES

Examples

## Not run: ## create a data frame and infer it's fields, then create a domain design from itlibrary(Rlabkey)df <- data.frame(ptid=c(1:3), age = c(10,20,30), sex = c("f", "m", "f"))fields <- labkey.domain.inferFields(baseUrl="http://labkey/", folderPath="home", df=df)dd <- labkey.domain.createDesign(name="test list", fields=fields)## create a new list with an integer key fieldlabkey.domain.create(baseUrl="http://labkey/", folderPath="home",    domainKind="IntList", domainDesign=dd, options=list(keyName = "ptid"))## create a domain using a domain templatelabkey.domain.create(baseUrl="http://labkey/", folderPath="home",    domainTemplate="Priority", module="simpletest", domainGroup="todolist")## End(Not run)

Create a new LabKey domain and load data

Description

Create a domain of the type specified by the domainKind. A LabKey domain represents a table in a specific schema. Once the domain is createdthe data from the data frame will be imported.

Usage

labkey.domain.createAndLoad(baseUrl=NULL, folderPath,    name, description="", df, domainKind, options=NULL, schemaName=NULL)

Arguments

Details

Will create a domain of the specified domain type, valid types are

• "IntList": A list with an integer key field

• "VarList": A list with a string key field

• "StudyDatasetVisit": A dataset in a visit based study

• "StudyDatasetDate": A dataset in a date based study

• "IssueDefinition": An issue list domain

• "SampleSet": Sample set

• "DataClass": Data class

The options parameter should contain a list of attributes that are specificto the domain kind specified. The list of valid options for each domain kind are:

• IntList and VarList

  • keyName (required) : The name of the field in the domain design which identifies the key field

• StudyDatasetVisit and StudyDatasetDate

  • datasetId : Specifies a dataset ID to use, the default is to auto generate an ID

  • categoryId : Specifies an existing category ID

  • categoryName : Specifies an existing category name

  • demographics : (TRUE | FALSE) Determines whether the dataset is created as demographic

  • keyPropertyName : The name of an additional key field to be used in conjunction with participantId and (visitId or date) to create unique records

  • useTimeKeyField : (TRUE | FALSE) Specifies to use the time portion of the date field as an additional key

• IssueDefinition

  • providerName : The type of issue list to create (IssueDefinition (default) or AssayRequestDefinition)

  • singularNoun : The singular name to use for items in the issue definition (defaults to issue)

  • pluralNoun : The plural name (defaults to issues)

• SampleSet

  • idCols : The columns to use when constructing the concatenated unique ID. Can be up to 3 numeric IDs which represent the zero-based position of the fields in the domain.

  • parentCol : The column to represent the parent identifier in the sample set. This is a numeric value representing the zero-based position of the field in the domain.

  • nameExpression : The name expression to use for creating unique IDs

• DataClass

  • sampleSet : The ID of the sample set if this data class is associated with a sample set.

  • nameExpression : The name expression to use for creating unique IDs

Value

A list containing the newly uploaded data frame rows.

Author(s)

Karl Lum

See Also

labkey.domain.get,labkey.domain.inferFields,labkey.domain.createDesign,labkey.domain.createIndices,labkey.domain.save,labkey.domain.drop

Examples

## Not run: library(Rlabkey)## Prepare a data.frameparticipants = c("0001","0001","0002","0002","0007","0008")Visit = c("V1", "V2", "V2", "V1", "V2", "V1")IntValue = c(256:261)dataset = data.frame("ParticipantID" = participants, Visit,    "IntegerValue" = IntValue, check.names = FALSE)## Create the dataset and importlabkey.domain.createAndLoad(baseUrl="http://labkey", folderPath="home",    name="demo dataset", df=dataset, domainKind="StudyDatasetVisit")## End(Not run)

Create a conditional format data frame

Description

Create a conditional format data frame.

Usage

labkey.domain.createConditionalFormat(queryFilter, bold=FALSE, italic=FALSE,    strikeThrough=FALSE, textColor="", backgroundColor="")

Arguments

Details

This function can be used to construct a conditional format data frame intended for use within a domain design'sconditionalFormats component while creating or updating a domain. The queryFilter parameter can be used in conjunctionwithlabkey.domain.createConditionalFormatQueryFilter for convenient construction of a query filter string. Multiple conditionalformats can be applied to one field, where each format specified constitutes a new row of the field's conditionalFormatsdata frame.If text formatting options are not specified, the default is to display the value as black text on a white background.

Value

The data frame containing values describing a conditional format.

Author(s)

Rosaline Pyktel

See Also

labkey.domain.get,labkey.domain.create,labkey.domain.createDesign,labkey.domain.inferFields,labkey.domain.save,labkey.domain.drop,labkey.domain.createConditionalFormatQueryFilter,labkey.domain.FILTER_TYPES

Examples

## Not run: library(Rlabkey)domain <- labkey.domain.get(baseUrl="http://labkey/", folderPath="home",    schemaName="lists", queryName="test list")## update the third field to use two conditional formatsqf <- labkey.domain.FILTER_TYPEScf1 = labkey.domain.createConditionalFormat(labkey.domain.createConditionalFormatQueryFilter(qf$GT,      100), bold=TRUE, text_color="D33115", background_color="333333")cf2 = labkey.domain.createConditionalFormat(labkey.domain.createConditionalFormatQueryFilter(      qf$LESS_THAN, 400), italic=TRUE, text_color="68BC00")domain$fields$conditionalFormats[[3]] = rbind(cf1,cf2)labkey.domain.save(baseUrl="http://labkey/", folderPath="home",    schemaName="lists", queryName="test list", domainDesign=domain)## End(Not run)

Create a conditional format query filter

Description

Create a conditional format query filter string.

Usage

labkey.domain.createConditionalFormatQueryFilter(filterType, value,    additionalFilter=NULL, additionalValue=NULL)

Arguments

Details

This function can be used to as a convenience wrapper to construct a query filter string for conditional formats.Two relational expressions may be formed, one with the first two parameters (for instance, parameter values '50' and 'eq' for value and filterrespectively would create a condition of 'equals 50') and the second with the remaining two optional parameters. If bothconditions are created, they are conjunct with a logical AND, and a value would have to pass both conditions to clearthe filter.This function can be used in conjunction withlabkey.domain.FILTER_TYPES for easy access to the set ofpermitted relational operators.

Value

The string specifying a query filter in LabKey filter URL format.

Author(s)

Rosaline Pyktel

See Also

labkey.domain.get,labkey.domain.create,labkey.domain.createDesign,labkey.domain.inferFields,labkey.domain.save,labkey.domain.drop,labkey.domain.createConditionalFormat,labkey.domain.FILTER_TYPES

Examples

## Not run: library(Rlabkey)qf <- labkey.domain.FILTER_TYPES# Filters for values equal to 750qf1 <- labkey.domain.createConditionalFormatQueryFilter(qf$EQUAL, 750)# Filters for values greater than 500, but less than 1000qf2 <- labkey.domain.createConditionalFormatQueryFilter(qf$GREATER_THAN, 500, qf$LESS_THAN, 1000)## End(Not run)

Helper function to create a domain design data structure

Description

Create a domain design data structure which can then be used bylabkey.domain.create orlabkey.domain.save

Usage

labkey.domain.createDesign(name, description = NULL, fields, indices = NULL)

Arguments

Details

This is a function which can be used to create a domain design data structure. Domain designs are used both when creating a new domain or updating an existing domain.

Value

A list containing elements describing the domain design. Any of the APIs which take a domain design parameter can accept this data structure.

Author(s)

Karl Lum

See Also

labkey.domain.get,labkey.domain.inferFields,labkey.domain.createIndices,labkey.domain.create,labkey.domain.save,labkey.domain.drop,labkey.domain.createConditionalFormat,labkey.domain.createConditionalFormatQueryFilter,labkey.domain.FILTER_TYPES

Examples

## Not run: ## create a data frame and infer it's fields, then create a domain design from itlibrary(Rlabkey)df <- data.frame(ptid=c(1:3), age = c(10,20,30), sex = c("f", "m", "f"))fields <- labkey.domain.inferFields(baseUrl="http://labkey/", folderPath="home", df=df)indices = labkey.domain.createIndices(list("ptid", "age"), TRUE)indices = labkey.domain.createIndices(list("age"), FALSE, indices)dd <- labkey.domain.createDesign(name="test list", fields=fields, indices=indices)## End(Not run)

Helper function to create a domain design indices list

Description

Create a list of indices definitions which can then be used bylabkey.domain.createDesign

Usage

labkey.domain.createIndices(colNames, asUnique, existingIndices = NULL)

Arguments

Details

This helper function can be used to construct the list of indices definitions for a domain design structure.Each call to this function takes in the column names from the domain to use in the index and a parameterindicating if this should be a UNIQUE index. A third parameter can be used to build up more then one indicesdefinitions.

Value

The data frame containing the list of indices definitions, concatenated with the existingIndices object if provided.

Author(s)

Cory Nathe

See Also

labkey.domain.get,labkey.domain.create,labkey.domain.createDesign,labkey.domain.inferFields,labkey.domain.save,labkey.domain.drop

Examples

## Not run: ## create a list of indices definitions to use for a domain designlibrary(Rlabkey)indices = labkey.domain.createIndices(list("intKey", "customInt"), TRUE)indices = labkey.domain.createIndices(list("customInt"), FALSE, indices)## End(Not run)

Delete a LabKey domain

Description

Delete an existing domain.

Usage

labkey.domain.drop(baseUrl=NULL, folderPath, schemaName, queryName)

Arguments

Details

This function will delete an existing domain along with any data that may have been uploaded to it.

Author(s)

Karl Lum

See Also

labkey.domain.get,labkey.domain.inferFields,labkey.domain.createDesign,labkey.domain.createIndices,labkey.domain.save,labkey.domain.create

Examples

## Not run: ## delete an existing domainlibrary(Rlabkey)labkey.domain.drop(baseUrl="http://labkey/", folderPath="home",    schemaName="lists", queryName="test list")## End(Not run)

Returns the metadata for an existing LabKey domain

Description

Get the data structure for a domain.

Usage

labkey.domain.get(baseUrl=NULL, folderPath, schemaName, queryName)

Arguments

Details

Returns the domain design of an existing domain. The returned domain design can be used for reporting purposes or it canbe modified and used to create a new domain or update the domain source.

Value

A list containing elements describing the domain. The structure is the same as a domain design created bylabkey.createDomainDesign

Author(s)

Karl Lum

See Also

labkey.domain.create,labkey.domain.inferFields,labkey.domain.createDesign,labkey.domain.createIndices,labkey.domain.save,labkey.domain.drop

Examples

## Not run: ## retrieve an existing domainlibrary(Rlabkey)labkey.domain.get(baseUrl="http://labkey/", folderPath="home",    schemaName="lists", queryName="test list")## End(Not run)

Infer field metadata from a data frame

Description

Generate field information from the specified data frame. The resulting list can be used to create or edit a domain using the labkey.domain.create or labkey.domain.save APIs.

Usage

labkey.domain.inferFields(baseUrl = NULL, folderPath, df)

Arguments

Details

Field information can be generated from a data frame by introspecting the data associated with it along with other properties about that column. The data frameis posted to the server endpoint where the data is analyzed and returned as a list of fields each with it's associated list of properties and values. This listcan be edited and/or used to create a domain on the server.

Value

The inferred metadata will be returned as a list with an element called : "fields" which contains the list of fields inferred from the data frame.Each field will contain the list of attributes and values for that field definition.

Author(s)

Karl Lum

See Also

labkey.domain.get,labkey.domain.create,labkey.domain.createDesign,labkey.domain.createIndices,labkey.domain.save,labkey.domain.drop

Examples

## Not run: ## create a data frame and infer it's fieldslibrary(Rlabkey)df <- data.frame(ptid=c(1:3), age = c(10,20,30), sex = c("f", "m", "f"))fields <- labkey.domain.inferFields(baseUrl="http://labkey/", folderPath="home", df=df)## End(Not run)

Updates an existing LabKey domain

Description

Modify an existing domain with the specified domain design.

Usage

labkey.domain.save(baseUrl=NULL, folderPath, schemaName, queryName, domainDesign)

Arguments

Value

A list containing elements describing the domain after the update. The structure is the same as a domain design created bylabkey.createDomainDesign

Author(s)

Karl Lum

See Also

labkey.domain.get,labkey.domain.inferFields,labkey.domain.createDesign,labkey.domain.createIndices,labkey.domain.create,labkey.domain.drop,labkey.domain.createConditionalFormat,labkey.domain.createConditionalFormatQueryFilter,labkey.domain.FILTER_TYPES

Examples

## Not run: library(Rlabkey)## change the type of one of the columnsdomain <- labkey.domain.get(baseUrl="http://labkey/", folderPath="home",    schemaName="lists", queryName="test list")domain$fields[3,]$rangeURI = "xsd:string"domain$fields[3,]$name = "changed to string"labkey.domain.save(baseUrl="http://labkey/", folderPath="home",    schemaName="lists", queryName="test list", domainDesign=domain)## End(Not run)

Retrieve data from a LabKey Server using SQL commands

Description

Use Sql commands to specify data to be imported into R. Prior to import, data canbe manipulated through standard SQL commands supported in LabKey SQL.

Usage

labkey.executeSql(baseUrl, folderPath, schemaName, sql,    maxRows = NULL, rowOffset = NULL, colSort=NULL,    showHidden = FALSE, colNameOpt='caption',    containerFilter=NULL, parameters=NULL)

Arguments

Details

A full dataset or any portion of a dataset can be imported into an Rdata frame using thelabkey.executeSqlfunction. Function arguments are components of the url that identify the location of thedata and the SQL actions that should be taken on the data prior to import.

Seelabkey.selectRows for a discussion of the valid options and defaults forcolNameOpt.

Value

The requested data are returned in a data frame with stringsAsFactors set to FALSE. Column names are set as determined by the colNameOpt parameter.

Author(s)

Valerie Obenchain

See Also

labkey.selectRows,makeFilter,labkey.insertRows,labkey.importRows,labkey.updateRows,
labkey.deleteRows,getRows

Examples

## Not run: ## Example of an expicit join and use of group by and aggregates# library(Rlabkey)sql<- "SELECT AllTypesCategories.Category AS Category,     SUM(AllTypes.IntFld) AS SumOfIntFld,    AVG(AllTypes.DoubleFld) AS AvgOfDoubleFld    FROM AllTypes LEFT JOIN AllTypesCategories    ON (AllTypes.Category = AllTypesCategories.TextKey)    WHERE AllTypes.Category IS NOT NULL    GROUP BY AllTypesCategories.Category"sqlResults <- labkey.executeSql(    baseUrl="http://localhost:8080/labkey",    folderPath="/apisamples",    schemaName="lists",    sql = sql)sqlResults## End(Not run)

Constant for the Simple Derivation Protocol

Description

Simple Derivation Protocol constant.

Details

This value can be used in the labkey.experiment.saveBatch function when creating runs that aren't backed by an assay protocol.

Author(s)

Karl Lum

See Also

labkey.experiment.saveBatch

Create an experiment data object

Description

Create an experiment data object.

Usage

labkey.experiment.createData(config,    dataClassId = NULL, dataClassName = NULL, dataFileUrl = NULL)

Arguments

Details

Create an experiment data object which can be used as either input or output datas for an experiment run.

Value

Returns the object representation of the experiment data object.

Author(s)

Karl Lum

See Also

labkey.experiment.saveBatch,labkey.experiment.createMaterial,labkey.experiment.createRun

Examples

## Not run: library(Rlabkey)## create a non-assay backed run with data classes as data inputs and outputsd1 <- labkey.experiment.createData(        list(name = "dc-01"), dataClassId = 400)d2 <- labkey.experiment.createData(        list(name = "dc-02"), dataClassId = 402)run <- labkey.experiment.createRun(        list(name="new run"), dataInputs = d1, dataOutputs = d2)labkey.experiment.saveBatch(baseUrl="http://labkey/", folderPath="home",        protocolName=labkey.experiment.SAMPLE_DERIVATION_PROTOCOL, runList=run)## End(Not run)

Create an experiment material object

Description

Create an experiment material object.

Usage

labkey.experiment.createMaterial(config, sampleSetId = NULL, sampleSetName = NULL)

Arguments

Details

Create an experiment material object which can be used as either input or output materials for an experiment run.

Value

Returns the object representation of the experiment material object.

Author(s)

Karl Lum

See Also

labkey.experiment.saveBatch,labkey.experiment.createData,labkey.experiment.createRun

Examples

## Not run: library(Rlabkey)## create a non-assay backed run with samples as material inputs and outputsm1 <- labkey.experiment.createMaterial(        list(name = "87444063.2604.626"), sampleSetName = "Study Specimens")m2 <- labkey.experiment.createMaterial(        list(name = "87444063.2604.625"), sampleSetName = "Study Specimens")run <- labkey.experiment.createRun(        list(name="new run"), materialInputs = m1, materialOutputs = m2)labkey.experiment.saveBatch(baseUrl="http://labkey/", folderPath="home",        protocolName=labkey.experiment.SAMPLE_DERIVATION_PROTOCOL, runList=run)## End(Not run)

Create an experiment run object

Description

Create an experiment run object.

Usage

labkey.experiment.createRun(config,    dataInputs = NULL, dataOutputs = NULL, dataRows = NULL,    materialInputs = NULL, materialOutputs = NULL)

Arguments

Details

Create an experiment run object which can be used in the saveBatch function.

Value

Returns the object representation of the experiment run object.

Author(s)

Karl Lum

See Also

labkey.experiment.saveBatch,labkey.experiment.createData,labkey.experiment.createMaterial

Examples

## Not run: library(Rlabkey)## create a non-assay backed run with samples as material inputs and outputsm1 <- labkey.experiment.createMaterial(        list(name = "87444063.2604.626"), sampleSetName = "Study Specimens")m2 <- labkey.experiment.createMaterial(        list(name = "87444063.2604.625"), sampleSetName = "Study Specimens")## create the run configuration and include optional run level propertiesrunConfig <- list(name="new run", properties <- list(textField="run prop 1", floatField=3.14))run <- labkey.experiment.createRun(        runConfig, materialInputs = m1, materialOutputs = m2)labkey.experiment.saveBatch(baseUrl="http://labkey/", folderPath="home",        protocolName=labkey.experiment.SAMPLE_DERIVATION_PROTOCOL, runList=run)## End(Not run)

Get lineage parent/child relationships for experiment objects

Description

Get lineage parent/child relationships and information for exp objects by LSID(s)

Usage

labkey.experiment.lineage(baseUrl=NULL, folderPath,    lsids, options = NULL)

Arguments

Details

This function retrieves lineage parent/child relationships and information for experiment objects by LSID(s).

Optional parameters (passed via options) include:

• parents (boolean) : include parent objects in the lineage

• children (boolean) : include child objects in the lineage

• depth (integer) : the depth of the lineage to retrieve

• expType (string) : the type of experiment objects to retrieve lineage for

• cpasType (string) : the type of CPAS object to retrieve lineage for

• runProtocolLsid (string) : the LSID of the run protocol to retrieve lineage for

• includeProperties (boolean) : include properties in the lineage response

• includeInputsAndOutputs (boolean) : include inputs and outputs in the lineage response

• includeRunSteps (boolean) : include run steps in the lineage response

Value

Returns a lineage response object based on the LSID seed values provided. The response object contains:

• seeds : the LSID of the object(s) requested

• nodes : an object with LSID keys for each lineage node and values containing the lineage information

Author(s)

Cory Nathe

Examples

## Not run: library(Rlabkey)labkey.experiment.lineage(  baseUrl="http://labkey/",  folderPath = "/home/OriginalFolder",  lsids=c("urn:lsid:labkey.com:Sample.519.Blood:23", "urn:lsid:labkey.com:Sample.519.Blood:12"),  options=list(    parents=TRUE,    children=TRUE,    depth=10,    expType="Material",    includeProperties=TRUE,    includeInputsAndOutputs=FALSE,    includeRunSteps=FALSE  ))## End(Not run)

Saves a modified experiment batch

Description

Saves a modified experiment batch.

Usage

labkey.experiment.saveBatch(baseUrl=NULL, folderPath,    assayConfig = NULL, protocolName = NULL,    batchPropertyList = NULL, runList)

Arguments

Details

Saves a modified batch. Runs within the batch may refer to existing data and material objects, either inputs or outputs,by ID or LSID. Runs may also define new data and materials objects by not specifying an ID or LSID in their properties.

Runs can be created for either assay or non-assay backed protocols. For an assay backed protocol, either the assayId orthe assayName and providerName name must be specified in the assayConfig parameter. If a non-assay backed protocol is to be used,specify the protocolName string value, note that currently only the simple : labkey.experiment.SAMPLE_DERIVATION_PROTOCOL is supported.

Refer to the labkey.experiment.createData, labkey.experiment.createMaterial, and labkey.experiment.createRun helper functionsto assemble the data structure that saveBatch expects.

Value

Returns the object representation of the experiment batch.

Author(s)

Karl Lum

See Also

labkey.experiment.createData,labkey.experiment.createMaterial,labkey.experiment.createRun

Examples

## Not run: library(Rlabkey)## uploads data to an existing assaydf <- data.frame(participantId=c(1:3), visitId = c(10,20,30), sex = c("f", "m", "f"))bprops <- list(LabNotes="this is a simple demo")bpl <- list(name=paste("Batch ", as.character(date())),properties=bprops)run <- labkey.experiment.createRun(list(name="new assay run"), dataRows = df)labkey.experiment.saveBatch(baseUrl="http://labkey/", folderPath="home",    assayConfig=list(assayName="GPAT", providerName="General"),    batchPropertyList=bpl, runList=run)## create a non-assay backed run with samples as material inputs and outputsm1 <- labkey.experiment.createMaterial(        list(name = "87444063.2604.626"), sampleSetName = "Study Specimens")m2 <- labkey.experiment.createMaterial(        list(name = "87444063.2604.625"), sampleSetName = "Study Specimens")run <- labkey.experiment.createRun(        list(name="new run"), materialInputs = m1, materialOutputs = m2)labkey.experiment.saveBatch(baseUrl="http://labkey/", folderPath="home",        protocolName=labkey.experiment.SAMPLE_DERIVATION_PROTOCOL, runList=run)## End(Not run)

Saves Runs.

Description

Saves experiment runs.

Usage

labkey.experiment.saveRuns(baseUrl=NULL, folderPath,    protocolName, runList)

Arguments

Details

Saves experiment runs. Runs may refer to existing data and material objects, either inputs or outputs,by ID or LSID. Runs may also define new data and materials objects by not specifying an ID or LSID in their properties.

Refer to the labkey.experiment.createData, labkey.experiment.createMaterial, and labkey.experiment.createRun helper functionsto assemble the data structure that saveRuns expects.

Value

Returns the object representation of the experiment run.

Author(s)

Ankur Juneja

See Also

labkey.experiment.createData,labkey.experiment.createMaterial,labkey.experiment.createRun

Examples

## Not run: library(Rlabkey)## example with materialInputs and materialOutputsm1 <- labkey.experiment.createMaterial(        list(name = "87444063.2604.626"), sampleSetName = "Study Specimens")m2 <- labkey.experiment.createMaterial(        list(name = "87444063.2604.625"), sampleSetName = "Study Specimens")run <- labkey.experiment.createRun(        list(name="new run"), materialInputs = m1, materialOutputs = m2)labkey.experiment.saveRuns(baseUrl="http://labkey/", folderPath="home",        protocolName=labkey.experiment.SAMPLE_DERIVATION_PROTOCOL, runList=run)## End(Not run)

Get the default baseUrl parameter used for all http or https requests

Description

Use this function to get "baseUrl" package environment variables to be used for all http or https requests.

Usage

labkey.getBaseUrl(baseUrl=NULL)

Arguments

Details

The function takes an optional baseUrl parameter. When non empty parameter is passed in and if baseUrlhas not been previously set, the function will remember the baseUrl value in package environment variables andreturn the formatted baseUrl. Skip baseUrl parameter to get previously set baseUrl.

Examples

## Not run: ## Example of getting previously set baseUrllibrary(Rlabkey)labkey.setDefaults(apiKey="abcdef0123456789abcdef0123456789",    baseUrl="http://labkey/")labkey.getBaseUrl()## End(Not run)

Retrieve the fields of a LabKey query view

Description

Fetch a list of output fields and their attributes that are avaialble from the default view of a given query

Usage

labkey.getDefaultViewDetails(baseUrl, folderPath,    schemaName, queryName)

Arguments

Details

Queries have a default “views” associeated with them. A query view can describe a subset or superset of the fields defined by the query. A query view is defined by using the “Customize View” button option on a LabKey data grid page.getDefaultViewDetails has the same arguments and returns the same shape of result data frame asgetQueryDetails.The default view is the what you will get back on callinglabkey.selectRows orgetRows.

Value

The output field attributes of the default view are returned as a data frame. Seelabkey.getQueryDetails for a description.

Author(s)

Peter Hussey, peter@labkey.com

See Also

labkey.selectRows,makeFilter,labkey.executeSql,labkey.updateRows,labkey.insertRows,labkey.importRows,labkey.deleteRows,labkey.getSchemas,labkey.getQueries,labkey.getQueryViews,labkey.getQueryDetails,labkey.getLookupDetails

Examples

## Not run: ## Details  of fields of a default query view# library(Rlabkey)queryDF <- labkey.getDefaultViewDetails(baseUrl="http://localhost:8080/labkey",folderPath="/apisamples",schemaName="lists",queryName="AllTypes")queryDF## End(Not run)

Retrieve a list of folders accessible to the current user

Description

Fetch a list of all folders accessible to the current user, starting from a given folder.

Usage

labkey.getFolders(baseUrl, folderPath,        includeEffectivePermissions=TRUE,        includeSubfolders=FALSE, depth=50,        includeChildWorkbooks=TRUE,        includeStandardProperties=TRUE)

Arguments

Details

Folders are a hierarchy of containers for data and files. The are the place where permissions are set in LabKey Server. The top level in a folder hierarchy is the project. Below the project is an arbitrary hierarchy of folders that can be used to partition data for reasons of security, visibility, and organization.

Folders cut across schemas. Some schemas, like the lists schema are not visible in a folder that has no list objects defined in it. Other schemas are visible in all folders.

Value

The available folders are returned as a three-column data frame containing

Author(s)

Peter Hussey, peter@labkey.com

See Also

labkey.getQueries,labkey.getQueryViews,labkey.getQueryDetails,labkey.getDefaultViewDetails,labkey.getLookupDetails,labkey.security.getContainers,labkey.security.createContainer,labkey.security.deleteContainer,labkey.security.moveContainerlabkey.security.renameContainer

Examples

## Not run: ## List of folders # library(Rlabkey)folders <- labkey.getFolders("https://www.labkey.org", "/home")folders## End(Not run)

Retrieve detailed information on a LabKey query

Description

Fetch a list of output columns and their attributes from the query referenced by a lookup field

Usage

labkey.getLookupDetails(baseUrl, folderPath,    schemaName, queryName, lookupKey)

Arguments

Details

WhengetQueryDetails returns non-NA values for the lookupQueryName, thegetLookupDetails function can be calledto enumerate the fields from the query referenced by the lookup. These lookup fields can be added to thecolSelect list ofselectRows.

Value

The available schemas are returned as a data frame, with the same columnsas detailed inlabkey.getQueryDetails

Author(s)

Peter Hussey, peter@labkey.com

See Also

labkey.selectRows,makeFilter,labkey.executeSql,labkey.updateRows,labkey.insertRows,labkey.importRows,labkey.deleteRows,labkey.getSchemas,labkey.getQueries,labkey.getQueryViews,labkey.getQueryDetails,labkey.getDefaultViewDetails

Examples

## Not run: ## Details  of fields of a query referenced by a lookup field# library(Rlabkey)lu1  <- labkey.getLookupDetails(baseUrl="http://localhost:8080/labkey",folderPath="/apisamples",schemaName="lists",queryName="AllTypes",lookupKey="Category")lu1## When a lookup field points to a query object that itself has a lookup## field, use a compound fieldkey consisting of the lookup fields from## the base query object to the target lookupDetails, separated by## forward slasheslu2<- labkey.getLookupDetails(baseUrl="http://localhost:8080/labkey",folderPath="/apisamples",schemaName="lists",queryName="AllTypes",lookupKey="Category/Group")lu2## Now select a result set containing a field from the base query, a## field from the 1st level of lookup, and one from the 2ndrows<- labkey.selectRows(baseUrl="http://localhost:8080/labkey",folderPath="/apisamples",schemaName="lists",queryName="AllTypes",colSelect=c("DisplayFld","Category/Category","Category/Group/GroupName"), colFilter = makeFilter(c("Category/Group/GroupName",   "NOT_EQUALS","TypeRange")), maxRows=20 ) rows## End(Not run)

Get effective module property value

Description

Get a specific effective module property value for folder

Usage

labkey.getModuleProperty(baseUrl=NULL, folderPath, moduleName, propName)

Arguments

Examples

## Not run: library(Rlabkey)labkey.getModuleProperty(baseUrl="http://labkey/", folderPath="flowProject",    moduleName="flow", propName="ExportToScriptFormat")## End(Not run)

Retrieve a list of available queries for a specified LabKey schema

Description

Fetch a list of queries available to the current user within in a specified folder context and specified schema

Usage

labkey.getQueries(baseUrl, folderPath, schemaName)

Arguments

Details

“Query” is the LabKey term for a data container that acts like a relational table within LabKey Server. Queries include lists, assay data results, user-defined queries, built-in SQL tables in individual modules, and tables or table-like objects in external schemas, For a specific queriable object,the data that is visible depends on the current user's permissions in a given folder.Function arguments identify the location of the server and the folder path.

Value

The available queries are returned as a three-column data frame containing one row for each field for each queryin the specified schema. The three columns are

Author(s)

Peter Hussey, peter@labkey.com

References

http://www.omegahat.net/RCurl/,
https://www.labkey.org/home/project-begin.view

See Also

labkey.selectRows,makeFilter,labkey.executeSql,labkey.updateRows,labkey.insertRows,labkey.importRows,labkey.deleteRows,labkey.getSchemas,labkey.getQueryViews,labkey.getQueryDetails,labkey.getDefaultViewDetails,labkey.getLookupDetails

Examples

## Not run: ## List of queries in a schema# library(Rlabkey)queriesDF <- labkey.getQueries(baseUrl="https://www.labkey.org",folderPath="/home",schemaName="lists")queriesDF## End(Not run)

Retrieve detailed information on a LabKey query

Description

Fetch a list of output columns and their attributes that are avaialble from a given query

Usage

labkey.getQueryDetails(baseUrl, folderPath, schemaName, queryName)

Arguments

Details

Queries have a default output list of fields defined by the "default view" of the query. To retrieve that set of fields with their detailed properties such as type and nullability, uselabkey.getQueryDetails function. Function arguments are the components of the url that identifythe location of the server, the folder path, the schema, and the name of the query.

The results from getQueryDetails describe the “field names” that are used to build the colSelect, colFilter and colSort parameters to selectRows. Each column in the data frame returned from selectRowscorresponds to a field in the colSelect list.
There are two types of fieldNames that will be reported by the server in the output of this function. For fields that aredirectly defined in the query corresponding the queryName parameter for this function, the fieldName is simply the name assigned by the query. Because selectRows returns the results specified by the default view, however,there may be cases where this default view incorporates data from other queries that have a defined 1-M relationshipwith the table designated by the queryName. Such fields in related tables are referred to as “lookup” fields.Lookup fields have multi-part names using a forward slash as the delimiter. For example, in a samples data set, if the ParticipantIdidentifies the source of the sample,ParticipantId/CohortId/CohortName could be a reference to aCohortName field in aCohorts data set.

These lookup fieldNames can appear in the default view and show up in the selectRows result. If a field from a lookup tableis not in the default view, it can still be added to the output column list oflabkey.selectRows. Use thelabkey.getLookups to discover what additional fields are available via lookups, and then put their multipart fieldName valuesinto the colSelect list. Lookup fields have the semantics of a LEFT JOIN in SQL, such thatevery record from the target queryName appears in the output whether or not there is a matching lookup field value.

Value

The available schemas are returned as a data frame:

Author(s)

Peter Hussey, peter@labkey.com

See Also

labkey.selectRows,makeFilter,labkey.executeSql,labkey.updateRows,labkey.insertRows,labkey.importRows,labkey.deleteRows,labkey.getSchemas,labkey.getQueries,labkey.getQueryViews,labkey.getDefaultViewDetails,labkey.getLookupDetails

Examples

## Not run: ## Details  of fields of a query# library(Rlabkey)queryDF<-labkey.getQueryDetails(baseUrl="http://localhost:8080/labkey",folderPath="/apisamples",schemaName="lists",queryName="AllTypes")## End(Not run)

Retrieve a list of available named views defined on a query in a schema

Description

Fetch a list of named query views available to the current user in a specified folder context, schema and query

Usage

labkey.getQueryViews(baseUrl, folderPath, schemaName, queryName)

Arguments

Details

Queries have a default “view” associeated with them, and can also have any number of named views.A named query view is created by using the “Customize View” button option on a LabKey data grid page. UsegetDefaultViewDetails to get inforation about the default (unnamed) view.

Value

The available views for a query are returned as a three-column data frame, with one row per view output field.

Author(s)

Peter Hussey, peter@labkey.com

References

https://www.labkey.org/Documentation/wiki-page.view?name=savingViews

See Also

labkey.selectRows,makeFilter,labkey.executeSql,labkey.updateRows,labkey.insertRows,labkey.importRows,labkey.deleteRows,labkey.getSchemas,labkey.getQueries,labkey.getQueryDetails,labkey.getDefaultViewDetails,labkey.getLookupDetails

Examples

## Not run: ## List of views defined for a query in a schema# library(Rlabkey)viewsDF <- labkey.getQueryViews(baseUrl="http://localhost:8080/labkey",folderPath="/apisamples",schemaName="lists",queryName="AllTypes")## End(Not run)

Helper function to get the HTTP request options for a specific method type.

Description

The internal functions for labkey.get() and labkey.post() use this labkey.getRequestOptions()helper to build up the HTTP request options for things like CSRF, CURL options, and authenticationproperties. This function is also exposed for general use if you would like to make your ownHTTP request but need to use those request options as set in your session context.

Usage

labkey.getRequestOptions(method = 'GET', encoding = NULL)

Arguments

Author(s)

Cory Nathe

Examples

## Not run: library(Rlabkey)labkey.getRequestOptions()## End(Not run)

Retrieve a list of available schemas from a labkey database

Description

Fetch a list of schemas available to the current user in a specified folder context

Usage

labkey.getSchemas(baseUrl, folderPath)

Arguments

Details

Schemas act as the name space for query objects in LabKey Server. Schemas are generatllyassociated with a LabKey Server "module" that provides some specific functionality. Within a queriable object,the specific data that is visible depends on the current user's permissions in a given folder.Function arguments are the components of the url that identify the location of the server and the folder path.

Value

The available schemas are returned as a single-column data frame.

Author(s)

Peter Hussey, peter@labkey.com

References

http://www.omegahat.net/RCurl/,
https://www.labkey.org/home/project-begin.view

See Also

labkey.selectRows,makeFilter,labkey.executeSql,labkey.updateRows,labkey.insertRows,labkey.importRows,labkey.deleteRows,labkey.getQueries,labkey.getQueryViews,labkey.getQueryDetails,labkey.getDefaultViewDetails,labkey.getLookupDetails,

Examples

## Not run: ## List of schemas# library(Rlabkey)schemasDF <- labkey.getSchemas(baseUrl="http://localhost:8080/labkey",folderPath="/apisamples")## End(Not run)

Import rows of data into a LabKey Server

Description

Bulk import rows of data into the database.

Usage

labkey.importRows(baseUrl, folderPath,    schemaName, queryName, toImport, na)

Arguments

Details

Multiple rows of data can be imported in bulk. ThetoImport data frame must containvalues for each column in the dataset and must be created with thestringsAsFactors optionset to FALSE. The names of the data in the data frame must be the column names from theLabKey Server. To import a value of NULL, use an empty string ("") in the data frame(regardless of the database column type). Also, when importing data into a study dataset, thesequence number must be specified.

Value

A list is returned with named categories ofcommand,rowsAffected,queryName,containerPath andschemaName.TheschemaName,queryName andcontainerPath properties contain the same schema, queryand folder path used in the request. TherowsAffected property indicates the number of rows affected by the API action. This will typically be the samenumber as passed in the request.

Author(s)

Cory Nathe

See Also

labkey.selectRows,labkey.executeSql,makeFilter,labkey.insertRows,labkey.updateRows,labkey.deleteRows,labkey.query.import

Examples

## Not run: ## Note that users must have the necessary permissions in the database## to be able to modify data through the use of these functions# library(Rlabkey)newrows <- data.frame(DisplayFld="Imported from R", RequiredText="abc", RequiredInt=1, stringsAsFactors=FALSE)newrows = newrows[rep(1:nrow(newrows),each=5),]importedInfo <- labkey.importRows("http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",    toImport=newrows)importedInfo$rowsAffected## End(Not run)

Insert new rows of data into a LabKey Server

Description

Insert new rows of data into the database.

Usage

labkey.insertRows(baseUrl, folderPath,    schemaName, queryName, toInsert, na,    provenanceParams=NULL, options=NULL)

Arguments

Details

A single row or multiple rows of data can be inserted. ThetoInsert data frame must containvalues for each column in the dataset and must be created with thestringsAsFactors optionset to FALSE. The names of the data in the data frame must be the column names from theLabKey Server.To insert a value of NULL, use an empty string ("") in the data frame (regardless of the database column type). Also, when inserting data into a study dataset, the sequence number must be specified.

The list of valid options for each query will vary, but some common examples include:

• auditBehavior (string) : Can be used to override the audit behavior for the table the query is acting on.The set of types include: NONE, SUMMARY, and DETAILED.

• auditUserComment (string) : Can be used to provide a comment from the user that will be attached tocertain detailed audit log records.

Value

A list is returned with named categories ofcommand,rowsAffected,rows,queryName,containerPath andschemaName.TheschemaName,queryName andcontainerPath properties contain the same schema, query and folder path used in the request. TherowsAffected property indicates the number of rows affected by the API action. This will typically be the samenumber as passed in the request. Therows property contains a list of row objects corresponding to the rows inserted.

Author(s)

Valerie Obenchain

See Also

labkey.selectRows,labkey.executeSql,makeFilter,labkey.importRows,labkey.updateRows,
labkey.deleteRows,labkey.moveRows,
labkey.query.import,labkey.provenance.createProvenanceParams,labkey.provenance.startRecording,labkey.provenance.addRecordingStep,labkey.provenance.stopRecording

Examples

## Not run: ## Insert, update and delete## Note that users must have the necessary permissions in the database## to be able to modify data through the use of these functions# library(Rlabkey)newrow <- data.frame(DisplayFld="Inserted from R", TextFld="how its done", IntFld= 98 , DoubleFld = 12.345, DateTimeFld = "03/01/2010", BooleanFld= FALSE, LongTextFld = "Four score and seven years ago"#, AttachmentFld = NA    #attachment fields not supported , RequiredText = "Veni, vidi, vici", RequiredInt = 0, Category = "LOOKUP2", stringsAsFactors=FALSE)insertedRow <- labkey.insertRows("http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",    toInsert=newrow, options=list(auditBehavior="DETAILED",    auditUserComment="testing audit comment for insert"))newRowId <- insertedRow$rows[[1]]$RowIdselectedRow<-labkey.selectRows("http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",    colFilter=makeFilter(c("RowId", "EQUALS", newRowId)))updaterow=data.frame(RowId=newRowId, DisplayFld="Updated from R", TextFld="how to update", IntFld= 777 , stringsAsFactors=FALSE)updatedRow <- labkey.updateRows("http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",    toUpdate=updaterow, options=list(auditBehavior="DETAILED",    auditUserComment="testing audit comment for update"))selectedRow<-labkey.selectRows("http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",    colFilter=makeFilter(c("RowId", "EQUALS", newRowId)))deleterow <- data.frame(RowId=newRowId, stringsAsFactors=FALSE)result <- labkey.deleteRows(baseUrl="http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",    toDelete=deleterow)## Example of creating a provenance run with an initial step with material inputs, a second step## with provenance mapping to link existing samples with newly inserted samples, and a final step## with a data output##mi <- data.frame(lsid=c("urn:lsid:labkey.com:Sample.251.MySamples:sample1",        "urn:lsid:labkey.com:Sample.251.MySamples:sample2"))p <- labkey.provenance.createProvenanceParams(name="step1", description="initial step",        materialInputs=mi)ra <- labkey.provenance.startRecording(baseUrl="https://labkey.org/labkey/",        folderPath = "Provenance", provenanceParams=p)rows <- fromJSON(txt='[{        "name" : "sample3",        "protein" : "p3",        "prov:objectInputs" : [            "urn:lsid:labkey.com:Sample.251.MySamples:sample21",            "urn:lsid:labkey.com:Sample.251.MySamples:sample22"        ]    },{        "name" : "sample4",        "protein" : "p4",        "prov:objectInputs" : [            "urn:lsid:labkey.com:Sample.251.MySamples:sample21",            "urn:lsid:labkey.com:Sample.251.MySamples:sample22"        ]    }]')labkey.insertRows(baseUrl="https://labkey.org/labkey/", folderPath = "Provenance",    schemaName="samples", queryName="MySamples", toInsert=rows,    provenanceParams=labkey.provenance.createProvenanceParams(name="query step",        recordingId=ra$recordingId))labkey.provenance.stopRecording(baseUrl="https://labkey.org/labkey/", folderPath = "Provenance",    provenanceParams=labkey.provenance.createProvenanceParams(name="final step",    recordingId=ra$recordingId, dataOutputs=do))## End(Not run)

Build a file path to data on a remote machine

Description

Replaces a local root with a remote root given a full path

Usage

labkey.makeRemotePath(localRoot, remoteRoot, fullPath)

Arguments

Details

A helper function to translate a file path on a LabKey web server to a path accessible by a remote machine. For example, if an R script is run on an R server that is a different machine than the LabKey server and that script references data files on the LabKey server, a remote path needs to be created to correctly reference these files. The local and remote roots of the data pipeline are included by LabKey in the prolog of an R View report script. Note that the data pipeline root references are only included if an administrator has enabled the Rserve Reports experimental feature on the LabKey server. If the remoteRoot is empty or the fullPath does not contain the localRoot then the fullPath is returned without its root being changed.

Value

A character array containing the full path.

Author(s)

Dax Hawkins

Examples

# library(Rlabkey)labkey.pipeline.root <- "c:/data/fcs"labkey.remote.pipeline.root <- "/volumes/fcs"fcsFile <- "c:/data/fcs/runA/aaa.fcs"# returns "/volumes/fcs/runA/aaa.fcslabkey.makeRemotePath(localRoot=labkey.pipeline.root,remoteRoot=labkey.remote.pipeline.root,fullPath=fcsFile);

Move rows of data from a LabKey database

Description

Specify rows of data to be moved from the LabKey Server

Usage

labkey.moveRows(baseUrl, folderPath, targetFolderPath,    schemaName, queryName, toMove, options=NULL)

Arguments

Details

Move a set of rows from the source container to a target container for a table. Note that this is not implemented forall tables.

The list of valid options for each query will vary, but some common examples include:

• auditBehavior (string) : Can be used to override the audit behavior for the table the query is acting on.The set of types include: NONE, SUMMARY, and DETAILED.

• auditUserComment (string) : Can be used to provide a comment from the user that will be attached tocertain detailed audit log records.

Value

A list is returned with named categories ofcommand,rowsAffected,schemaName,queryName,containerPath andupdateCounts.ThecontainerPath will be the target container path where the rows were moved.TherowsAffected property indicates the number of rows affected by the API action. This will typically be the samenumber as passed in the request.TheupdateCounts property is a list of the number of items moved for various related items.

Author(s)

Cory Nathe

See Also

labkey.deleteRows,
labkey.importRows,
labkey.importRows,
labkey.updateRows,

Examples

## Not run: ## Note that users must have the necessary permissions in the LabKey Server## to be able to modify data through the use of these functions# library(Rlabkey)newrow <- data.frame(DisplayFld="Inserted from R", IntFld= 98, DateTimeFld = "03/01/2010", stringsAsFactors=FALSE)insertedRow <- labkey.insertRows("http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="samples",    queryName="Blood", toInsert=newrow)newRowId <- insertedRow$rows[[1]]$RowIdresult <- labkey.moveRows(baseUrl="http://localhost:8080/labkey",    folderPath="/apisamples", folderPath="/apisamples/subA", schemaName="samples",    queryName="Blood",  toMove=data.frame(RowId=c(newRowId)),    options = list(auditUserComment="testing comment from API call", auditBehavior="DETAILED"))result## End(Not run)

Gets the protocol file status for a pipeline

Description

Gets the status of analysis using a particular protocol for a particular pipeline.

Usage

labkey.pipeline.getFileStatus(baseUrl=NULL, folderPath,        taskId, protocolName, path, files)

Arguments

Value

The response will contain a list of file status objects, i.e. files, each of whichwill have the following properties:

• "name": name of the file

• "status": status of the file

The response will also include the name of the action that would be performed onthe files if the user initiated processing, i.e. submitType.

Author(s)

Cory Nathe

See Also

labkey.pipeline.getPipelineContainer,labkey.pipeline.getProtocols,labkey.pipeline.startAnalysis

Examples

## Not run: labkey.pipeline.getFileStatus(    baseUrl="http://labkey/",    folderPath="home",    taskId = "pipelinetest:pipeline:r-copy",    path = "r-copy",    protocolName = "Test protocol name",    files = list("sample.txt", "result.txt"))## End(Not run)

Gets the container in which the pipeline is defined

Description

Gets the container in which the pipeline for this container is defined. This may be thecontainer in which the request was made, or a parent container if the pipeline was definedthere.

Usage

labkey.pipeline.getPipelineContainer(baseUrl=NULL, folderPath)

Arguments

Value

The response will contain the following:

• "containerPath": The container path in which the pipeline is defined.If no pipeline has been defined in this container hierarchy,then the value of this property will be null.

• "webDavURL": The WebDavURL for the pipeline root.

Author(s)

Cory Nathe

See Also

labkey.pipeline.getProtocols,labkey.pipeline.getFileStatus,labkey.pipeline.startAnalysis

Examples

## Not run: labkey.pipeline.getPipelineContainer(    baseUrl="http://labkey/",    folderPath="home")## End(Not run)

Gets the protocols that have been saved for a particular pipeline

Description

Gets the protocols that have been saved for a particular pipeline.

Usage

labkey.pipeline.getProtocols(baseUrl=NULL, folderPath,        taskId, path, includeWorkbooks = FALSE)

Arguments

Value

The response will contain a list of protocol objects, each of which will have thefollowing properties:

• "name": Name of the saved protocol.

• "description": Description of the saved protocol, if provided.

• "xmlParameters": Bioml representation of the parameters defined by this protocol.

• "jsonParameters": A list representation of the parameters defined by this protocol.

• "containerPath": The container path where this protocol was saved.

The response will also include a defaultProtocolName property representing which of the protocolnames is the default.

Author(s)

Cory Nathe

See Also

labkey.pipeline.getPipelineContainer,labkey.pipeline.getFileStatus,labkey.pipeline.startAnalysis

Examples

## Not run: labkey.pipeline.getProtocols(    baseUrl="http://labkey/",    folderPath="home",    taskId = "pipelinetest:pipeline:r-copy",    path = "r-copy",    includeWorkbooks = FALSE)## End(Not run)

Start an analysis of a set of files using a pipeline

Description

Starts analysis of a set of files using a particularprotocol definition with a particular pipeline.

Usage

labkey.pipeline.startAnalysis(baseUrl=NULL, folderPath,    taskId, protocolName, path, files, fileIds = list(),    pipelineDescription = NULL, protocolDescription = NULL,    jsonParameters = NULL, xmlParameters = NULL,    allowNonExistentFiles = FALSE, saveProtocol = TRUE)

Arguments

Value

On success, the response will contain the jobGUID string value for the newly created pipeline job.

Author(s)

Cory Nathe

See Also

labkey.pipeline.getPipelineContainer,labkey.pipeline.getProtocols,labkey.pipeline.getFileStatus

Examples

## Not run: labkey.pipeline.startAnalysis(    baseUrl="http://labkey/",    folderPath="home",    taskId = "pipelinetest:pipeline:r-copy",    protocolName = "Test protocol name",    path="r-copy",    files = list("sample.txt", "result.txt"),    protocolDescription = "Test protocol description",    pipelineDescription = "test pipeline description",    jsonParameters = list(assay = "Test assay name", comment = "Test assay comment"),    saveProtocol = TRUE)## End(Not run)

Add a step to a provenance recording

Description

Function to add a step to a previously created provenance recording session.Note: this function is in beta and not yet final, changes should be expected so exercise caution when using it.

Usage

labkey.provenance.addRecordingStep(baseUrl=NULL, folderPath, provenanceParams = NULL)

Arguments

Details

Function to add a step to a previously created provenance recording. The recording ID that was obtained froma previous startRecording function call must be passed into the provenanceParams config.This is a premium feature and requires the Provenance LabKey module to function correctly.

Value

The generated recording ID which can be used in subsequent steps (or queries that support provenance).

Author(s)

Karl Lum

See Also

labkey.provenance.createProvenanceParams,labkey.provenance.startRecording,labkey.provenance.stopRecording

Examples

## Not run: ## start a provenance recording and add a recording steplibrary(Rlabkey)mi <- data.frame(lsid=c("urn:lsid:labkey.com:Sample.251.MySamples:sample1",        "urn:lsid:labkey.com:Sample.251.MySamples:sample2"))p <- labkey.provenance.createProvenanceParams(name="step1", description="initial step",        materialInputs=mi)r <- labkey.provenance.startRecording(baseUrl="https://labkey.org/labkey/",        folderPath = "Provenance", provenanceParams=p)do <- data.frame(        lsid="urn:lsid:labkey.com:AssayRunTSVData.Folder-251:12c70994-7ce5-1038-82f0-9c1487dbd334")labkey.provenance.addRecordingStep(baseUrl="https://labkey.org/labkey/", folderPath = "Provenance",    provenanceParams=labkey.provenance.createProvenanceParams(name="additional step",        recordingId=r$recordingId, dataOutputs=do))## End(Not run)

Create provenance parameter object

Description

Helper function to create the data structure that can be used in provenance related APIs.Note: this function is in beta and not yet final, changes should be expected so exercise caution when using it.

Usage

labkey.provenance.createProvenanceParams(recordingId=NULL, name=NULL, description=NULL,        runName=NULL, materialInputs=NULL, materialOutputs=NULL, dataInputs=NULL,        dataOutputs=NULL, inputObjectUriProperty=NULL, outputObjectUriProperty=NULL,        objectInputs=NULL, objectOutputs=NULL, provenanceMap=NULL,        params=NULL, properties=NULL)

Arguments

Details

This function can be used to generate a provenance parameter object which can then be used as an argumentin the other provenance related functions to assemble provenance runs.This is a premium feature and requires the Provenance LabKey module to function correctly.

Value

A list containing elements describing the passed in provenance parameters.

Author(s)

Karl Lum

See Also

labkey.provenance.startRecording,labkey.provenance.addRecordingStep,labkey.provenance.stopRecording

Examples

## Not run: ## create provenance params with material inputs and data outputslibrary(Rlabkey)mi <- data.frame(lsid=c("urn:lsid:labkey.com:Sample.251.MySamples:sample1",        "urn:lsid:labkey.com:Sample.251.MySamples:sample2"))do <- data.frame(        lsid="urn:lsid:labkey.com:AssayRunTSVData.Folder-251:12c70994-7ce5-1038-82f0-9c1487dbd334")p <- labkey.provenance.createProvenanceParams(name="step1", description="initial step",        materialInputs=mi, dataOutputs=do)## create provenance params with object inputs (from an assay run)oi <- labkey.selectRows(baseUrl="https://labkey.org/labkey/", folderPath = "Provenance",        schemaName="assay.General.titer",        queryName="Data",        colSelect= c("LSID"),        colFilter=makeFilter(c("Run/RowId","EQUAL","253")))mi <- data.frame(lsid=c("urn:lsid:labkey.com:Sample.251.MySamples:sample1",        "urn:lsid:labkey.com:Sample.251.MySamples:sample2"))p <- labkey.provenance.createProvenanceParams(name="step1", description="initial step",        objectInputs=oi[["LSID"]], materialInputs=mi)## add run step properties and custom properties to the provenance paramsprops <- data.frame(    "urn:lsid:labkey.com:Vocabulary.Folder-996:ProvenanceDomain#version"=c(22.3),    "urn:lsid:labkey.com:Vocabulary.Folder-996:ProvenanceDomain#instrumentName"=c("NAb reader"),    check.names=FALSE)params <- list()params$comments <- "adding additional step properties"params$activityDate <- "2022-3-21"params$startTime <- "2022-3-21 12:35:00"params$endTime <- "2022-3-22 02:15:30"params$recordCount <- 2p <- labkey.provenance.createProvenanceParams(recordingId=ra$recordingId, name="step2",    properties=props, params=params)## End(Not run)

Start a provenance recording

Description

Function to start a provenance recording session, if successful a provenance recording ID is returned whichcan be used to add additional steps to the provenance run.Note: this function is in beta and not yet final, changes should be expected so exercise caution when using it.

Usage

labkey.provenance.startRecording(baseUrl=NULL, folderPath, provenanceParams = NULL)

Arguments

Details

Function to start a provenance recording. A provenance recording can contain an arbitrary number of steps to create aprovenance run, but stopRecording must be called to finish the recording and create the run. If successfulthis will return a recording ID which is needed for subsequent steps.This is a premium feature and requires the Provenance LabKey module to function correctly.

Value

The generated recording ID which can be used in subsequent steps (or queries that support provenance).

Author(s)

Karl Lum

See Also

labkey.provenance.createProvenanceParams,labkey.provenance.addRecordingStep,labkey.provenance.stopRecording

Examples

## Not run: ## create provenance params with material inputs and data outputs and start a recordinglibrary(Rlabkey)mi <- data.frame(lsid=c("urn:lsid:labkey.com:Sample.251.MySamples:sample1",        "urn:lsid:labkey.com:Sample.251.MySamples:sample2"))do <- data.frame(        lsid="urn:lsid:labkey.com:AssayRunTSVData.Folder-251:12c70994-7ce5-1038-82f0-9c1487dbd334")p <- labkey.provenance.createProvenanceParams(name="step1", description="initial step",        materialInputs=mi, dataOutputs=do)labkey.provenance.startRecording(baseUrl="https://labkey.org/labkey/",        folderPath = "Provenance", provenanceParams=p)## End(Not run)

Stop a provenance recording

Description

Function to end a provenance recording and create and save the provenance run on the server.Note: this function is in beta and not yet final, changes should be expected so exercise caution when using it.

Usage

labkey.provenance.stopRecording(baseUrl=NULL, folderPath, provenanceParams = NULL)

Arguments

Details

Function to stop the provenance recording associated with the recording ID, this will create a provenance runusing all the steps (with inputs and outputs) associated with the recording ID. The recording ID that was obtained froma previous startRecording function call must be passed into the provenanceParams config.This is a premium feature and requires the Provenance LabKey module to function correctly.

Value

The serialized provenance run that was created.

Author(s)

Karl Lum

See Also

labkey.provenance.createProvenanceParams,labkey.provenance.startRecording,labkey.provenance.addRecordingStep

Examples

## Not run: library(Rlabkey)## object inputs (from an assay run) and material inputs##oi <- labkey.selectRows(baseUrl="https://labkey.org/labkey/", folderPath = "Provenance",        schemaName="assay.General.titer",        queryName="Data",        colSelect= c("LSID"),        colFilter=makeFilter(c("Run/RowId","EQUAL","253")))mi <- data.frame(lsid=c("urn:lsid:labkey.com:Sample.251.MySamples:sample1",        "urn:lsid:labkey.com:Sample.251.MySamples:sample2"))p <- labkey.provenance.createProvenanceParams(name="step1", description="initial step",        objectInputs=oi[["LSID"]], materialInputs=mi)r <- labkey.provenance.startRecording(baseUrl="https://labkey.org/labkey/",        folderPath = "Provenance", provenanceParams=p)run <- labkey.provenance.stopRecording(baseUrl="https://labkey.org/labkey/",        folderPath = "Provenance",        provenanceParams=labkey.provenance.createProvenanceParams(name="final step",            recordingId=r$recordingId))## End(Not run)

Bulk import an R data frame into a LabKey Server table using file import.

Description

Bulk import an R data frame into a LabKey Server table using file import.

Usage

labkey.query.import(baseUrl, folderPath,    schemaName, queryName, toImport, options = NULL)

Arguments

Details

This command mimics the "Import bulk data" option that you see in the LabKey server UIfor a table/query. It takes the passed intoImport data frame and writes it to atemp file to be posted to the import action for the given LabKey query. It is very similarto thelabkey.importRows command but will be much more performant.

Multiple rows of data can be imported in bulk using thetoImport data frame.The names of the data in the data frame must be the column names from theLabKey Server.

LabKey data types support different import options. The list of valid options for eachquery will vary, but some common examples include:

• insertOption (string) : Whether the import action should be done as an insert, creating newrows for each provided row of the data frame, or a merge. When merging during import, any data you providefor the rows representing records that already exist will replace the previous values.Note that when updating an existing record, you only need to provide the columns you wish to update,existing data for other columns will be left as is. Available options are "INSERT" and "MERGE".Defaults to "INSERT".

• auditBehavior (string) : Set the level of auditing details for this import action.Available options are "SUMMARY" and "DETAILED". SUMMARY - Audit log reflects that a change was made,but does not mention the nature of the change. DETAILED - Provides full details on what change was made,including values before and after the change. Defaults to the setting as specified by the LabKey query.

• importLookupByAlternateKey (boolean) : Allows lookup target rows to be resolved by valuesrather than the target's primary key. This option will only be available for lookups that areconfigured with unique column information. Defaults to FALSE.

Value

A list is returned with the row count for the number of affected rows. If options are provided,additional details may be included in the response object related to those options.

Author(s)

Cory Nathe

See Also

labkey.insertRows,labkey.updateRows,labkey.importRows

Examples

## Not run: ## Note that users must have the necessary permissions in the database## to be able to modify data through the use of these functions# library(Rlabkey)df <- data.frame(    name=c("test1","test2","test3"),    customInt=c(1:3),    customString=c("aaa", "bbb", "ccc"))importedInfo <- labkey.query.import(    "http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="samples", queryName="SampleType1",    toImport=df, options=list(insertOption = "MERGE", auditBehavior = "DETAILED"))importedInfo$rowCount## End(Not run)

Initialize a RStudio session for LabKey integration

Description

LabKey-RStudio integration helper. Not intended for use outside RStudio.

Usage

labkey.rstudio.initRStudio(apiKey = "", baseUrl = "", folderPath, skipViewer = FALSE)

Arguments

Examples

## Not run: ## RStudio console onlylibrary(Rlabkey)labkey.rstudio.initRStudio(apiKey="abcdef0123456789abcdef0123456789",    baseUrl="http://labkey/", folderPath="home")## End(Not run)

Initialize a RStudio session for LabKey R report source editing

Description

LabKey-RStudio integration helper. Not intended for use outside RStudio.

Usage

labkey.rstudio.initReport(apiKey = "", baseUrl = "", folderPath,  reportEntityId, skipViewer = FALSE, skipEdit = FALSE)

Arguments

Examples

## Not run: ## RStudio console onlylibrary(Rlabkey)labkey.rstudio.initReport(apiKey="abcdef0123456789abcdef0123456789",    baseUrl="http://labkey/", folderPath="home",    reportEntityId="0123456a-789b-1000-abcd-01234567abcde")## End(Not run)

Initialize a RStudio session for LabKey integration using a time one request id

Description

LabKey-RStudio integration helper. Not intended for use outside RStudio.

Usage

labkey.rstudio.initSession(requestId, baseUrl)

Arguments

Examples

## Not run: ## RStudio console onlylibrary(Rlabkey)labkey.rstudio.initSession(requestId="a60228c8-9448-1036-a7c5-ab541dc15ee9",    baseUrl="http://labkey/")## End(Not run)

Check valid rlabkey session

Description

LabKey-RStudio integration helper. Not intended for use outside RStudio.

Usage

labkey.rstudio.isInitialized()

Examples

## Not run: ## RStudio console onlylibrary(Rlabkey)labkey.rstudio.isInitialized()## End(Not run)

Update RStudio report source back to LabKey

Description

LabKey-RStudio integration helper. Not intended for use outside RStudio.

Usage

labkey.rstudio.saveReport(folderPath, reportEntityId, reportFilename,  useWarning = FALSE)

Arguments

Examples

## Not run: ## RStudio console onlylibrary(Rlabkey)labkey.rstudio.saveReport(folderPath="home",    reportEntityId="0123456a-789b-1000-abcd-01234567abcde",    reportFilename="knitrReport.Rhtml", useWarning=TRUE)## End(Not run)

Save an assay batch object to a labkey database

Description

Save an assay batch object to a labkey database

Usage

labkey.saveBatch(baseUrl, folderPath, assayName, resultDataFrame,    batchPropertyList=NULL, runPropertyList=NULL)

Arguments

Details

This function has been deprecated and will be removed in a future release, please use labkey.experiment.saveBatch instead asit supports the newer options for saving batch objects.

To save an R data.frame an assay results sets, you must create a named assay using the "General" assay provider.Note that saveBatch currently supports only a single run with one result set per batch.

Value

Returns the object representation of the Assay batch.

Author(s)

Peter Hussey

References

https://www.labkey.org/Documentation/wiki-page.view?name=createDatasetViaAssay

See Also

labkey.selectRows,labkey.executeSql,makeFilter,labkey.updateRows,
labkey.deleteRows,labkey.experiment.saveBatch

Examples

## Not run: ## Very simple example of an analysis flow:  query some data, calculate## some stats, then save the calculations as an assay result set in## LabKey Server##  Note this example expects to find an assay named "SimpleMeans" in##  the apisamples project# library(Rlabkey)simpledf <- labkey.selectRows(baseUrl="http://localhost:8080/labkey",folderPath="/apisamples",schemaName="lists", queryName="AllTypes")## some dummy calculations to produce and example analysis resulttesttable <- simpledf[,3:4]colnames(testtable) <- c("IntFld", "DoubleFld")row <- c(list("Measure"="colMeans"), colMeans(testtable, na.rm=TRUE))results <- data.frame(row, row.names=NULL, stringsAsFactors=FALSE)row <- c(list("Measure"="colSums"), colSums(testtable, na.rm=TRUE))results <- rbind(results, as.vector(row))bprops <- list(LabNotes="this is a simple demo")bpl <- list(name=paste("Batch ", as.character(date())),properties=bprops) rpl <- list(name=paste("Assay Run ", as.character(date())))assayInfo<- labkey.saveBatch(baseUrl="http://localhost:8080/labkey",folderPath="/apisamples","SimpleMeans", results, batchPropertyList=bpl,runPropertyList=rpl)## End(Not run)

Creates a new container, which may be a project, folder, or workbook, on the server

Description

Create a new container, which may be a project, folder, or workbook, on the LabKey server with parameters to controlthe containers name, title, description, and folder type.

Usage

labkey.security.createContainer(baseUrl=NULL, parentPath, name = NULL, title = NULL,    description = NULL, folderType = NULL, isWorkbook = FALSE)

Arguments

Details

This function allows for users with proper permissions to create a new container, which may be a project, folder, orworkbook, on the LabKey server with parameters to control the containers name, title, description, and folder type.If the container already exists or the user does not have permissions, an error message will be returned.

Value

Returns information about the newly created container.

Author(s)

Cory Nathe

See Also

labkey.getFolders,labkey.security.getContainers,labkey.security.deleteContainer,labkey.security.moveContainerlabkey.security.renameContainer

Examples

## Not run: library(Rlabkey)labkey.security.createContainer(baseUrl="http://labkey/", parentPath = "/home",    name = "NewFolder", description = "My new folder has this description",    folderType = "Collaboration")## End(Not run)

Deletes an existing container, which may be a project, folder, or workbook

Description

Deletes an existing container, which may be a project, folder, or workbook, and all of its children from the Labeky server.

Usage

labkey.security.deleteContainer(baseUrl=NULL, folderPath)

Arguments

Details

This function allows for users with proper permissions to delete an existing container, which may be a project, folder,or workbook, from the LabKey server. This will also remove all subfolders of the container being deleted.If the container does not exist or the user does not have permissions, an error message will be returned.

Value

Returns a success message for the container deletion action.

Author(s)

Cory Nathe

See Also

labkey.getFolders,labkey.security.getContainers,labkey.security.createContainer,labkey.security.moveContainerlabkey.security.renameContainer

Examples

## Not run: library(Rlabkey)labkey.security.deleteContainer(baseUrl="http://labkey/", folderPath = "/home/FolderToDelete")## End(Not run)

Returns information about the specified container

Description

Returns information about the specified container, including the user's current permissions within that container.If the includeSubfolders config option is set to true, it will also return information about all descendantsthe user is allowed to see.

Usage

labkey.security.getContainers(baseUrl=NULL, folderPath,    includeEffectivePermissions=TRUE, includeSubfolders=FALSE, depth=50,    includeChildWorkbooks=TRUE, includeStandardProperties = TRUE)

Arguments

Details

This function returns information about the specified container, including the user's current permissions within that container.If the includeSubfolders config option is set to true, it will also return information about all descendantsthe user is allowed to see. The depth of the results for the included subfolders can be controlled with the depth parameter.

Value

The data frame containing the container properties for the current folder and subfolders, including name, title, id,path, type, folderType, and effectivePermissions.

Author(s)

Cory Nathe

See Also

labkey.getFolders,labkey.security.createContainer,labkey.security.deleteContainer,labkey.security.moveContainerlabkey.security.renameContainer

Examples

## Not run: library(Rlabkey)labkey.security.getContainers(    baseUrl="http://labkey/", folderPath = "home",    includeEffectivePermissions = FALSE, includeSubfolders = TRUE, depth = 2,    includeChildWorkbooks = FALSE, includeStandardProperties = FALSE)## End(Not run)

Start impersonating a user

Description

For site-admins or project-admins only, start impersonating a user based on theuserId or email address.

Usage

labkey.security.impersonateUser(baseUrl=NULL, folderPath,    userId=NULL, email=NULL)

Arguments

Details

Admins may impersonate other users to perform actions on their behalf.Site admins may impersonate any user in any project. Project admins mustexecute this command in a project in which they have admin permissionand may impersonate only users that have access to the project.

To finish an impersonation session uselabkey.security.stopImpersonating.

Value

Returns a success message based on a call tolabkey.whoAmI.

Author(s)

Cory Nathe

See Also

labkey.whoAmI,labkey.security.stopImpersonating

Examples

## Not run: library(Rlabkey)labkey.security.impersonateUser(baseUrl="http://labkey/", folderPath = "/home",    email = "reader@localhost.test")## End(Not run)

Moves an existing container, which may be a folder or workbook

Description

Moves an existing container, which may be a folder or workbook, to be the subfolder of another folder and/or projecton the LabKey server.

Usage

labkey.security.moveContainer(baseUrl=NULL, folderPath,    destinationParent, addAlias = TRUE)

Arguments

Details

This function moves an existing container, which may be a folder or workbook, to be the subfolder of anotherfolder and/or project on the LabKey server. Projects and the root container can not be moved.If the target or destination container does not exist or the user does not have permissions, an error message willbe returned.

Value

Returns a success message for the container move action with the new path.

Author(s)

Cory Nathe

See Also

labkey.getFolders,labkey.security.getContainers,labkey.security.createContainer,labkey.security.deleteContainerlabkey.security.renameContainer

Examples

## Not run: library(Rlabkey)labkey.security.moveContainer(baseUrl="http://labkey/", folderPath = "/home/FolderToMove",    destinationParent = "/OtherProject", addAlias = TRUE)## End(Not run)

Rename an existing container at the given container path

Description

Renames an existing container at the given container path.This action allows for updating the container name, title, or both.

Usage

labkey.security.renameContainer(baseUrl=NULL, folderPath,    name=NULL, title=NULL, addAlias=TRUE)

Arguments

Details

This function renames an existing container at the given container path on the LabKey server.A new container name and/or title must be specified. If a new name is provided but not a title, the name will alsobe set as the container title.

Value

Returns a success message for the container rename action.

Author(s)

Cory Nathe

See Also

labkey.getFolders,labkey.security.getContainers,labkey.security.createContainer,labkey.security.deleteContainerlabkey.security.moveContainer

Examples

## Not run: library(Rlabkey)labkey.security.renameContainer(baseUrl="http://labkey/", folderPath = "/home/OriginalFolder",    name = "NewFolderName", title = "New Folder Title", addAlias = TRUE)## End(Not run)

Stop impersonating a user

Description

Stop impersonating a user while keeping the original user logged in.

Usage

labkey.security.stopImpersonating(baseUrl=NULL)

Arguments

Details

If you are currently impersonating a user in this session, you can use thisfunction to stop the impersonation and return back to the original user logged in.

To start an impersonation session uselabkey.security.impersonateUser.

Value

Returns a success message based on a call tolabkey.whoAmI.

Author(s)

Cory Nathe

See Also

labkey.whoAmI,labkey.security.impersonateUser

Examples

## Not run: library(Rlabkey)labkey.security.stopImpersonating(baseUrl="http://labkey/")## End(Not run)

Retrieve data from a labkey database

Description

Import full datasets or selected rows into R. The data can be sorted and filtered prior to import.

Usage

labkey.selectRows(baseUrl = NULL, folderPath, schemaName, queryName,    viewName = NULL, colSelect = NULL, maxRows = NULL,    rowOffset = NULL, colSort = NULL, colFilter = NULL,    showHidden = FALSE, colNameOpt="caption",    containerFilter = NULL, parameters = NULL,    includeDisplayValues = FALSE, method = "POST")

Arguments

Details

A full dataset or any portion of a dataset can be downloaded into an R data frame using thelabkey.selectRows function. Function arguments are the components of the url that identifythe location of the data and what actions should be taken on the data prior to import(ie, sorting, selecting particular columns or maximum number of rows, etc.).

Stored queries in LabKey Server have an associated default view and may have one or more named views. Views determine the column set ofthe return data frame. View columns can be a subset or superset of the columns of the underlying query (a subset if columns from thequery are left out of the view, and a superset if lookup columns in the underlying query are used to include columns from related queries).Views can also include filter and sort properties that will make their result set different from the underlying query.If no view is specified, the columns and rows returned are determined by the default view, which may not be the same as the result rows of the underlying query. Please see the topic on Saving Views in the LabKey online documentation.

In the returned data frame, there are three different ways to have the columns named:colNameOpt='caption' uses the caption value, and is the default option for backward compatibility. It may be the best option for displaying to another user, but may make scripting more difficult.colNameOpt='fieldname' uses the field name value, so that the data frame colnames are the same namesthat are used as arguments to labkey function calls. It is the default for the newgetRows session-basedfunction.colNameOpt='rname' transforms the field name value into valid R names by substituting an underscore for bothspaces and forward slash (/) characters and lower casing the entire name. This option is the way a data frame is passed to ascript running in a LabKey server in the R View feature of the data grid. If you are writing scripts for running in anR view on the server, or if you prefer to work with legal r names in the returned grid, this option may be useful.

For backward compatibility, column names returned bylabkey.executeSql andlabkey.selectRows are field captions by default. ThegetRows function has the samecolNameOpt parameter but defaults to field names instead of captions.

Value

The requested data are returned in a data frame with stringsAsFactors set to FALSE. Column names are set as determined by the colNameOpt parameter.

Author(s)

Valerie Obenchain

References

https://www.labkey.org/Documentation/wiki-page.view?name=savingViews

See Also

makeFilter,labkey.executeSql,labkey.updateRows,labkey.insertRows,labkey.importRows,labkey.deleteRows,labkey.getSchemas,labkey.getQueries,labkey.getQueryViews,labkey.getQueryDetails,labkey.getDefaultViewDetails,labkey.getLookupDetails

Examples

## Not run: ## select from a list named AllTypes# library(Rlabkey)rows <- labkey.selectRows(baseUrl="http://localhost:8080/labkey",folderPath="/apisamples",schemaName="lists", queryName="AllTypes")## select from a view on that listviewrows <- labkey.selectRows(baseUrl="http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="Lists", queryName="AllTypes",    viewName="rowbyrow")## select a subset of columnscolSelect=c("TextFld", "IntFld")subsetcols <- labkey.selectRows(baseUrl="http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",    colSelect=colSelect)## including columns from a lookup (foreign key) fieldlookupcols <- labkey.selectRows(baseUrl="http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",    colSelect="TextFld,IntFld,IntFld/LookupValue")## End(Not run)

Modify the current set of Curl options that are being used in the existing session

Description

Rlabkey uses the package httr to connect to the LabKey Server.

Arguments

Details

This topic explains how to configure Rlabkey to work with a LabKey Server running SSL.

Rlabkey uses the package httr to connect to the LabKey Server. On Windows, the httr package is not configured for SSLby default. In order to connect to a HTTPS enabled LabKey Server, you will need to perform the following steps:

1. Create or download a "ca-bundle" file.

We recommend using ca-bundle file that is published by Mozilla. See http://curl.haxx.se/docs/caextract.html. You have two options:

Download the ca-bundle.crt file from the link named "HTTPS from github:" on http://curl.haxx.se/docs/caextract.html
Create your own ca-bundle.crt file using the instructions provided on http://curl.haxx.se/docs/caextract.html

2. Copy the ca-bundle.crt file to a location on your hard-drive.
If you will be the only person using the Rlabkey package on your computer, we recommend that you

create a directory named 'labkey' in your home directory
copy the ca-bundle.crt into the 'labkey' directory

If you are installing this file on a server where multiple users will use may use the Rlabkey package, we recommend that youcreate a directory named 'c:labkey'

copy the ca-bundle.crt into the 'c:labkey' directory

3. Create a new Environment variable named 'RLABKEY_CAINFO_FILE'

On Windows 7, Windows Server 2008 and earlier

Select Computer from the Start menu.
Choose System Properties from the context menu.
Click Advanced system settings > Advanced tab.
Click on Environment Variables.
Under System Variables click on the new button.
For Variable Name: enter RLABKEY_CAINFO_FILE
For Variable Value: enter the path of the ca-bundle.crt you created above.
Hit the Ok buttons to close all the windows.
On Windows 8, Windows 2012 and above
Drag the Mouse pointer to the Right bottom corner of the screen.
Click on the Search icon and type: Control Panel.
Click on -> Control Panel -> System and Security.
Click on System -> Advanced system settings > Advanced tab.
In the System Properties Window, click on Environment Variables.
Under System Variables click on the new button.
For Variable Name: enter RLABKEY_CAINFO_FILE
For Variable Value: enter the path of the ca-bundle.crt you created above.
Hit the Ok buttons to close all the windows.
Now you can start R and begin working.

This command can also be used to provide an alternate location / path to your.netrc file. Example:
labkey.setCurlOptions(NETRC_FILE = '/path/to/alternate/_netrc')

Helper function to enable/disable debug mode.

Description

When debug mode is enabled, the GET/POST calls with output information about the request being madeand will output a raw string version of the response object.

Usage

labkey.setDebugMode(debug = FALSE)

Arguments

Author(s)

Cory Nathe

Examples

## Not run: library(Rlabkey)labkey.setDebugMode(TRUE)labkey.executeSql(    baseUrl="http://localhost:8080/labkey",    folderPath="/home",    schemaName="core",    sql = "select * from containers")## End(Not run)

Set the default parameters used for all http or https requests

Description

Use this function to set the default baseUrl and authentication parameters as package environment variables to be usedfor all http or https requests. You can also use labkey.setDefaults() without any parameters to reset/clearthese settings.

Usage

labkey.setDefaults(apiKey="", baseUrl="", email="", password="")

Arguments

Details

An API key can be used to authorize Rlabkey functions that access secure content on LabKey Server. Using an API keyavoids copying and storing credentials on the client machine. An API key can be revoked and set to expire. It alsoacts as a credential for those who sign in using a single sign-on authentication mechanism such as CAS or SAML.

A site administrator must first enable the use of API keys on that LabKey Server. Once enabled, any logged in user cangenerate an API key by clicking their display name (upper right) and selecting "External Tool Access". The API Key pagecreates and displays keys that can be copied and pasted into a labkey.setDefaults() statement to give an Rlabkeysession the permissions of the corresponding user.

If an API key is not provided, you can also use this function for basic authentication via email and password. Notethat both email and password must be set via a labkey.setDefaults() call. If an API key is also set, that will be givenpreference and the email/password will not be used for authentication.

On servers that enable them, a session key can be used in place of an API key. A session key ties all Rlabkey accessto a user's current browser session, which means the code runs in the same context as the browser (e.g. same user,same authorizations, same declared terms of use and PHI level, same impersonation state, etc.). Session keys can beuseful in certain compliance scenarios.

Once valid credentials are provided to labkey.setDefaults(), subsequent labkey.get or labkey.post API calls willauthenticate using those credentials.

Examples

## Example of setting and clearing email/password, API key, and Session key# library(Rlabkey)labkey.setDefaults(email="testing@localhost.test", password="password")## Functions invoked at this point respect the role assignments and## other authorizations of the specified user## A user can create an API key via the LabKey UI and set it as follows:labkey.setDefaults(apiKey="abcdef0123456789abcdef0123456789")## Functions invoked at this point respect the role assignments and## other authorizations of the user who created the API key## A user can create a session key via the LabKey UI and set it as follows:labkey.setDefaults(apiKey="0123456789abcdef0123456789abcdef")## Functions invoked at this point share authorization## and session information with the user's browser sessionlabkey.setDefaults() # called without any parameters will reset/clear the environment variables

Set module property value

Description

Set module property value for a specific folder or as site wide (with folderPath '/')

Usage

labkey.setModuleProperty(baseUrl=NULL, folderPath, moduleName, propName, propValue)

Arguments

Examples

## Not run: library(Rlabkey)labkey.setModuleProperty(baseUrl="http://labkey/", folderPath="flowProject",    moduleName="flow", propName="ExportToScriptFormat", propValue="zip")## End(Not run)

Helper function to enable/disable wafEncoding mode.

Description

By default, this command encodes the SQL parameter to allow it to pass through web applicationfirewalls. This is compatible with LabKey Server v23.9.0 and above. If targeting an earlierserver, pass FALSE to this method.

Usage

labkey.setWafEncoding(wafEncode = TRUE)

Arguments

Author(s)

Cory Nathe

Examples

## Not run: library(Rlabkey)labkey.setWafEncoding(FALSE)labkey.executeSql(    baseUrl="http://localhost:8080/labkey",    folderPath="/home",    schemaName="core",    sql = "select * from containers")## End(Not run)

Create a new LabKey Freezer Manager storage item

Description

Create a new LabKey Freezer Manager storage item that can be used in the creation of a storage hierarchy.Storage items can be of the following types: Physical Location, Freezer, Primary Storage, Shelf, Rack, Canister,Storage Unit Type, or Terminal Storage Location.

Usage

labkey.storage.create(baseUrl=NULL, folderPath, type, props)

Arguments

Value

A list containing a data element with the property values for the newly created storage item.

Author(s)

Cory Nathe

See Also

labkey.storage.update,labkey.storage.delete

Examples

## Not run: library(Rlabkey)## create a storage Freezer with a Shelf and 2 Plates on that Shelffreezer <- labkey.storage.create(    baseUrl="http://labkey/",    folderPath="home",    type="Freezer",    props=list(name="Test Freezer", description="My example storage freezer"))shelf = labkey.storage.create(    baseUrl="http://labkey/",    folderPath="home",    type="Shelf",    props=list(name="Test Shelf", locationId=freezer$data$rowId ))plateType = labkey.storage.create(    baseUrl="http://labkey/",    folderPath="home",    type="Storage Unit Type",    props=list(name="Test 8X12 Well Plate", unitType="Plate", rows=8, cols=12 ))plate1 = labkey.storage.create(    baseUrl="http://labkey/",    folderPath="home",    type="Terminal Storage Location",    props=list(name="Plate #1", typeId=plateType$data$rowId, locationId=shelf$data$rowId ))plate2 = labkey.storage.create(    baseUrl="http://labkey/",    folderPath="home",    type="Terminal Storage Location",    props=list(name="Plate #2", typeId=plateType$data$rowId, locationId=shelf$data$rowId ))## End(Not run)

Delete a LabKey Freezer Manager storage item

Description

Delete an existing LabKey Freezer Manager storage item. Note that deletion of freezers, primary storage, or locationswithin the storage hierarchy will cascade the delete down the hierarchy to remove child locations and terminal storagelocations. Samples in the deleted storage location(s) will not be deleted but will be removed from storage.Storage items can be of the following types: Physical Location, Freezer, Primary Storage, Shelf, Rack, Canister,Storage Unit Type, or Terminal Storage Location.

Usage

labkey.storage.delete(baseUrl=NULL, folderPath, type, rowId)

Arguments

Value

A list containing a data element with the property values for the deleted storage item.

Author(s)

Cory Nathe

See Also

labkey.storage.create,labkey.storage.update

Examples

## Not run: library(Rlabkey)## delete a freezer and its child locations and terminal storage locationsfreezer <- labkey.storage.create(    baseUrl="http://labkey/",    folderPath="home",    type="Freezer",    props=list(name="Test Freezer", description="My example storage freezer"))shelf = labkey.storage.create(    baseUrl="http://labkey/",    folderPath="home",    type="Shelf",    props=list(name="Test Shelf", locationId=freezer$data$rowId ))plateType = labkey.storage.create(    baseUrl="http://labkey/",    folderPath="home",    type="Storage Unit Type",    props=list(name="Test 8X12 Well Plate", unitType="Plate", rows=8, cols=12 ))plate1 = labkey.storage.create(    baseUrl="http://labkey/",    folderPath="home",    type="Terminal Storage Location",    props=list(name="Plate #1", typeId=plateType$data$rowId, locationId=shelf$data$rowId ))plate2 = labkey.storage.create(    baseUrl="http://labkey/",    folderPath="home",    type="Terminal Storage Location",    props=list(name="Plate #2", typeId=plateType$data$rowId, locationId=shelf$data$rowId ))# NOTE: this will delete freezer, shelf, plate1 and plate2 but it will not delete#       the plateType as that is not a part of the freezer hierarchyfreezer <- labkey.storage.delete(    baseUrl="http://labkey/",    folderPath="home",    type="Freezer",    rowId=freezer$data$rowId)## End(Not run)

Update a LabKey Freezer Manager storage item

Description

Update an existing LabKey Freezer Manager storage item to change its properties or location within the storage hierarchy.Storage items can be of the following types: Physical Location, Freezer, Primary Storage, Shelf, Rack, Canister,Storage Unit Type, or Terminal Storage Location.

Usage

labkey.storage.update(baseUrl=NULL, folderPath, type, props)

Arguments

Value

A list containing a data element with the property values for the updated storage item.

Author(s)

Cory Nathe

See Also

labkey.storage.create,labkey.storage.delete

Examples

## Not run: library(Rlabkey)## create a storage unit type and then update it to change some propertiesplateType = labkey.storage.create(    baseUrl="http://labkey/",    folderPath="home",    type="Storage Unit Type",    props=list(name="Test 8X12 Well Plate", unitType="Plate", rows=8, cols=12 ))plateType = labkey.storage.update(    baseUrl="http://labkey/",    folderPath="home",    type="Storage Unit Type",    props=list(rowId=plateType$data$rowId, positionFormat="NumAlpha", positionOrder="ColumnRow" ))## End(Not run)

Assay transform script helper function to get a run property value from a data.frame

Description

A function that takes in data.frame of the run properties info for a given assay transform script execution andreturns the value for a given property name.

Usage

labkey.transform.getRunPropertyValue(runProps, propName)

Arguments

Details

This helper function will most likely be used within an assay transform script after thelabkey.transform.readRunPropertiesFile function has been called to load the full set of run properties.

Examples

## Not run: # library(Rlabkey)run.props = labkey.transform.readRunPropertiesFile("${runInfo}");run.data.file = labkey.transform.getRunPropertyValue(run.props, "runDataFile");## End(Not run)

Assay transform script helper function to read a run properties file

Description

A function that takes in the full path to the LabKey generated run properties file and returns a data.frame ofthe key value pairs for the lines within that file. This helper function would be used as part of an assay transformscript written in R and associated with an assay design.

Usage

labkey.transform.readRunPropertiesFile(runInfoPath)

Arguments

Details

The most common scenario is that the assay transform script will get the run properties file path addedinto the running script as a replacement variable.

Examples

## Not run: # library(Rlabkey)labkey.transform.readRunPropertiesFile("${runInfo}")## End(Not run)

Delete all rows from a table

Description

Delete all rows from the specified table.

Usage

labkey.truncateTable(baseUrl = NULL, folderPath, schemaName, queryName)

Arguments

Details

Deletes all rows in the table in a single transaction and will also log a single audit event for the action. Not all tables support truncation, ifa particular table doesn't support the action, an error will be returned. The current list of tables supporting truncation include : lists, datasets,issues, sample sets, data classes.

Value

Returns the count of the number of rows deleted.

Author(s)

Karl Lum

See Also

labkey.deleteRows

Examples

## Not run: ## create a data frame and infer it's fieldslibrary(Rlabkey)labkey.truncateTable(baseUrl="http://labkey/", folderPath="home",    schemaName="lists", queryName="people")## End(Not run)

Update existing rows of data in a labkey database

Description

Send data from an R session to update existing rows of data in the database.

Usage

labkey.updateRows(baseUrl, folderPath,    schemaName, queryName, toUpdate,    provenanceParams=NULL, options=NULL)

Arguments

Details

A single row or multiple rows of data can be updated. ThetoUpdate data frame should contain the rows of data to be updated and must be created with thestringsAsFactors optionset to FALSE. The names of the data in the data frame must be the column names from thelabkey database. To update a row/column to a value of NULL, use an empty string ("") in the data frame (regardless of the database column type).

The list of valid options for each query will vary, but some common examples include:

• auditBehavior (string) : Can be used to override the audit behavior for the table the query is acting on.The set of types include: NONE, SUMMARY, and DETAILED.

• auditUserComment (string) : Can be used to provide a comment from the user that will be attached tocertain detailed audit log records.

Value

A list is returned with named categories ofcommand,rowsAffected,rows,queryName,containerPath andschemaName.TheschemaName,queryName andcontainerPath properties contain the same schema, query and folder path used in the request. TherowsAffected property indicates the number of rows affected by the API action. This will typically be the samenumber as passed in the request. Therows property contains a list of row objects corresponding to the rowsupdated.

Author(s)

Valerie Obenchain

See Also

labkey.selectRows,labkey.executeSql,makeFilter,labkey.insertRows,labkey.importRows,
labkey.deleteRows,labkey.moveRows,
labkey.query.import,labkey.provenance.createProvenanceParams,labkey.provenance.startRecording,labkey.provenance.addRecordingStep,labkey.provenance.stopRecording

Examples

## Not run: ## Insert, update and delete## Note that users must have the necessary permissions in the database## to be able to modify data through the use of these functions# library(Rlabkey)newrow <- data.frame(DisplayFld="Inserted from R", TextFld="how its done", IntFld= 98 , DoubleFld = 12.345, DateTimeFld = "03/01/2010", BooleanFld= FALSE, LongTextFld = "Four score and seven years ago"#, AttachmentFld = NA    #attachment fields not supported , RequiredText = "Veni, vidi, vici", RequiredInt = 0, Category = "LOOKUP2", stringsAsFactors=FALSE)insertedRow <- labkey.insertRows("http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",    toInsert=newrow, options=list(auditBehavior="DETAILED",    auditUserComment="testing audit comment for insert"))newRowId <- insertedRow$rows[[1]]$RowIdselectedRow<-labkey.selectRows("http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",    colFilter=makeFilter(c("RowId", "EQUALS", newRowId)))selectedRowupdaterow=data.frame(RowId=newRowId, DisplayFld="Updated from R", TextFld="how to update", IntFld= 777 , stringsAsFactors=FALSE)updatedRow <- labkey.updateRows("http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",    toUpdate=updaterow, options=list(auditBehavior="DETAILED",    auditUserComment="testing audit comment for update"))selectedRow<-labkey.selectRows("http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",    colFilter=makeFilter(c("RowId", "EQUALS", newRowId)))selectedRowdeleterow <- data.frame(RowId=newRowId, stringsAsFactors=FALSE)result <- labkey.deleteRows(baseUrl="http://localhost:8080/labkey",    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",    toDelete=deleterow)str(result)## End(Not run)

Deletes the provided file/folder on a LabKey Server via WebDAV

Description

This will delete the supplied file or folder under the specified LabKey Server project using WebDAV.

Usage

labkey.webdav.delete(    baseUrl=NULL,    folderPath,    remoteFilePath,    fileSet='@files'    )

Arguments

Details

This will delete the supplied file or folder under the specified LabKey Server project using WebDAV. Note: if a folder is provided, it will delete that folder and contents.

Value

TRUE if the folder was deleted successfully

Author(s)

Ben Bimber, Ph.D.

See Also

labkey.webdav.get,labkey.webdav.put,labkey.webdav.mkDir,labkey.webdav.mkDirs,labkey.webdav.listDir,labkey.webdav.pathExists,labkey.webdav.downloadFolder

Examples

## Not run: library(Rlabkey)#delete an entire directory and contentslabkey.webdav.delete(baseUrl="http://labkey/", folderPath="home", remoteFilePath="folder1")#delete single filelabkey.webdav.delete(baseUrl="http://labkey/", folderPath="home", remoteFilePath="folder/file.txt")## End(Not run)

Recursively download a folder via WebDAV

Description

This will recursively download a folder from a LabKey Server using WebDAV.

Usage

labkey.webdav.downloadFolder(    localBaseDir,    baseUrl=NULL,     folderPath,    remoteFilePath,    overwriteFiles=TRUE,    mergeFolders=TRUE,    fileSet='@files',    showProgressBar=FALSE    )

Arguments

Details

This will recursively download a folder from a LabKey Server using WebDAV. This is essentially a wrapper that recursively callslabkey.webdav.get to download all files in the remote folder.

Value

TRUE or FALSE, depending on if this folder was successfully downloaded

Author(s)

Ben Bimber, Ph.D.

See Also

labkey.webdav.get,labkey.webdav.put,labkey.webdav.mkDir,labkey.webdav.mkDirs,labkey.webdav.pathExists,labkey.webdav.listDir,labkey.webdav.delete

Examples

## Not run: ## download folder from a LabKey Serverlibrary(Rlabkey)labkey.webdav.downloadFolder(baseUrl="http://labkey/",    folderPath="home",    remoteFilePath="folder1",    localBaseDir="destFolder",    overwrite=TRUE)## End(Not run)

Download a file via WebDAV

Description

This will download a file from a LabKey Server using WebDAV.

Usage

labkey.webdav.get(    baseUrl=NULL,    folderPath,    remoteFilePath,    localFilePath,    overwrite=TRUE,    fileSet='@files',    showProgressBar=FALSE    )

Arguments

Details

Download a single file from a LabKey Server to the local machine using WebDAV.

Value

TRUE or FALSE, depending on if this file was downloaded and exists locally. Will return FALSE if the already file exists and overwrite=F.

Author(s)

Ben Bimber, Ph.D.

See Also

labkey.webdav.put,labkey.webdav.mkDir,labkey.webdav.mkDirs,labkey.webdav.pathExists,labkey.webdav.listDir,labkey.webdav.delete,labkey.webdav.downloadFolder

Examples

## Not run: ## download a single file from a LabKey Serverlibrary(Rlabkey)labkey.webdav.get(    baseUrl="http://labkey/",    folderPath="home",    remoteFilePath="folder/myFile.txt",    localFilePath="myDownloadedFile.txt",    overwrite=TRUE)## End(Not run)

List the contents of a LabKey Server folder via WebDAV

Description

This will list the contents of a LabKey Server folder using WebDAV.

Usage

labkey.webdav.listDir(    baseUrl=NULL,    folderPath,    remoteFilePath,    fileSet='@files',    haltOnError=TRUE    )

Arguments

Details

Lists the contents of a folder on a LabKey Server using WebDAV.

Value

A list with each item under this folder. Each item (file or directory) is a list with the following attributes:

• "files": A list of the files, where each has the following attributes:

  • "id": The relative path to this item, not encoded

  • "href": The relative URL to this item, HTML encoded

  • "text": A dataset in a date based study

  • "creationdate": The date this item was created

  • "createdby": The user that created this file

  • "lastmodified": The last modification time

  • "contentlength": The content length

  • "size": The file size

  • "isdirectory": TRUE or FALSE, depending on whether this item is a directory

• "fileCount": If this item is a directory, this property will be present, listing the the total files in this location

Author(s)

Ben Bimber, Ph.D.

See Also

labkey.webdav.get,labkey.webdav.put,labkey.webdav.mkDir,labkey.webdav.mkDirs,labkey.webdav.pathExists,labkey.webdav.delete,labkey.webdav.downloadFolder

Examples

## Not run: library(Rlabkey)json <- labkey.webdav.listDir(            baseUrl="http://labkey/",            folderPath="home",            remoteFilePath="myFolder"        )## End(Not run)

Create a folder via WebDAV

Description

This will create a folder under the specified LabKey Server project using WebDAV.

Usage

labkey.webdav.mkDir(    baseUrl=NULL,    folderPath,    remoteFilePath,    fileSet='@files'    )

Arguments

Details

Creates a folder on a LabKey Server using WebDAV. If the parent directory does not exist, this will fail (similar to mkdir on linux)

Value

TRUE if the folder was created successfully

Author(s)

Ben Bimber, Ph.D.

See Also

labkey.webdav.get,labkey.webdav.put,labkey.webdav.mkDirs,labkey.webdav.pathExists,labkey.webdav.listDir,labkey.webdav.delete,labkey.webdav.downloadFolder

Examples

## Not run: library(Rlabkey)labkey.webdav.mkDir(    baseUrl="http://labkey/",    folderPath="home",    remoteFilePath="toCreate")## End(Not run)

Create a folder via WebDAV

Description

This will create folder(s) under the specified LabKey Server project using WebDAV.

Usage

labkey.webdav.mkDirs(    baseUrl=NULL,    folderPath,    remoteFilePath,    fileSet='@files'    )

Arguments

Details

Creates a folder on a LabKey Server using WebDAV. If the parent directory or directories no not exist, these will also be created (similar to mkdir -p on linux)

Value

TRUE if the folder was created successfully

Author(s)

Ben Bimber, Ph.D.

See Also

labkey.webdav.get,labkey.webdav.put,labkey.webdav.mkDir,labkey.webdav.pathExists,labkey.webdav.listDir,labkey.webdav.delete,labkey.webdav.downloadFolder

Examples

## Not run: library(Rlabkey)labkey.webdav.mkDirs(    baseUrl="http://labkey/",    folderPath="home",    remoteFilePath="folder1/folder2/toCreate")## End(Not run)

Tests if a path exists on a LabKey Server via WebDAV

Description

This will test if the supplied file/folder exists folder under the specified LabKey Server project using WebDAV.

Usage

labkey.webdav.pathExists(    baseUrl=NULL,    folderPath,    remoteFilePath,    fileSet='@files'    )

Arguments

Details

This will test if the supplied file/folder exists folder under the specified LabKey Server project using WebDAV.

Value

TRUE if the folder was created successfully

Author(s)

Ben Bimber, Ph.D.

See Also

labkey.webdav.get,labkey.webdav.put,labkey.webdav.mkDir,labkey.webdav.mkDirs,labkey.webdav.listDir,labkey.webdav.delete,labkey.webdav.downloadFolder

Examples

## Not run: library(Rlabkey)# Test folderlabkey.webdav.pathExists(    baseUrl="http://labkey/",    folderPath="home",    remoteFilePath="pathToTest")# Test filelabkey.webdav.pathExists(    baseUrl="http://labkey/",    folderPath="home",    remoteFilePath="folder/fileToTest.txt")## End(Not run)

Upload a file via WebDAV

Description

This will upload a file to a LabKey Server using WebDAV.

Usage

labkey.webdav.put(    localFile,    baseUrl=NULL,    folderPath,    remoteFilePath,    fileSet='@files',    description=NULL)

Arguments

Details

Upload a single file from the local machine to a LabKey Server using WebDAV.

Value

TRUE if the file was uploaded successfully

Author(s)

Ben Bimber, Ph.D.

See Also

labkey.webdav.get,labkey.webdav.mkDir,labkey.webdav.mkDirs,labkey.webdav.pathExists,labkey.webdav.listDir,labkey.webdav.delete,labkey.webdav.downloadFolder

Examples

## Not run: ## upload a single file to a LabKey Serverlibrary(Rlabkey)labkey.webdav.put(    localFile="myFileToUpload.txt",    baseUrl="http://labkey/",    folderPath="home",    remoteFilePath="myFileToUpload.txt")## End(Not run)

Call the whoami API

Description

Call the whoami API to get information about the current LabKey user.

Usage

labkey.whoAmI(baseUrl=NULL)

Arguments

Value

Returns information about the logged in user including: displayName, id, email,and whether or not the user is impersonated.

Author(s)

Cory Nathe

See Also

labkey.security.impersonateUser,labkey.security.stopImpersonating

Examples

## Not run: library(Rlabkey)labkey.whoAmI(baseUrl="http://labkey/")## End(Not run)

List the available folder paths

Description

Lists the available folder paths relative to the current folder path for a LabKey session

Usage

lsFolders(session)

Arguments

Details

Lists the available folder paths relative to the current folder path for a LabKey session

Value

A character array containing the available folder paths, relative to the project root. These values can be set on a session using curFolder<-

Author(s)

Peter Hussey

References

https://www.labkey.org/Documentation/wiki-page.view?name=projects

See Also

getSession,lsProjects,lsSchemas

Examples

## Not run: ##get a list if projects and folders# library(Rlabkey)lks<- getSession("https://www.labkey.org", "/home")#returns values "/home" , "/home/_menus" , ...lsFolders(lks)## End(Not run)

List the projects available at a given LabKey Server address

Description

Lists the projects available. Takes a string URL instead of a session, as it is intended for use before creating a session.

Usage

lsProjects(baseUrl)

Arguments

Details

List the projects available at a given LabKey Server address.

Value

A character array containing the available projects, relative to the root. These values can be set on a session using curFolder<-

Author(s)

Peter Hussey

References

https://www.labkey.org/home/project-begin.view

See Also

getSession,lsFolders,lsSchemas

Examples

## Not run: ## get list of projects on server, connect a session in one project,## then list the folders in that project# library(Rlabkey)lsProjects("https://www.labkey.org")lkorg <- getSession("https://www.labkey.org", "/home")lsFolders(lkorg)lkorg <- getSession("https://www.labkey.org", "/home/Study/ListDemo")lsSchemas(lkorg)## End(Not run)

List the available schemas

Description

Lists the available schemas given the current folder path for a LabKey session

Usage

lsSchemas(session)

Arguments

Details

Lists the available schemas given the current folder path for a LabKey session

Value

A character array containing the available schema names

Author(s)

Peter Hussey

See Also

getSession,lsFolders,lsProjects

Examples

## Not run: ##  get a list of schemas available in the current session context# library(Rlabkey)lks<- getSession(baseUrl="http://localhost:8080/labkey",    folderPath="/apisamples")#returns several schema names, e.g. "lists", "core", "MS1", etc.lsSchemas(lks)## End(Not run)

Builds filters to be used in labkey.selectRows and getRows

Description

This function takes inputs of column name, filter value and filter operator and returns an array of filters to be used inlabkey.selectRows andgetRows.

Usage

makeFilter(...)

Arguments

Details

These filters are applied to the data prior to import into R. The user can specify as many filters as desired. The format for specifying a filter is a vector of characters includingthe column name, operator and value.

colname

a string specifying the name of the column to be filtered

operator

a string specifying what operator should be used in the filter (see options below)

value

an integer or string specifying the value the columns should be filtered on

Operator values:
EQUAL
DATE_EQUAL
NOT_EQUAL
DATE_NOT_EQUAL
NOT_EQUAL_OR_MISSING
GREATER_THAN
DATE_GREATER_THAN
LESS_THAN
DATE_LESS_THAN
GREATER_THAN_OR_EQUAL
DATE_GREATER_THAN_OR_EQUAL
LESS_THAN_OR_EQUAL
DATE_LESS_THAN_OR_EQUAL
STARTS_WITH
DOES_NOT_START_WITH
CONTAINS
DOES_NOT_CONTAIN
CONTAINS_ONE_OF
CONTAINS_NONE_OF
IN
NOT_IN
BETWEEN
NOT_BETWEEN
MEMBER_OF
MISSING
NOT_MISSING
MV_INDICATOR
NO_MV_INDICATOR
Q
ONTOLOGY_IN_SUBTREE
ONTOLOGY_NOT_IN_SUBTREE
EXP_CHILD_OF
EXP_PARENT_OF
EXP_LINEAGE_OF

When using the MISSING, NOT_MISSING, MV_INDICATOR, or NO_MV_INDICATOR operators, an empty string should be supplied as the value.See example below.

Value

The function returns either a single string or an array of strings to be use in thecolFilter argument of thelabkey.selectRows function.

Author(s)

Valerie Obenchain

References

http://www.omegahat.net/RCurl/,
https://www.labkey.org/home/project-begin.view

See Also

labkey.selectRows

Examples

# library(Rlabkey)## Two filters, ANDed togethermakeFilter(c("TextFld","CONTAINS","h"),    c("BooleanFld","EQUAL","TRUE"))## Using "in" operator:makeFilter(c("RowId","IN","2;3;6"))## Using "missing" operator:makeFilter(c("IntFld","MISSING",""))

Returns an object representing a LabKey schema

Description

A wrapper function to labkey.saveBatch which uses a session object and provides defaults for the Batch/Run names.

Usage

saveResults(session, assayName, resultDataFrame,   batchPropertyList= list(name=paste("Batch ", as.character(date()))),  runPropertyList= list(name=paste("Assay Run ", as.character(date()))))

Arguments

Details

saveResults is a wrapper function to labkey.saveBatch with two changes: First, it uses a session object in placeof the separate baseUrl and folderPath arguments. Second, it provides defaults for generating Batch and Run names based on a currenttimestamp.

To see the save result on LabKey server, click on the "SimpleMeans" assay in the Assay List web part.

Value

an object representing the assay.

Author(s)

Peter Hussey

References

https://www.labkey.org/home/project-begin.view

See Also

getSession,getSchema,getLookups,getRows

Examples

## Not run: ## Very simple example of an analysis flow:  query some data,## calculate some stats, then save the calculations as an assay## result set in LabKey Server# library(Rlabkey)s<- getSession(baseUrl="http://localhost:8080/labkey",    folderPath="/apisamples")scobj <- getSchema(s, "lists")simpledf <- getRows(s, scobj$AllTypes)## some dummy calculations to produce and example analysis resulttesttable <- simpledf[,3:4]colnames(testtable) <- c("IntFld", "DoubleFld")row <- c(list("Measure"="colMeans"), colMeans(testtable, na.rm=TRUE))results <- data.frame(row, row.names=NULL, stringsAsFactors=FALSE)row <- c(list("Measure"="colSums"), colSums(testtable, na.rm=TRUE))results <- rbind(results, as.vector(row))bprops <- list(LabNotes="this is a simple demo")bpl<- list(name=paste("Batch ", as.character(date())),properties=bprops) rpl<- list(name=paste("Assay Run ", as.character(date())))assayInfo<- saveResults(s, "SimpleMeans", results,    batchPropertyList=bpl, runPropertyList=rpl)## End(Not run)