source: trunk/grails-app/controllers/nl/tno/metagenomics/integration/RestController.groovy @ 18

Last change on this file since 18 was 18, checked in by robert@…, 8 years ago

Fixed issue #11: export of excel sample data is now column wise

File size: 21.1 KB
Line 
1package nl.tno.metagenomics.integration
2
3import grails.converters.*
4import nl.tno.metagenomics.*
5
6import org.apache.catalina.connector.Response;
7import 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 */
34class RestController {
35        def synchronizationService
36       
37        /****************************************************************/
38        /* REST resource for handling study change in GSCF              */
39        /****************************************************************/
40       
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
50
51                if( !studyToken ) {
52                        response.sendError(400, "No studyToken given" )
53                        return
54                }
55
56                // Search for the changed study
57                def study = Study.findByStudyToken( studyToken );
58
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(
64                                        name: "",
65                                        studyToken: studyToken,
66                                        isDirty: true
67                                        )
68                } else {
69                        log.info( "METAGENOMICS: GSCF notification for existing study " + studyToken );
70                        study.isDirty = true;
71                }
72                study.save(flush:true);
73
74                def jsonData = [ 'studyToken': studyToken, message: "Notify succesful" ];
75
76                render jsonData as JSON
77        }
78
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
98
99                if( !assay ) {
100                        synchronizationService.synchronizeStudies()
101                        assay = Assay.findByAssayToken( assayToken );
102
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                        }
114
115                        def url = [ 'url' : ConfigurationHolder.config.grails.serverURL + '/assay/show/' + assay.id.toString() ]
116
117                        render url as JSON
118                }
119        }
120
121        /***************************************************/
122        /* REST resources related to the querying in GSCF  */
123        /***************************************************/
124
125        /**
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":
160                                        fields[ entity ] = [ "# sequences", "Tag name", "Run name" ]
161                                        break;
162                                default:
163                                        // Do nothing
164                                        break;
165                        }
166                }
167               
168                render fields as JSON
169        }
170       
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 = {
185                println "Get queryable Field data: " + params
186               
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
213                for( token in tokens ) {
214                        def object = getQueryableObject( entity, token );
215
216                        if( object ) {
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                               
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                       
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               
288                switch( entity ) {
289                        case "Study":
290                                assaySamples = object.assays*.assaySamples;
291                                if( assaySamples ) {
292                                        assaySamples = assaySamples.flatten()
293                                } 
294                                break;
295                        case "Assay":
296                        case "Sample":
297                                assaySamples = object.assaySamples;
298                                break;
299                        default:
300                        // Other entities can't be handled
301                                return null;
302                }
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
324        }
325       
326        private def checkAssayToken( def assayToken ) {
327                if( !assayToken || assayToken == null ) {
328                        return false
329                }
330                def list = []
331                def assay = Assay.findByAssayToken( assayToken )
332
333                if( !assay || assay == null ) {
334                        return false;
335                }
336
337                return assay;
338        }
339
340        /****************************************************************/
341        /* REST resources for exporting data from GSCF                          */
342        /****************************************************************/
343
344        /**
345         * Retrieves a list of actions that can be performed on data with a specific entity.
346         *
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'
357         */
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":
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                                        ]
377                                        break;
378                                case "Assay":
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                                        ]
383                                        break;
384                                case "Sample":
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                                        ]
389                                        break;
390                                default:
391                                        // Do nothing
392                                        break;
393                        }
394                }
395               
396                render actions as JSON
397        }
398
399        /****************************************************************/
400        /* REST resources for providing basic data to the GSCF          */
401        /****************************************************************/
402        private getMeasurementTypes() {
403                return [ "# sequences" ]
404        }
405
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;
424
425                if( !checkAssayToken( assayToken ) ) {
426                        response.sendError(404)
427                        return false
428                }
429
430                render getMeasurementTypes() as JSON
431        }
432
433        /**
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"} ]
451         */
452        def getMeasurementMetaData = {
453                def assayToken = params.assayToken
454                def measurementTokens = params.measurementToken
455
456                if( !checkAssayToken( assayToken ) ) {
457                        response.sendError(404)
458                        return false
459                }
460
461                // For now, we don't have any metadata about the measurements
462                def measurements = getMeasurementTypes();
463                def measurementMetadata = [ ]
464
465                measurementTokens.each { token ->
466                        if( measurements.contains( token ) )
467                                measurementMetadata << [ "name" : token ];
468                }
469
470                render measurementMetadata as JSON
471        }
472
473        /**
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         *
573         */
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
582                }
583
584                def assay = checkAssayToken( assayToken );
585                if( !assay ) {
586                        response.sendError(404)
587                        return false
588                }
589
590                if( !measurementTokens ) {
591                        measurementTokens = []
592                }
593                else if( measurementTokens.class == java.lang.String ) {
594                        measurementTokens = [ measurementTokens ]
595                }
596
597                if( !sampleTokens ) {
598                        sampleTokens = []
599                }
600                else if( sampleTokens.class == java.lang.String ) {
601                        sampleTokens = [ sampleTokens ]
602                }
603
604                def data = AssaySample.findAllByAssay( assay );
605                def measurements = getMeasurementTypes()
606
607                def results = []
608                data.each { assaySample ->
609                        measurements.each { type ->
610                                def sample = assaySample.sample.sampleToken
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 ) ) ) {
616                                        results.push( [ 'sampleToken': sample, 'measurementToken': type, 'value': assaySample[ type ] ] )
617                                }
618                        }
619                }
620
621                if(!verbose) {
622                        results = compactTable( results )
623                }
624
625                render results as JSON
626        }
627
628       
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}
Note: See TracBrowser for help on using the repository browser.