NAME

CohortExplorer::Command::Query - CohortExplorer base 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

process( $opts, @args )

The method attempts to construct the SQL query from the hash ref returned by create_query_params. Upon successful execution of the SQL query the method returns the result set ($rs) which is a ref to array of arrays where each array corresponds to data on one entity or entity-visit combination (if applicable).

save_command( $opts, @args)

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

export( $opts, $rs, $dir, @args )

This method creates a export directory in the directory specified by --out option and calls process_result method in the subclass. Further processing by the method depends on the presence of --export option(s). If the user has specified --export option, the method first constructs the SQL query from the hash ref returned by entity_structure with a placeholder for table name. The method executes the same SQL query with a different bind value (table name) depending on 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, $rs, $dir )

This method is only called if the user has specified summary statistics option (--stats). The method attempts to calculate statistics from the data frame returned by create_dataset.

SUBCLASS HOOKS

usage_text()

This method should return the usage information for the command.

get_valid_variables()

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

create_query_params( $opts, @args )

This method should return a hash ref with keys, static, dynamic, or both depending on the datasource type and variables supplied as arguments and conditions. As standard datasource only contains 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 value of each key comprises of SQL parameters such as -from, -where, -group_by and -order_by. The parameters to this method are as follows:

$opts an options hash with the user-provided command options as keys and their values as hash values.

@args arguments to the command.

process_result( $opts, $rs, $dir, @args )

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

In this method,

$opts an options hash with the user-provided options as keys and their values as hash values.

$rs is the result set obtained upon executing the SQL query.

$dir is the export directory.

@args arguments to the command.

export_metadata( $table, $dir )

This method writes table metadata (i.e. variable dictionary) in the export directory.

In this method,

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

$dir is the export directory.

process_table( $table, $ts, $dir, $rs_entity )

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

The parameters to the method are:

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

$ts is the table set obtained from executing the table export SQL query.

$dir is the export directory.

$rs_entity is a ref to a list/hash containing entities present in the result set.

create_dataset( $rs )

This method should create a data frame for calculating statistics. The method should return a hash ref where key is the parameter, the statistics are calculated with respect to and value is the variable name-value pairs.

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 expected that the file $HOME/.CohortExplorer_History exists with RWX enabled for CohortExplorer.

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

   • execute method in DBI fails to execute the SQL query.

   • The full methods in package Statistics::Descriptive fail to calculate 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

cpanm CohortExplorer

perl -MCPAN -e shell
install CohortExplorer