[2] | 1 | package nl.tno.metagenomics.integration |
---|
| 2 | |
---|
| 3 | import grails.converters.* |
---|
[18] | 4 | import nl.tno.metagenomics.* |
---|
[12] | 5 | |
---|
| 6 | import org.apache.catalina.connector.Response; |
---|
[2] | 7 | import org.codehaus.groovy.grails.commons.ConfigurationHolder |
---|
| 8 | |
---|
| 9 | /** Expose the list of features within a certain assay |
---|
| 10 | * |
---|
| 11 | * @author Robert Horlings (robert@isdat.nl) |
---|
| 12 | * @since 20101229 |
---|
| 13 | * @see SAM.RestController |
---|
| 14 | * |
---|
| 15 | * $Rev$ |
---|
| 16 | * |
---|
| 17 | * This class provides a REST-full service for getting and setting the data |
---|
| 18 | * in the Metagenomics Module. The service consists of several |
---|
| 19 | * resources listed below. So far, all resources are GET resoruces, i.e. we |
---|
| 20 | * do not use PUT, POST or DELETE. Because we are using Grails' web libaries, |
---|
| 21 | * each resource corresponds to exactly one action of this controller. |
---|
| 22 | * |
---|
| 23 | * |
---|
| 24 | * The REST resources implemented in this controller are: |
---|
| 25 | * |
---|
| 26 | * metagenomics-host:port/metagenomics/rest/getMeasurements(assayToken) |
---|
| 27 | * metagenomics-host:port/metagenomics/rest/getMeasurementMetadata(assayToken, measurementTokens) |
---|
| 28 | * metagenomics-host:port/metagenomics/rest/getMeasurementData(assayToken, measurementTokens, sampleTokens) |
---|
| 29 | * metagenomics-host:port/metagenomics/rest/getAssayURL(assayToken) |
---|
| 30 | * |
---|
| 31 | * Where 'metagenomics-host' is the url of the metagenomics server's host with port number 'port'. |
---|
| 32 | * |
---|
| 33 | */ |
---|
| 34 | class RestController { |
---|
| 35 | def synchronizationService |
---|
[12] | 36 | |
---|
[2] | 37 | /****************************************************************/ |
---|
[12] | 38 | /* REST resource for handling study change in GSCF */ |
---|
[2] | 39 | /****************************************************************/ |
---|
[12] | 40 | |
---|
[2] | 41 | /** |
---|
| 42 | * Is called by GSCF when a study is added, changed or deleted. |
---|
| 43 | * Sets the 'dirty' flag of a study to true, so that it will be updated |
---|
| 44 | * next time the study is asked for. |
---|
| 45 | * |
---|
| 46 | * @param studyToken |
---|
| 47 | */ |
---|
| 48 | def notifyStudyChange = { |
---|
| 49 | def studyToken = params.studyToken |
---|
[9] | 50 | |
---|
[2] | 51 | if( !studyToken ) { |
---|
| 52 | response.sendError(400, "No studyToken given" ) |
---|
| 53 | return |
---|
| 54 | } |
---|
[9] | 55 | |
---|
[2] | 56 | // Search for the changed study |
---|
| 57 | def study = Study.findByStudyToken( studyToken ); |
---|
[9] | 58 | |
---|
[2] | 59 | // If the study is not found, it is added in GSCF. Add a dummy (dirty) study, in order to |
---|
| 60 | // update it immediately when asked for |
---|
| 61 | if( !study ) { |
---|
| 62 | log.info( "METAGENOMICS: GSCF notification for new study " + studyToken ); |
---|
| 63 | study = new Study( |
---|
[9] | 64 | name: "", |
---|
| 65 | studyToken: studyToken, |
---|
| 66 | isDirty: true |
---|
| 67 | ) |
---|
[2] | 68 | } else { |
---|
| 69 | log.info( "METAGENOMICS: GSCF notification for existing study " + studyToken ); |
---|
| 70 | study.isDirty = true; |
---|
| 71 | } |
---|
| 72 | study.save(flush:true); |
---|
[9] | 73 | |
---|
[2] | 74 | def jsonData = [ 'studyToken': studyToken, message: "Notify succesful" ]; |
---|
[9] | 75 | |
---|
[2] | 76 | render jsonData as JSON |
---|
| 77 | } |
---|
[9] | 78 | |
---|
[2] | 79 | /** |
---|
| 80 | * Return URL to view an assay. |
---|
| 81 | * |
---|
| 82 | * @param assayToken |
---|
| 83 | * @return URL to view an assay as single hash entry with key 'url'. |
---|
| 84 | * |
---|
| 85 | */ |
---|
| 86 | def getAssayURL = { |
---|
| 87 | def assayToken = params.assayToken |
---|
| 88 | |
---|
| 89 | if( !assayToken ) { |
---|
| 90 | render [] as JSON |
---|
| 91 | return |
---|
| 92 | } |
---|
| 93 | |
---|
| 94 | def assay = Assay.findByAssayToken( assayToken ) |
---|
| 95 | |
---|
| 96 | // If the assay is not found, try synchronizing |
---|
| 97 | synchronizationService.sessionToken = session.sessionToken |
---|
[9] | 98 | |
---|
[2] | 99 | if( !assay ) { |
---|
| 100 | synchronizationService.synchronizeStudies() |
---|
| 101 | assay = Assay.findByAssayToken( assayToken ); |
---|
[9] | 102 | |
---|
[2] | 103 | if( !assay ) { |
---|
| 104 | response.sendError(404, "Not Found" ) |
---|
| 105 | return; |
---|
| 106 | } |
---|
| 107 | } else { |
---|
| 108 | try { |
---|
| 109 | synchronizationService.synchronizeAssay(assay); |
---|
| 110 | } catch( Exception e ) { |
---|
| 111 | response.sendError( 500, e.getMessage()) |
---|
| 112 | return |
---|
| 113 | } |
---|
[9] | 114 | |
---|
[3] | 115 | def url = [ 'url' : ConfigurationHolder.config.grails.serverURL + '/assay/show/' + assay.id.toString() ] |
---|
[2] | 116 | |
---|
| 117 | render url as JSON |
---|
| 118 | } |
---|
[4] | 119 | } |
---|
[9] | 120 | |
---|
[2] | 121 | /***************************************************/ |
---|
| 122 | /* REST resources related to the querying in GSCF */ |
---|
| 123 | /***************************************************/ |
---|
| 124 | |
---|
| 125 | /** |
---|
[9] | 126 | * Retrieves a list of fields that could be queried when searching for a specific entity. |
---|
| 127 | * |
---|
| 128 | * The module is allowed to return different fields when the user searches for different entities |
---|
| 129 | * |
---|
| 130 | * Example call: [moduleurl]/rest/getQueryableFields?entity=Study&entity=Sample |
---|
| 131 | * Example response: { "Study": [ "# sequences" ], "Sample": [ "# sequences", "# bacteria" ] } |
---|
| 132 | * |
---|
| 133 | * @param params.entity Entity that is searched for. Might be more than one. If no entity is given, |
---|
| 134 | * a list of searchable fields for all entities is given |
---|
| 135 | * @return JSON List with the names of the fields |
---|
| 136 | */ |
---|
| 137 | def getQueryableFields = { |
---|
| 138 | // We don't really care about the entity. The only thing is that this module |
---|
| 139 | // is only aware of studies, assays and samples, but doesn't know anything about |
---|
| 140 | // subjects or events. If the user searches for those entities (maybe in the future) |
---|
| 141 | // this module doesn't have anything to search for. |
---|
| 142 | |
---|
| 143 | def entities = params.entity ?: [] |
---|
| 144 | |
---|
| 145 | if( entities instanceof String ) |
---|
| 146 | entities = [entities] |
---|
| 147 | else |
---|
| 148 | entities = entities.toList() |
---|
| 149 | |
---|
| 150 | if( !entities ) |
---|
| 151 | entities = [ "Study", "Assay", "Sample" ] |
---|
| 152 | |
---|
| 153 | |
---|
| 154 | def fields = [:]; |
---|
| 155 | entities.unique().each { entity -> |
---|
| 156 | switch( entity ) { |
---|
| 157 | case "Study": |
---|
| 158 | case "Assay": |
---|
| 159 | case "Sample": |
---|
[12] | 160 | fields[ entity ] = [ "# sequences", "Tag name", "Run name" ] |
---|
[9] | 161 | break; |
---|
| 162 | default: |
---|
| 163 | // Do nothing |
---|
| 164 | break; |
---|
| 165 | } |
---|
| 166 | } |
---|
| 167 | |
---|
| 168 | render fields as JSON |
---|
| 169 | } |
---|
[12] | 170 | |
---|
[9] | 171 | /** |
---|
| 172 | * Returns data for the given field and entities. |
---|
| 173 | * |
---|
| 174 | * Example call: [moduleurl]/rest/getQueryableFieldData?entity=Study&tokens=abc1&tokens=abc2&fields=# sequences&fields=# bacteria |
---|
| 175 | * Example response: { "abc1": { "# sequences": 141, "# bacteria": 0 }, "abc2": { "#sequences": 412 } } |
---|
| 176 | * |
---|
| 177 | * @param params.entity Entity that is searched for |
---|
| 178 | * @param params.tokens One or more tokens of the entities that the data should be returned for |
---|
| 179 | * @param params.fields One or more field names of the data to be returned. |
---|
| 180 | * @return JSON Map with keys being the entity tokens and the values being maps with entries [field] = [value]. Not all |
---|
| 181 | * fields and tokens that are asked for have to be returned by the module (e.g. when a specific entity can |
---|
| 182 | * not be found, or a value is not present for an entity) |
---|
| 183 | */ |
---|
| 184 | def getQueryableFieldData = { |
---|
[18] | 185 | println "Get queryable Field data: " + params |
---|
| 186 | |
---|
[9] | 187 | def entity = params.entity; |
---|
| 188 | def tokens = params.tokens ?: [] |
---|
| 189 | def fields = params.fields ?: [] |
---|
| 190 | |
---|
| 191 | if( tokens instanceof String ) |
---|
| 192 | tokens = [tokens] |
---|
| 193 | else |
---|
| 194 | tokens = tokens.toList(); |
---|
| 195 | |
---|
| 196 | if( fields instanceof String ) |
---|
| 197 | fields = [fields] |
---|
| 198 | else |
---|
| 199 | fields = fields.toList(); |
---|
| 200 | |
---|
| 201 | // Only search for unique tokens and fields |
---|
| 202 | tokens = tokens.unique() |
---|
| 203 | fields = fields.unique() |
---|
| 204 | |
---|
| 205 | // Without tokens or fields we can only return an empty list |
---|
| 206 | def map = [:] |
---|
| 207 | if( tokens.size() == 0 || fields.size() == 0 ) { |
---|
| 208 | log.trace "Return empty string for getQueryableFieldData: #tokens: " + tokens.size() + " #fields: " + fields.size() |
---|
| 209 | render map as JSON |
---|
| 210 | return; |
---|
| 211 | } |
---|
| 212 | |
---|
[12] | 213 | for( token in tokens ) { |
---|
[9] | 214 | def object = getQueryableObject( entity, token ); |
---|
[12] | 215 | |
---|
[9] | 216 | if( object ) { |
---|
[12] | 217 | // Check whether the user has sufficient privileges: |
---|
| 218 | def study; |
---|
| 219 | switch( entity ) { |
---|
| 220 | case "Study": |
---|
| 221 | study = object; |
---|
| 222 | break; |
---|
| 223 | case "Assay": |
---|
| 224 | case "Sample": |
---|
| 225 | study = object.study |
---|
| 226 | break; |
---|
| 227 | default: |
---|
| 228 | log.error "Incorrect entity used: " + entity; |
---|
| 229 | continue; |
---|
| 230 | } |
---|
| 231 | |
---|
| 232 | if( !study.canRead( session.user ) ) { |
---|
| 233 | log.error "Data was requested for " + entity.toLowerCase() + " " + object.name + " but the user " + session.user.username + " doesn't have the right privileges." |
---|
| 234 | continue; |
---|
| 235 | } |
---|
| 236 | |
---|
[9] | 237 | map[ token ] = [:] |
---|
| 238 | fields.each { field -> |
---|
| 239 | def v = getQueryableFieldValue( entity, object, field ); |
---|
| 240 | if( v != null ) |
---|
| 241 | map[ token ][ field ] = v |
---|
| 242 | } |
---|
| 243 | } else { |
---|
| 244 | log.trace "No " + entity + " with token " + token + " found." |
---|
| 245 | } |
---|
| 246 | } |
---|
| 247 | |
---|
| 248 | render map as JSON |
---|
| 249 | } |
---|
| 250 | |
---|
| 251 | /** |
---|
| 252 | * Searches for a specific entity |
---|
| 253 | * |
---|
| 254 | * @param entity Entity to search in |
---|
| 255 | * @param token Token of the entity to search in |
---|
| 256 | * @return |
---|
| 257 | */ |
---|
| 258 | protected def getQueryableObject( def entity, def token ) { |
---|
| 259 | switch( entity ) { |
---|
| 260 | case "Study": |
---|
| 261 | return Study.findByStudyToken( token ); |
---|
| 262 | case "Assay": |
---|
| 263 | return Assay.findByAssayToken( token ); |
---|
| 264 | case "Sample": |
---|
| 265 | return Sample.findBySampleToken( token ); |
---|
| 266 | default: |
---|
| 267 | // Other entities can't be handled |
---|
| 268 | return null; |
---|
| 269 | } |
---|
| 270 | } |
---|
| 271 | |
---|
| 272 | /** |
---|
| 273 | * Searches for the value of a specific field in a specific entity |
---|
| 274 | * |
---|
| 275 | * @param entity Entity of the given object |
---|
| 276 | * @param object Object to search in |
---|
| 277 | * @param field Field value to retrieve |
---|
| 278 | * @return |
---|
| 279 | */ |
---|
| 280 | protected def getQueryableFieldValue( def entity, def object, def field ) { |
---|
| 281 | if( !entity || !object || !field ) |
---|
| 282 | return null; |
---|
| 283 | |
---|
[12] | 284 | // First determine all assaysamples involved, in order to return data later. |
---|
| 285 | // All data that has to be returned is found in assaysamples |
---|
| 286 | def assaySamples |
---|
| 287 | |
---|
[9] | 288 | switch( entity ) { |
---|
| 289 | case "Study": |
---|
[12] | 290 | assaySamples = object.assays*.assaySamples; |
---|
| 291 | if( assaySamples ) { |
---|
| 292 | assaySamples = assaySamples.flatten() |
---|
| 293 | } |
---|
| 294 | break; |
---|
[9] | 295 | case "Assay": |
---|
| 296 | case "Sample": |
---|
[12] | 297 | assaySamples = object.assaySamples; |
---|
| 298 | break; |
---|
[9] | 299 | default: |
---|
| 300 | // Other entities can't be handled |
---|
| 301 | return null; |
---|
| 302 | } |
---|
[12] | 303 | |
---|
| 304 | // If no assaySamples are involved, return null as empty value |
---|
| 305 | if( !assaySamples ) { |
---|
| 306 | return null; |
---|
| 307 | } |
---|
| 308 | |
---|
| 309 | // Now determine the exact field to return |
---|
| 310 | switch( field ) { |
---|
| 311 | // Returns the total number of sequences in this sample |
---|
| 312 | case "# sequences": |
---|
| 313 | return assaySamples.collect { it.numSequences() }.sum(); |
---|
| 314 | // Returns the unique tag names |
---|
| 315 | case "Tag name": |
---|
| 316 | return assaySamples.collect { it.tagName }.findAll { it != null }.unique(); |
---|
| 317 | case "Run name": |
---|
| 318 | return assaySamples.collect { it.run?.name }.findAll { it != null }.unique(); |
---|
| 319 | // Other fields are not handled |
---|
| 320 | default: |
---|
| 321 | return null; |
---|
| 322 | } |
---|
| 323 | |
---|
[9] | 324 | } |
---|
[12] | 325 | |
---|
| 326 | private def checkAssayToken( def assayToken ) { |
---|
| 327 | if( !assayToken || assayToken == null ) { |
---|
| 328 | return false |
---|
| 329 | } |
---|
[2] | 330 | def list = [] |
---|
[12] | 331 | def assay = Assay.findByAssayToken( assayToken ) |
---|
[2] | 332 | |
---|
[12] | 333 | if( !assay || assay == null ) { |
---|
| 334 | return false; |
---|
[2] | 335 | } |
---|
| 336 | |
---|
[12] | 337 | return assay; |
---|
[2] | 338 | } |
---|
| 339 | |
---|
[12] | 340 | /****************************************************************/ |
---|
| 341 | /* REST resources for exporting data from GSCF */ |
---|
| 342 | /****************************************************************/ |
---|
| 343 | |
---|
[2] | 344 | /** |
---|
[12] | 345 | * Retrieves a list of actions that can be performed on data with a specific entity. |
---|
[2] | 346 | * |
---|
[12] | 347 | * The module is allowed to return different fields when the user searches for different entities |
---|
| 348 | * |
---|
| 349 | * Example call: [moduleurl]/rest/getPossibleActions?entity=Assay&entity=Sample |
---|
| 350 | * Example response: { "Assay": [ { name: "excel", description: "Export as excel" } ], |
---|
| 351 | * "Sample": [ { name: "excel", description: "Export as excel" }, { name: "fasta", description: : "Export as fasta" } ] } |
---|
| 352 | * |
---|
| 353 | * @param params.entity Entity that is searched for. Might be more than one. If no entity is given, |
---|
| 354 | * a list of searchable fields for all entities is given |
---|
| 355 | * @return JSON Hashmap with keys being the entities and the values are lists with the action this module can |
---|
| 356 | * perform on this entity. The actions as hashmaps themselves, with keys 'name' and 'description' |
---|
[2] | 357 | */ |
---|
[12] | 358 | def getPossibleActions = { |
---|
| 359 | def entities = params.entity ?: [] |
---|
| 360 | |
---|
| 361 | if( entities instanceof String ) |
---|
| 362 | entities = [entities] |
---|
| 363 | else |
---|
| 364 | entities = entities.toList() |
---|
| 365 | |
---|
| 366 | if( !entities ) |
---|
| 367 | entities = [ "Study", "Assay", "Sample" ] |
---|
| 368 | |
---|
| 369 | def actions = [:]; |
---|
| 370 | entities.unique().each { entity -> |
---|
| 371 | switch( entity ) { |
---|
| 372 | case "Study": |
---|
[14] | 373 | actions[ entity ] = [ |
---|
| 374 | [ name: "excel", description: "Export metadata", url: createLink( controller: "study", action: "exportMetaData", absolute: true ) ], |
---|
| 375 | [ name: "fasta", description: "Export as fasta", url: createLink( controller: "study", action: "exportAsFasta", absolute: true ) ] |
---|
| 376 | ] |
---|
[12] | 377 | break; |
---|
| 378 | case "Assay": |
---|
[14] | 379 | actions[ entity ] = [ |
---|
| 380 | [ name: "fasta", description: "Export as fasta", url: createLink( controller: "assay", action: "exportAsFasta", absolute: true ) ], |
---|
| 381 | [ name: "excel", description: "Export metadata", url: createLink( controller: "assay", action: "exportMetaData", absolute: true ) ] |
---|
| 382 | ] |
---|
[12] | 383 | break; |
---|
| 384 | case "Sample": |
---|
[14] | 385 | actions[ entity ] = [ |
---|
| 386 | [ name: "fasta", description: "Export as fasta", url: createLink( controller: "sample", action: "exportAsFasta", absolute: true ) ], |
---|
| 387 | [ name: "excel", description: "Export metadata", url: createLink( controller: "sample", action: "exportMetaData", absolute: true ) ] |
---|
| 388 | ] |
---|
[12] | 389 | break; |
---|
| 390 | default: |
---|
| 391 | // Do nothing |
---|
| 392 | break; |
---|
[2] | 393 | } |
---|
| 394 | } |
---|
[12] | 395 | |
---|
| 396 | render actions as JSON |
---|
[2] | 397 | } |
---|
| 398 | |
---|
[12] | 399 | /****************************************************************/ |
---|
| 400 | /* REST resources for providing basic data to the GSCF */ |
---|
| 401 | /****************************************************************/ |
---|
| 402 | private getMeasurementTypes() { |
---|
| 403 | return [ "# sequences" ] |
---|
| 404 | } |
---|
[2] | 405 | |
---|
[12] | 406 | /** |
---|
| 407 | * Return a list of simple assay measurements matching the querying text. |
---|
| 408 | * |
---|
| 409 | * @param assayToken |
---|
| 410 | * @return list of measurements for token. Each member of the list is a hash. |
---|
| 411 | * the hash contains the three keys values pairs: value, sampleToken, and |
---|
| 412 | * measurementMetadata. |
---|
| 413 | * |
---|
| 414 | * Example REST call: |
---|
| 415 | * http://localhost:8184/metagenomics/rest/getMeasurements/query?assayToken=16S-5162 |
---|
| 416 | * |
---|
| 417 | * Resulting JSON object: |
---|
| 418 | * |
---|
| 419 | * [ "# sequences", "average quality" ] |
---|
| 420 | * |
---|
| 421 | */ |
---|
| 422 | def getMeasurements = { |
---|
| 423 | def assayToken = params.assayToken; |
---|
[2] | 424 | |
---|
[12] | 425 | if( !checkAssayToken( assayToken ) ) { |
---|
| 426 | response.sendError(404) |
---|
| 427 | return false |
---|
| 428 | } |
---|
| 429 | |
---|
| 430 | render getMeasurementTypes() as JSON |
---|
| 431 | } |
---|
| 432 | |
---|
[2] | 433 | /** |
---|
[12] | 434 | * Return measurement metadata for measurement |
---|
| 435 | * |
---|
| 436 | * @param assayToken |
---|
| 437 | * @param measurementTokens. List of measurements for which the metadata is returned. |
---|
| 438 | * If this is not given, then return metadata for all |
---|
| 439 | * measurements belonging to the specified assay. |
---|
| 440 | * @return list of measurements |
---|
| 441 | * |
---|
| 442 | * Example REST call: |
---|
| 443 | * http://localhost:8184/metagenomics/rest/getMeasurementMetadata/query?assayToken=16S-5162 |
---|
| 444 | * &measurementToken=# sequences |
---|
| 445 | * &measurementToken=average quality |
---|
| 446 | * |
---|
| 447 | * Example resulting JSON object: |
---|
| 448 | * |
---|
| 449 | * [ {"name":"# sequences","type":"raw"}, |
---|
| 450 | * {"name":"average quality", "unit":"Phred"} ] |
---|
[2] | 451 | */ |
---|
[18] | 452 | def getMeasurementMetaData = { |
---|
[12] | 453 | def assayToken = params.assayToken |
---|
| 454 | def measurementTokens = params.measurementToken |
---|
| 455 | |
---|
| 456 | if( !checkAssayToken( assayToken ) ) { |
---|
| 457 | response.sendError(404) |
---|
| 458 | return false |
---|
[2] | 459 | } |
---|
[12] | 460 | |
---|
| 461 | // For now, we don't have any metadata about the measurements |
---|
| 462 | def measurements = getMeasurementTypes(); |
---|
[18] | 463 | def measurementMetadata = [ ] |
---|
[12] | 464 | |
---|
| 465 | measurementTokens.each { token -> |
---|
| 466 | if( measurements.contains( token ) ) |
---|
| 467 | measurementMetadata << [ "name" : token ]; |
---|
[2] | 468 | } |
---|
[12] | 469 | |
---|
| 470 | render measurementMetadata as JSON |
---|
[2] | 471 | } |
---|
| 472 | |
---|
| 473 | /** |
---|
[12] | 474 | * Return list of measurement data. |
---|
| 475 | * |
---|
| 476 | * @param assayTokes |
---|
| 477 | * @param measurementToken. Restrict the returned data to the measurementTokens specified here. |
---|
| 478 | * If this argument is not given, all samples for the measurementTokens are returned. |
---|
| 479 | * Multiple occurences of this argument are possible. |
---|
| 480 | * @param sampleToken. Restrict the returned data to the samples specified here. |
---|
| 481 | * If this argument is not given, all samples for the measurementTokens are returned. |
---|
| 482 | * Multiple occurences of this argument are possible. |
---|
| 483 | * @param boolean verbose. If this argument is not present or it's value is true, then return |
---|
| 484 | * the date in a redundant format that is easier to process. |
---|
| 485 | * By default, return a more compact JSON object as follows. |
---|
| 486 | * |
---|
| 487 | * The list contains three elements: |
---|
| 488 | * |
---|
| 489 | * (1) a list of sampleTokens, |
---|
| 490 | * (2) a list of measurementTokens, |
---|
| 491 | * (3) a list of values. |
---|
| 492 | * |
---|
| 493 | * The list of values is a matrix represented as a list. Each row of the matrix |
---|
| 494 | * contains the values of a measurementToken (in the order given in the measurement |
---|
| 495 | * token list, (2)). Each column of the matrix contains the values for the sampleTokens |
---|
| 496 | * (in the order given in the list of sampleTokens, (1)). |
---|
| 497 | * (cf. example below.) |
---|
| 498 | * |
---|
| 499 | * |
---|
| 500 | * @return table (as hash) with values for given samples and measurements |
---|
| 501 | * |
---|
| 502 | * |
---|
| 503 | * List of examples. |
---|
| 504 | * |
---|
| 505 | * |
---|
| 506 | * Example REST call: |
---|
| 507 | * http://localhost:8184/metagenomics/rest/getMeasurementData/doit?assayToken=PPSH-Glu-A |
---|
| 508 | * &measurementToken=total carbon dioxide (tCO) |
---|
| 509 | * &sampleToken=5_A |
---|
| 510 | * &sampleToken=1_A |
---|
| 511 | * &verbose=true |
---|
| 512 | * |
---|
| 513 | * Resulting JSON object: |
---|
| 514 | * [ {"sampleToken":"1_A","measurementToken":"total carbon dioxide (tCO)","value":28}, |
---|
| 515 | * {"sampleToken":"5_A","measurementToken":"total carbon dioxide (tCO)","value":29} ] |
---|
| 516 | * |
---|
| 517 | * |
---|
| 518 | * |
---|
| 519 | * Example REST call without sampleToken, without measurementToken, |
---|
| 520 | * and with verbose representation: |
---|
| 521 | * http://localhost:8184/metagenomics/rest/getMeasurementData/dossit?assayToken=PPSH-Glu-A |
---|
| 522 | * &verbose=true |
---|
| 523 | * |
---|
| 524 | * Resulting JSON object: |
---|
| 525 | * [ {"sampleToken":"1_A","measurementToken":"sodium (Na+)","value":139}, |
---|
| 526 | * {"sampleToken":"1_A","measurementToken":"potassium (K+)","value":4.5}, |
---|
| 527 | * {"sampleToken":"1_A","measurementToken":"total carbon dioxide (tCO)","value":26}, |
---|
| 528 | * {"sampleToken":"2_A","measurementToken":"sodium (Na+)","value":136}, |
---|
| 529 | * {"sampleToken":"2_A","measurementToken":"potassium (K+)","value":4.3}, |
---|
| 530 | * {"sampleToken":"2_A","measurementToken":"total carbon dioxide (tCO)","value":28}, |
---|
| 531 | * {"sampleToken":"3_A","measurementToken":"sodium (Na+)","value":139}, |
---|
| 532 | * {"sampleToken":"3_A","measurementToken":"potassium (K+)","value":4.6}, |
---|
| 533 | * {"sampleToken":"3_A","measurementToken":"total carbon dioxide (tCO)","value":27}, |
---|
| 534 | * {"sampleToken":"4_A","measurementToken":"sodium (Na+)","value":137}, |
---|
| 535 | * {"sampleToken":"4_A","measurementToken":"potassium (K+)","value":4.6}, |
---|
| 536 | * {"sampleToken":"4_A","measurementToken":"total carbon dioxide (tCO)","value":26}, |
---|
| 537 | * {"sampleToken":"5_A","measurementToken":"sodium (Na+)","value":133}, |
---|
| 538 | * {"sampleToken":"5_A","measurementToken":"potassium (K+)","value":4.5}, |
---|
| 539 | * {"sampleToken":"5_A","measurementToken":"total carbon dioxide (tCO)","value":29} ] |
---|
| 540 | * |
---|
| 541 | * |
---|
| 542 | * |
---|
| 543 | * Example REST call with default (non-verbose) view and without sampleToken: |
---|
| 544 | * |
---|
| 545 | * Resulting JSON object: |
---|
| 546 | * http://localhost:8184/metagenomics/rest/getMeasurementData/query? |
---|
| 547 | * assayToken=PPSH-Glu-A& |
---|
| 548 | * measurementToken=total carbon dioxide (tCO) |
---|
| 549 | * |
---|
| 550 | * Resulting JSON object: |
---|
| 551 | * [ ["1_A","2_A","3_A","4_A","5_A"], |
---|
| 552 | * ["sodium (Na+)","potassium (K+)","total carbon dioxide (tCO)"], |
---|
| 553 | * [139,136,139,137,133,4.5,4.3,4.6,4.6,4.5,26,28,27,26,29] ] |
---|
| 554 | * |
---|
| 555 | * Explanation: |
---|
| 556 | * The JSON object returned by default (i.e., unless verbose is set) is an array of three arrays. |
---|
| 557 | * The first nested array gives the sampleTokens for which data was retrieved. |
---|
| 558 | * The second nested array gives the measurementToken for which data was retrieved. |
---|
| 559 | * The thrid nested array gives the data for sampleTokens and measurementTokens. |
---|
| 560 | * |
---|
| 561 | * |
---|
| 562 | * In the example, the matrix represents the values of the above Example and |
---|
| 563 | * looks like this: |
---|
| 564 | * |
---|
| 565 | * 1_A 2_A 3_A 4_A 5_A |
---|
| 566 | * |
---|
| 567 | * Na+ 139 136 139 137 133 |
---|
| 568 | * |
---|
| 569 | * K+ 4.5 4.3 4.6 4.6 4.5 |
---|
| 570 | * |
---|
| 571 | * tCO 26 28 27 26 29 |
---|
| 572 | * |
---|
[2] | 573 | */ |
---|
[12] | 574 | def getMeasurementData = { |
---|
| 575 | def assayToken = params.assayToken |
---|
| 576 | def measurementTokens = params.measurementToken |
---|
| 577 | def sampleTokens = params.sampleToken |
---|
| 578 | def verbose = false |
---|
| 579 | |
---|
| 580 | if(params.verbose && (params.verbose=='true'||params.verbose==true) ) { |
---|
| 581 | verbose=true |
---|
[2] | 582 | } |
---|
[12] | 583 | |
---|
| 584 | def assay = checkAssayToken( assayToken ); |
---|
| 585 | if( !assay ) { |
---|
| 586 | response.sendError(404) |
---|
| 587 | return false |
---|
[2] | 588 | } |
---|
[12] | 589 | |
---|
| 590 | if( !measurementTokens ) { |
---|
| 591 | measurementTokens = [] |
---|
[2] | 592 | } |
---|
[12] | 593 | else if( measurementTokens.class == java.lang.String ) { |
---|
| 594 | measurementTokens = [ measurementTokens ] |
---|
| 595 | } |
---|
[2] | 596 | |
---|
[12] | 597 | if( !sampleTokens ) { |
---|
| 598 | sampleTokens = [] |
---|
[2] | 599 | } |
---|
[12] | 600 | else if( sampleTokens.class == java.lang.String ) { |
---|
| 601 | sampleTokens = [ sampleTokens ] |
---|
| 602 | } |
---|
[2] | 603 | |
---|
[18] | 604 | def data = AssaySample.findAllByAssay( assay ); |
---|
[12] | 605 | def measurements = getMeasurementTypes() |
---|
| 606 | |
---|
| 607 | def results = [] |
---|
[18] | 608 | data.each { assaySample -> |
---|
[12] | 609 | measurements.each { type -> |
---|
[18] | 610 | def sample = assaySample.sample.sampleToken |
---|
[12] | 611 | def isMatch = false |
---|
| 612 | |
---|
| 613 | // Check if this measurement should be returned |
---|
| 614 | if( ( measurementTokens.isEmpty() || measurementTokens.contains( type ) ) && |
---|
| 615 | ( sampleTokens.isEmpty() || sampleTokens.contains( sample ) ) ) { |
---|
[18] | 616 | results.push( [ 'sampleToken': sample, 'measurementToken': type, 'value': assaySample[ type ] ] ) |
---|
[12] | 617 | } |
---|
| 618 | } |
---|
[2] | 619 | } |
---|
| 620 | |
---|
[12] | 621 | if(!verbose) { |
---|
| 622 | results = compactTable( results ) |
---|
| 623 | } |
---|
| 624 | |
---|
| 625 | render results as JSON |
---|
[2] | 626 | } |
---|
| 627 | |
---|
[12] | 628 | |
---|
[2] | 629 | /* helper function for getSamples |
---|
| 630 | * |
---|
| 631 | * Return compact JSON object for data. The format of the returned array is as follows. |
---|
| 632 | * |
---|
| 633 | * The list contains three elements: |
---|
| 634 | * |
---|
| 635 | * (1) a list of sampleTokens, |
---|
| 636 | * (2) a list of measurementTokens, |
---|
| 637 | * (3) a list of values. |
---|
| 638 | * |
---|
| 639 | * The list of values is a matrix represented as a list. Each row of the matrix |
---|
| 640 | * contains the values of a measurementToken (in the order given in the measurement |
---|
| 641 | * token list, (2)). Each column of the matrix contains the values for the sampleTokens |
---|
| 642 | * (in the order given in the list of sampleTokens, (1)). |
---|
| 643 | */ |
---|
| 644 | def compactTable( results ) { |
---|
| 645 | def i = 0 |
---|
| 646 | def sampleTokenIndex = [:] |
---|
| 647 | def sampleTokens = results.collect( { it['sampleToken'] } ).unique() |
---|
| 648 | sampleTokens.each{ sampleTokenIndex[it] = i++ } |
---|
| 649 | |
---|
| 650 | i = 0 |
---|
| 651 | def measurementTokenIndex= [:] |
---|
| 652 | def measurementTokens = results.collect( { it['measurementToken'] } ).unique() |
---|
| 653 | measurementTokens.each{ measurementTokenIndex[it] = i++ } |
---|
| 654 | |
---|
| 655 | def data = [] |
---|
| 656 | measurementTokens.each{ m -> |
---|
| 657 | sampleTokens.each{ s -> |
---|
| 658 | def item = results.find{ it['sampleToken']==s && it['measurementToken']==m } |
---|
| 659 | data.push item ? item['value'] : null |
---|
| 660 | } |
---|
| 661 | } |
---|
| 662 | |
---|
| 663 | return [ sampleTokens, measurementTokens, data ] |
---|
| 664 | } |
---|
| 665 | |
---|
| 666 | } |
---|