Documentation

To use Damon, you need to be able to access the documentation for each of its functions and methods.  The syntax is >>> help(Module.Class.Method) or >>> help(Module.Function).  Here is how it works.

Open IDLE
Open the Python IDLE GUI.  In Windows, go to the Start button and search for IDLE.  On the Mac, search for it in your Applications folder.  Shortcut it.

IDLE

Python 2.7.2 |EPD 7.1-1 (64-bit)| (default, Jul  3 2011, 15:56:02) 
[GCC 4.0.1 (Apple Inc. build 5493)] on darwin
Type "copyright", "credits" or "license()" for more information.
>>> 







Import Damon
At the >>> prompt, type import damon1.  This loads the damon1 package.  On the next line, type >>>  help(damon1).  This gives access to top-level help.

Import damon1

>>> import damon1
>>> help(damon1)
Help on package damon1:

NAME
    damon1

FILE
    /Library/Frameworks/EPD64.framework/Versions/7.3/lib/python2.7/site-packages/damon1/__init__.py

DESCRIPTION
    Copyright (C) 2008 - 2012 Mark H. Moulton for Pythias Consulting, LLC.
    P.O. Box 391512
    Mountain View, CA 94039-1512
    
    Email:  pythiasconsulting@gmail.com
    
    Website:  www.pythiasconsulting.com
    
    Damon Version:  1.1.02
    Damon Release Date:  10/1/2012
    
    Damon is written in Python 2.7.2 and Numpy 1.6.1, as distributed
    by Enthought (EPD 7.2-2 (64-bit)).
    
    
    License
    -------
    This program is free software: you can redistribute it and/or modify

    |
    |
    snip
    |
    V
    
    Cheatsheet of Damon Methods
    ---------------------------
    In (approximate) order of application:
    
    d = create_data()['data']       =>  Create artificial Damon objects
    d = TopDamon()                  =>  Create a Damon object from an existing dataset
    d = Damon(data,'array',...)     =>  More generic low-level way to create a Damon object
    d.merge_info()                  =>  Merge row or column info into labels
    d.extract_valid()               =>  Extract only valid rows/cols
    d.pseudomiss()                  =>  Create index of pseudo-missing cells
    d.score_mc()                    =>  Score multiple-choice data
    d.subscale()                    =>  Append raw scores for item subscales
    d.parse()                       =>  Parse response options to separate columns
    d.standardize()                 =>  Convert all columns into a standard metric
    d.rasch()                       =>  Rasch-analyze data (in place of coord())
    d.coord()                       =>  Calculate row and column coordinates
    d.objectify()                   =>  Maximize objectivity of specified columns (in place of coord)
    d.base_est()                    =>  Calculate cell estimates
    d.base_resid()                  =>  Get residuals (observation - estimate)
    d.base_ear()                    =>  Get expected absolute residuals
    d.base_se()                     =>  Get standard errors for all cells
    d.equate()                      =>  Equate two datasets using a bank
    d.base_fit()                    =>  Get cell fit statistics
    d.fin_est()                     =>  Get final estimates, original metric
    d.est2logit()                   =>  Convert estimates to logits
    d.item_diff()                   =>  Get probability-based item difficulties
    d.fillmiss()                    =>  Fill missing cells of original dataset
    d.fin_resid()                   =>  Get final cell residuals, original metric
    d.fin_fit()                     =>  Get final cell fit, original metric
    d.restore_invalid()             =>  Restores invalid rows/cols to output arrays
    d.summstat()                    =>  Get summary row/column/range statistics
    d.bank()                        =>  Save row/column coordinates in "bank" file
    d.export()                      =>  Export specified outputs as files

PACKAGE CONTENTS
    core
    replace_it
    template
    tests (package)
    tools
    utils

DATA
    __all__ = ['core', 'tools']


>>> 

The import damon1 statement works fine, but to get help on individual methods the syntax can be a little long-winded.  For instance, to get help on the standardize() method, you would type:

Long-winded Help

# A bit of a mouthful
>>> help(damon1.core.Damon.standardize)

To simplify the syntax, at the >>> prompt, type import damon1.core as core .  The "as core" allows you to nickname damon.core as "core", to save typing.  You can also say import damon1.core as dmn.   Then type import damon1.tools as tools .  These two imports load all of Damon's public methods and functions.  

Import Damon

Python 2.7.2 |EPD 7.1-1 (64-bit)| (default, Jul  3 2011, 15:56:02) 
[GCC 4.0.1 (Apple Inc. build 5493)] on darwin
Type "copyright", "credits" or "license()" for more information.
>>> import damon1.core as core
>>> import damon1.tools as tools
>>>




List Contents
At the >>> prompt, type dir(core) .  Then type dir(tools) .  This gives you a top-level list of the contents of core and tools.  Note that "core" refers to the core.py Python file inside the damon1 directory, and "tools" refers to the tools.py file.  Python files are called "modules".  Notice the square brackets around the contents; this signifies a python list object.  Within each list are a bunch of objects, mostly functions.  The functions with double underscores around them (e.g., __doc__, __file__) belong to Python.  Most of the objects in the tools module you won't need.  You will mainly use three items in the core module:  create_data(), TopDamon(), and Damon().  

List Contents

>>> import damon1.core as core
>>> import damon1.tools as tools
>>> dir(core)
['Damon', 'TopDamon', '__builtins__', '__doc__', '__file__', '__name__', '__package__', 'cPickle', 'core', 'create_data', 'np', 'npla', 'npma', 'npr', 'os', 'sys', 'tools', 'utils']
>>> dir(tools)
['__builtins__', '__doc__', '__file__', '__name__', '__package__', 'addlabels', 'cPickle', 'condcoord', 'core', 'correl', 'cumnormprob', 'damon_dicts', 'dups', 'estimate', 'faccoord', 'fit', 'fitsd', 'getkeys', 'guess_validchars', 'h_stat', 'homogenize', 'invUTU', 'irls', 'jolt', 'log2prob', 'mergetool', 'metricprob', 'np', 'npla', 'npma', 'npr', 'objectivity', 'obsdeltatest', 'obspercell', 'os', 'percent25', 'percent75', 'ptbis', 'pytables', 'rand_chunk', 'reliability', 'rescale', 'residuals', 'resp_prob', 'rmsear', 'rmsr', 'separation', 'solve1', 'solve2', 'sterrpbc', 'subscale_filter', 'sys', 'test_damon', 'tools', 'triproject', 'tuple2table', 'unbiascoord', 'unbiasest', 'utils', 'valchars', 'weight_coord', 'zeros_chunk']
>>> 


Read About Core
The great bulk of documentation is written in the core.py module.  You can type >>> help(core), but the output will be voluminous.  It's better to get help for individual elements within core. 

Core Help

>>>  import damon1.core as core
>>>  help(core.TopDamon)

# prints out information about the TopDamon() function

However, you probably don't want to type >>>  help(core.Damon), because this, too, will be voluminous.  

List Damon Contents
The most important element in core is Damon.  Damon creates an "instance" (aka "object") of a Damon analysis.  It loads and formats a dataset for analysis, then applies Damon "methods" to it.  Each Damon object has its own dataset, and its methods are generally applied only once to that dataset, in a specific order.  To get a list of Damon methods, use dir >>> dir(core.Damon) . These are the commands to learn.  The one you will use the most is __init__ , which is used to "initialize" a Damon object, set up its various parameters.  When getting help, look up each Damon object method individually.

Damon Contents

>>> dir(core.Damon)
['__class__', '__delattr__', '__dict__', '__doc__', '__format__', '__getattribute__', '__getitem__', '__hash__', '__init__', '__module__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', 'bank', 'base_ear', 'base_est', 'base_fit', 'base_resid', 'base_se', 'combokeys', 'coord', 'equate', 'est2logit', 'export', 'extract', 'extract_valid', 'fillmiss', 'fin_ear', 'fin_est', 'fin_fit', 'fin_resid', 'fin_se', 'item_diff', 'merge', 'merge_info', 'objectify', 'parse', 'pseudomiss', 'rasch', 'restore_invalid', 'score_mc', 'standardize', 'subscale', 'summstat', 'table2tuple', 'transpose']
>>> 



Get Help
To get help on a specific method, type >>> help(core.Damon.my_method) .  (When I say, "my_method" or "my_something", I don't mean these literally; they indicate a thing of your choosing.)  Note the syntax:  help(Module.Class.Method) .  The "method" belongs to a "class" (the Damon class), which belongs to a "module" (a Python file).  The "." period signals that the element to the right is an "attribute" of the thing to the left.  To get help on the "extract" method, type  >>> help(core.Damon.extract) .

Help on extract()

>>> help(core.Damon.extract)
Help on method extract in module damon1.core:

extract(self, datadict, getrows={'Get': 'AllExcept', 'Labels': 'key', 'Rows': [None]}, getcols={'Cols': [None], 'Get': 'AllExcept', 'Labels': 'key'}, labels_only=None) unbound damon1.core.Damon method
    Extracts data() array with specified rows and columns.
    
    Returns
    -------
        Unlike other Damon methods, extract() does not return

    |
    |
    snip
    |
    V

    Paste method
    ------------
        extract(datadict,  # [data dictionary, e.g., self.data_out, self.coord_out]
                getrows = {'Get':'AllExcept','Labels':'key','Rows':[None]}, # [{'Get':<'AllExcept','NoneExcept'>,'Labels':<'key',1,2,...,'index'>,'Rows':[<None,keys,atts,index>]}]
                getcols = {'Get':'AllExcept','Labels':'key','Cols':[None]}, # [{'Get':<'AllExcept','NoneExcept'>,'Labels':<'key',1,2,...,'index'>,'Cols':[<None,keys,atts,index>]}]
                )

>>> 

This is only a snippet of the extract() method documentation.  Each method doc has the following sections:  Returns, Comments, Arguments, Examples (under construction), and Paste Method.  The "Paste Method" section always comes at the end and may be the most useful.  It contains a line-by-line list of the options available for each parameter that can be copied and pasted into your Python script (don't worry about the lines wrapping around).  This saves you from having to memorize the options for each parameter.  They are right there, already documented and described.

To get help on how to initialize a Damon object (which you will do a LOT), type >>> help(core.DamonObj.__init__) .  Don't be thrown by the __init__  nomenclature.  This is Python's generic tool for initializing instances (or objects) of a class.  We'll go over Damon.__init__ in the next lesson.

Help on create_data()
Aside from the Damon methods, the function you will use most is create_data().  Note that I called it a function instead of a method.  Functions are pretty much the same as methods, except they are not tied to a particular class.  Since create_data() creates artificial data out of the blue, it does not belong to the Damon class (which requires already-existing data).  To get help on create_data(), type >>> help(core.create_data) .  The function resides in (is an attribute of) the core.py file.

Help on create_data()

>>> import damon1.core as core
>>> help(core.create_data)
Help on function create_data in module damon1.core:

create_data(nfac0, nfac1, ndim, seed=None, facmetric=[4, -2], noise=None, validchars=None, mean_sd=None, p_nan=0.0, nanval=-999.0, condcoord_=None, nheaders4rows=1, nheaders4cols=1, extra_headers=0, input_array=None, output_as='Damon', outfile=None, delimiter=None, bankf0=None, bankf1=None, verbose=True)
    Create simulated model and noisy data objects analyzable by Damon.
        
    Returns
    -------
        create_data() returns a python dictionary where each of the following
        datasets is formatted either as a DamonObj, a datadict, an array,
        or a file, or combinations thereof.  'data' and 'model' may
        also be output as '.hd5' or pytables files to conserve memory.
        
        {'data':,       =>  simulated 'observed' data, with error and missing added
        'model':,       =>  simulated 'True' values, no error added
        'anskey':,      =>  answer key, when data are alpha (simulating multiple choice data)
        'fac0coord':,   =>  theoretical row coordinates
        'fac1coord':    =>  theoretical column coordinates
        }

  |
  |
snip
  |
  |
  V


Help on tools
The tools.py module contains a bunch of functions (not methods) which are used by Damon internally but which may be used outside of Damon.  Their most important feature is that they don't need to be applied to Damon objects; they're generic.  To access tool docs, type >>> help(tools.my_tool) .  For example, to access the correl() function (used to calculate correlations), type >>> help(tools.correl) .

Help on correl()

>>> import damon1.tools as tools
>>> help(tools.correl)
Help on function correl in module damon1.tools:

correl(observed, estimates, nanval=-999.0, form='Corr', count=None)
    Correlates observations to estimates.
    
    Returns
    -------
        When form = 'Corr', correl() returns a scalar between -1.0
        and 1.0 representing the correlation between an array of
        observations and an array of estimates.  It can also return
        covariance and mean product.
  |
  |
snip
  |
  |
  V

And that is how you get help on a specific tool or Damon method.