/ 
CohortExplorer-0.10
River stage zero No dependents
/ CohortExplorer::Command::Query

NAME

CohortExplorer::Command::Query - CohortExplorer abstract class to search and compare command classes

DESCRIPTION

This class serves as the base class to search and compare command classes. The class is inherited from CLI::Framework::Command and overrides the following methods:

option_spec()

Returns application option specifications as expected by Getopt::Long::Descriptive

( 
  [ 'cond|c=s%'      => 'impose conditions'         ],
  [ 'out|o:s'        => 'provide output directory'  ],
  [ 'save-command|s' => 'save command'              ],
  [ 'stats|S'        => 'show summary statistics'   ],
  [ 'export|e=s@'    => 'export tables by name'     ],
  [ 'export-all|a'   => 'export all tables'         ] 
)

validate( $opts, @args )

This method validates the command options and arguments and throws exceptions when validation fails.

run( $opts, @args )

This method is responsible for the overall functioning of the command. The method calls option specific methods for option specific processing.

OPTION SPECIFIC PROCESSING

get_validation_variables()

This method should return a ref to the list for validating variables present under arguments and condition option(s).

process( $opts, $cache, @args )

The method attempts to query the database using the SQL constructed from the hash ref, returned from get_query_parameters. Upon successful execution of the SQL query the method returns the output (i.e. $result_set) which is a ref to array of arrays where each array corresponds to one row of entity data.

save_command( $opts, $cache, @args)

This method is only called if the user has specified the save command option (i.e. --save-command). The method first constructs the command from command options and arguments (i.e. $opts and @args) and adds it to the $COMMAND_HISTORY hash along with the datetime information. The $COMMAND_HISTORY contains all commands previously saved by the user.

export_data( $opts, $cache, $result_set, $dir, $csv, @args )

This method creates a output directory under the directory specified by the --out option and calls process_result_set method of the subclass. The further processing by the method depends on the presence of --export option(s). If the user has provided the --export option, the method first constructs the SQL from entity_structure with a table name placeholder. The method executes the same SQL with a different bind parameter (i.e. table name) depending upon the number of tables to be exported. The output obtained from successful execution of SQL is passed to process_table for further processing.

summary_stats( $opts, $cache, $result_set, $dir, $csv )

This method is only called if the user has specified summary statistics (i.e. --stats) option. The method computes the descriptive statistics from the data frame returned by get_stats_data.

SUBCLASS HOOKS

usage_text()

This method should return the usage information for the command.

get_query_parameters( $opts, $datasource, @args )

This method should return a hash ref with keys, static, dynamic, or both depending on the datasource type and variables supplied in arguments and conditions. As a standard datasource has all static tables so the hash ref must contain only one key, static where as a longitudinal datasource may contain both keys, static and dynamic provided the datasource has static tables. The parameters to the method are as follows:

$opts an options hash with the received command options as keys and their values as hash values.

$datasource is the datasource object.

@args arguments to the command.

process_result_set( $opts, $datasource, $result_set, $dir, $csv, @args )

This method should process the result set obtained after running the SQL query and write a csv file. If the variables provided as part of arguments and conditions belong only to the static tables, the method should return a ref to list of entities present in the result set. Otherwise, the method should return a hash ref with Entity_ID as keys and corresponding visit numbers as values.

In this method,

$opts an options hash with the received command options as keys and their values as hash values.

$datasource is the datasource object.

$result_set is the output obtained upon SQL execution.

$dir is the export directory.

$csv is the object of Text::CSV_XS.

@args arguments to the command.

process_table( $table, $datasource, $table_data, $dir, $csv, $result_entity )

This method should process the table data obtained from running the export SQL query. The method should write the table data in a csv file for all entities present in the result set.

The parameters to the method are:

$table is the name of the table to be exported.

$datasource is the datasource object.

$table_data is the output obtained from executing the export SQL query.

$dir is the export directory.

$csv is the object of Text::CSV_XS.

$result_entity is a ref to all entities present in the result-set. If variables present in cond option and @args belong to static tables the ref is simply to the list containing Entity_IDs. Otherwise, the reference is to a hash where Entity_IDs are keys and corresponding visit numbers are values.

get_stats_data( $result_set )

This method should generate the data for computing summary statistics. The method should return a hash ref with key as the parameter, the statistics are computed with respect to and values as the hash with variable names as keys and array ref as hash values.

DIAGNOSTICS

CohortExplorer::Command::Query throws following exceptions imported from CLI::Framework::Exceptions:

  1. throw_cmd_run_exception: This exception is thrown if one of the following conditions are met:

    • The command history file fails to load. For the save command option to work it is required that the file $HOME/.CohortExplorer_History exists with RWX enabled for CohortExplorer.

    • The select method from SQL::Abstract::More fails to construct the SQL from the supplied hash ref.

    • The method execute from DBI fails to execute the SQL query.

    • The full methods under package Statistics::Descriptive fail to compute statistics.

  2. throw_cmd_validation_exception: This exception is thrown whenever the command options/arguments fail to validate.

DEPENDENCIES

CLI::Framework::Command

CLI::Framework::Exceptions

Config::General

DBI

Exception::Class::TryCatch

FileHandle

File::HomeDir

File::Spec

SQL::Abstract::More

Statistics::Descriptive

Text::CSV_XS

Tie::IxHash

SEE ALSO

CohortExplorer

CohortExplorer::Datasource

CohortExplorer::Command::Describe

CohortExplorer::Command::Find

CohortExplorer::Command::History

CohortExplorer::Command::Query::Search

CohortExplorer::Command::Query::Compare

LICENSE AND COPYRIGHT

Copyright (c) 2013-2014 Abhishek Dixit (adixit@cpan.org). All rights reserved.

This program is free software: you can redistribute it and/or modify it under the terms of either:

  • the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version, or

  • the "Artistic Licence".

AUTHOR

Abhishek Dixit