Package 'Rlabkey'

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 and getRows) 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 and labkey.importRows) or data can be deleted from the LabKey database (labkey.deleteRows). Interactive R users can discover available data via schema 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 (see labkey.setDefaults for more 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 Protocol client (ftp) and other programs such as CURL. On a Linux or Mac system this file should be named .netrc (dot netrc) and on Windows it should be named _netrc (underscore netrc). The file should be located in the user's home directory and the permissions 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 a text 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 [email protected]
password mypassword

Another example would be:
machine atlas.scharp.org login [email protected] 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

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

getSession lsFolders

Examples

## Not run: 

# library(Rlabkey)

lks<- getSession("https://www.labkey.org", "/home")
getFolderPath(lks)  #returns "/home"


## End(Not run)

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 in getRows, 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 base query objects that are named elemenets of a schema object, A lookup query object, however, does not have a parent schema object, it is only returned by getLookups. Also, the field names in a 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, getRows getSchema

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 queries
lucols <- getLookups(s, scobj$AllTypes$Category)

# keep going to other tables
lucols2 <- 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)

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 to labkey.selectRows. All of the arguments are the same as documented in labkey.selectRows.

See labkey.selectRows for a discussion of the valid options and defaults for colNameOpt. 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, saveResults labkey.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 schemas

scobj <- getSchema(s, "lists")
scobj   # shows available queries

scobj$AllTypes  ## this is the query object

getRows(s, scobj$AllTypes)
	

## End(Not run)

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 created by calling labkey.getQueries on the requested schema and labkey.getQueryDetails on each returned query. The information returned in the schema 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 node
sch$AllTypes$Category
sch$AllTypes$Category$caption
sch$AllTypes$Category$type

# can add fields from related queries
lucols <- 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)

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 which determine 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 are colNameOpt, which affects the names of columns in the data frames returned by getRows(), and maxRows, 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, getLookups saveResults

Examples

## Not run: 

# library(Rlabkey)

s <- getSession("https://www.labkey.org", "/home")
s   #shows schemas

## using the curlOptions for generating debug tracesof network traffic
d<- 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)

Description

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

Usage

labkey.acceptSelfSignedCerts()

Description

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

Usage

labkey.curlOptions()

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 the toDelete 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 the stringsAsFactors 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 top of 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 in the Rlabkey functions when a column name is expected. To identify a particular column name in a dataset on a 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 to certain detailed audit log records.

Value

A list is returned with named categories of command, rowsAffected, rows, queryName, containerPath and schemaName. The schemaName, queryName and containerPath properties contain the same schema, query and folder path used in the request. The rowsAffected property indicates the number of rows affected by the API action. This will typically be the same number as passed in the request. The rows property contains a list of rows corresponding to the rows deleted.

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]]$RowId

selectedRow<-labkey.selectRows("http://localhost:8080/labkey",
    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",
    colFilter=makeFilter(c("RowId", "EQUALS", newRowId)))
selectedRow

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)
selectedRow<-labkey.selectRows("http://localhost:8080/labkey",
    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",
    colFilter=makeFilter(c("RowId", "EQUALS", newRowId)))
selectedRow

deleterow <- 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)

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 being used, 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, see labkey.domain.createDesign for the helper function that can be used to construct this data structure. The options parameter should contain a list of attributes that are specific to 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 it
library(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 field
labkey.domain.create(baseUrl="http://labkey/", folderPath="home",
    domainKind="IntList", domainDesign=dd, options=list(keyName = "ptid"))

## create a domain using a domain template
labkey.domain.create(baseUrl="http://labkey/", folderPath="home",
    domainTemplate="Priority", module="simpletest", domainGroup="todolist")

## End(Not run)

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 created the 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 specific to 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.frame
participants = 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 import
labkey.domain.createAndLoad(baseUrl="http://labkey", folderPath="home",
    name="demo dataset", df=dataset, domainKind="StudyDatasetVisit")

## End(Not run)

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's conditionalFormats component while creating or updating a domain. The queryFilter parameter can be used in conjunction with labkey.domain.createConditionalFormatQueryFilter for convenient construction of a query filter string. Multiple conditional formats can be applied to one field, where each format specified constitutes a new row of the field's conditionalFormats data 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 formats
qf <- labkey.domain.FILTER_TYPES
cf1 = 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)

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 filter respectively would create a condition of 'equals 50') and the second with the remaining two optional parameters. If both conditions are created, they are conjunct with a logical AND, and a value would have to pass both conditions to clear the filter. This function can be used in conjunction with labkey.domain.FILTER_TYPES for easy access to the set of permitted 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 750
qf1 <- labkey.domain.createConditionalFormatQueryFilter(qf$EQUAL, 750)
# Filters for values greater than 500, but less than 1000
qf2 <- labkey.domain.createConditionalFormatQueryFilter(qf$GREATER_THAN, 500, qf$LESS_THAN, 1000)


## End(Not run)

Description

Create a domain design data structure which can then be used by labkey.domain.create or labkey.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 it
library(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)

Description

Create a list of indices definitions which can then be used by labkey.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 parameter indicating if this should be a UNIQUE index. A third parameter can be used to build up more then one indices definitions.

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 design
library(Rlabkey)

indices = labkey.domain.createIndices(list("intKey", "customInt"), TRUE)
indices = labkey.domain.createIndices(list("customInt"), FALSE, indices)


## End(Not run)

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 domain
library(Rlabkey)

labkey.domain.drop(baseUrl="http://labkey/", folderPath="home",
    schemaName="lists", queryName="test list")

## End(Not run)

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 map conventional terms to the expressions used by LabKey filter URL formats. The values are intended to be used in conjunction 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 comparators
comparator1 <- qf$EQUAL
comparator2 <- qf$GREATER_THAN
comparator3 <- qf$DATE_LESS_THAN_OR_EQUAL
comparator4 <- qf$STARTS_WITH
comparator5 <- qf$CONTAINS_ONE_OF


## End(Not run)

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 can be 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 by labkey.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 domain
library(Rlabkey)

labkey.domain.get(baseUrl="http://labkey/", folderPath="home",
    schemaName="lists", queryName="test list")

## End(Not run)

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 frame is 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 list can 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 fields
library(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)

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 by labkey.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 columns
domain <- 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)

Description

Use Sql commands to specify data to be imported into R. Prior to import, data can be 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 R data frame using the labkey.executeSql function. Function arguments are components of the url that identify the location of the data and the SQL actions that should be taken on the data prior to import.

See labkey.selectRows for a discussion of the valid options and defaults for colNameOpt.

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)

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 outputs

d1 <- 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)

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 outputs

m1 <- 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)

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 outputs

m1 <- 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)

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

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 or the 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 functions to 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 assay

df <- 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 outputs

m1 <- 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)

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 functions to 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 materialOutputs

m1 <- 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)

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 baseUrl has not been previously set, the function will remember the baseUrl value in package environment variables and return the formatted baseUrl. Skip baseUrl parameter to get previously set baseUrl.

Examples

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


## End(Not run)

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 as getQueryDetails.The default view is the what you will get back on calling labkey.selectRows or getRows.

Value

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

Author(s)

Peter Hussey, [email protected]

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)

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, [email protected]

See Also

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

Examples

## Not run: 

## List of folders 
# library(Rlabkey)

folders <- labkey.getFolders("https://www.labkey.org", "/home")
folders


## End(Not run)

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

When getQueryDetails returns non-NA values for the lookupQueryName, the getLookupDetails function can be called to enumerate the fields from the query referenced by the lookup. These lookup fields can be added to the colSelect list of selectRows.

Value

The available schemas are returned as a data frame, with the same columns as detailed in labkey.getQueryDetails

Author(s)

Peter Hussey, [email protected]

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 slashes
lu2<- 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 2nd
rows<- 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)

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)

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 query in the specified schema. The three columns are

Author(s)

Peter Hussey, [email protected]

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)

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, use labkey.getQueryDetails function. Function arguments are the components of the url that identify the 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 selectRows corresponds 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 are directly 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 relationship with 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 ParticipantId identifies the source of the sample, ParticipantId/CohortId/CohortName could be a reference to a CohortName field in a Cohorts data set.

These lookup fieldNames can appear in the default view and show up in the selectRows result. If a field from a lookup table is not in the default view, it can still be added to the output column list of labkey.selectRows. Use the labkey.getLookups to discover what additional fields are available via lookups, and then put their multipart fieldName values into the colSelect list. Lookup fields have the semantics of a LEFT JOIN in SQL, such that every 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, [email protected]

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)

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. Use getDefaultViewDetails 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, [email protected]

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)

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 authentication properties. This function is also exposed for general use if you would like to make your own HTTP 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)

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 generatlly associated 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, [email protected]

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)

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. The toImport data frame must contain values for each column in the dataset and must be created with the stringsAsFactors option set to FALSE. The names of the data in the data frame must be the column names from the LabKey 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, the sequence number must be specified.

Value

A list is returned with named categories of command, rowsAffected, queryName, containerPath and schemaName. The schemaName, queryName and containerPath properties contain the same schema, query and folder path used in the request. The rowsAffected property indicates the number of rows affected by the API action. This will typically be the same number 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)

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. The toInsert data frame must contain values for each column in the dataset and must be created with the stringsAsFactors option set to FALSE. The names of the data in the data frame must be the column names from the LabKey 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 to certain detailed audit log records.

Value

A list is returned with named categories of command, rowsAffected, rows, queryName, containerPath and schemaName. The schemaName, queryName and containerPath properties contain the same schema, query and folder path used in the request. The rowsAffected property indicates the number of rows affected by the API action. This will typically be the same number as passed in the request. The rows 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]]$RowId

selectedRow<-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)

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.fcs
labkey.makeRemotePath(
	localRoot=labkey.pipeline.root,
	remoteRoot=labkey.remote.pipeline.root,
	fullPath=fcsFile);

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 for all 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 to certain detailed audit log records.

Value

A list is returned with named categories of command, rowsAffected, schemaName, queryName, containerPath and updateCounts. The containerPath will be the target container path where the rows were moved. The rowsAffected property indicates the number of rows affected by the API action. This will typically be the same number as passed in the request. The updateCounts 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]]$RowId

result <- 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)

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 which will 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 on the 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)

Description

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

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)

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 the following 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 protocol names 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)

Description

Starts analysis of a set of files using a particular protocol 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)

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 from a 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 step
library(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)

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 argument in 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 outputs
library(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 params
props <- 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 <- 2
p <- labkey.provenance.createProvenanceParams(recordingId=ra$recordingId, name="step2",
    properties=props, params=params)


## End(Not run)

Description

Function to start a provenance recording session, if successful a provenance recording ID is returned which can 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 a provenance run, but stopRecording must be called to finish the recording and create the run. If successful this 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 recording
library(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)

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 run using all the steps (with inputs and outputs) associated with the recording ID. The recording ID that was obtained from a 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)

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 UI for a table/query. It takes the passed in toImport data frame and writes it to a temp file to be posted to the import action for the given LabKey query. It is very similar to the labkey.importRows command but will be much more performant.

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

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

• insertOption (string) : Whether the import action should be done as an insert, creating new rows for each provided row of the data frame, or a merge. When merging during import, any data you provide for 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 values rather than the target's primary key. This option will only be available for lookups that are configured 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)

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 only
library(Rlabkey)
labkey.rstudio.initReport(apiKey="abcdef0123456789abcdef0123456789",
    baseUrl="http://labkey/", folderPath="home",
    reportEntityId="0123456a-789b-1000-abcd-01234567abcde")


## End(Not run)

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 only
library(Rlabkey)
labkey.rstudio.initRStudio(apiKey="abcdef0123456789abcdef0123456789",
    baseUrl="http://labkey/", folderPath="home")


## End(Not run)

Description

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

Usage

labkey.rstudio.initSession(requestId, baseUrl)

Arguments

Examples

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


## End(Not run)

Description

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

Usage

labkey.rstudio.isInitialized()

Examples

## Not run: 
## RStudio console only
library(Rlabkey)
labkey.rstudio.isInitialized()


## End(Not run)

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 only
library(Rlabkey)
labkey.rstudio.saveReport(folderPath="home",
    reportEntityId="0123456a-789b-1000-abcd-01234567abcde",
    reportFilename="knitrReport.Rhtml", useWarning=TRUE)


## End(Not run)

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 as it 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 result
testtable <- 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)

Description

Create a new container, which may be a project, folder, or workbook, on the LabKey server with parameters to control the 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, or workbook, 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.moveContainer labkey.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)

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.moveContainer labkey.security.renameContainer

Examples

## Not run: 

library(Rlabkey)

labkey.security.deleteContainer(baseUrl="http://labkey/", folderPath = "/home/FolderToDelete")


## End(Not run)

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 descendants the 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 descendants the 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.moveContainer labkey.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)

Description

For site-admins or project-admins only, start impersonating a user based on the userId 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 must execute this command in a project in which they have admin permission and may impersonate only users that have access to the project.

To finish an impersonation session use labkey.security.stopImpersonating.

Value

Returns a success message based on a call to labkey.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 = "[email protected]"
)


## End(Not run)

Description

Moves an existing container, which may be a folder or workbook, to be the subfolder of another folder and/or project on 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 another folder 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 will be 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.deleteContainer labkey.security.renameContainer

Examples

## Not run: 

library(Rlabkey)

labkey.security.moveContainer(baseUrl="http://labkey/", folderPath = "/home/FolderToMove",
    destinationParent = "/OtherProject", addAlias = TRUE
)


## End(Not run)

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 also be 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.deleteContainer labkey.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)

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 this function to stop the impersonation and return back to the original user logged in.

To start an impersonation session use labkey.security.impersonateUser.

Value

Returns a success message based on a call to labkey.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)

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 the labkey.selectRows function. Function arguments are the components of the url that identify the 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 of the return data frame. View columns can be a subset or superset of the columns of the underlying query (a subset if columns from the query 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 names that are used as arguments to labkey function calls. It is the default for the new getRows session-based function. colNameOpt='rname' transforms the field name value into valid R names by substituting an underscore for both spaces and forward slash (/) characters and lower casing the entire name. This option is the way a data frame is passed to a script running in a LabKey server in the R View feature of the data grid. If you are writing scripts for running in an R 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 by labkey.executeSql and labkey.selectRows are field captions by default. The getRows function has the same colNameOpt 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 list
viewrows <- labkey.selectRows(baseUrl="http://localhost:8080/labkey",
    folderPath="/apisamples", schemaName="Lists", queryName="AllTypes",
    viewName="rowbyrow")

## select a subset of columns
colSelect=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) field
lookupcols <- labkey.selectRows(baseUrl="http://localhost:8080/labkey",
    folderPath="/apisamples", schemaName="lists", queryName="AllTypes",
    colSelect="TextFld,IntFld,IntFld/LookupValue")


## End(Not run)

Description

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

Arguments