예제 #1
0
def generate_ica_report(
    stats_report_filename,
    ica_maps,
    mask=None,
    report_title='ICA Report',
    methods_text='ICA',
    anat=None,
    anat_affine=None,
    threshold=2.,
    cluster_th=0,
    cmap=viz.cm.cold_hot,
    start_time=None,
    user_script_name=None,
    progress_logger=None,
    shutdown_all_reloaders=True,
    **glm_kwargs
    ):
    """Generates a report summarizing the statistical methods and results

    Parameters
    ----------
    stats_report_filename: string:
        html file to which output (generated html) will be written

    contrasts: dict of arrays
        contrasts we are interested in; same number of contrasts as zmaps;
        same keys

    zmaps: dict of image objects or strings (image filenames)
        zmaps for contrasts we are interested in; one per contrast id

    mask: 'nifti image object'
        brain mask for ROI

    design_matrix: list of 'DesignMatrix', `numpy.ndarray` objects or of
    strings (.png, .npz, etc.) for filenames
        design matrices for the experimental conditions

    contrasts: dict of arrays
       dictionary of contrasts of interest; the keys are the contrast ids,
       the values are contrast values (lists)

    z_maps: dict of 3D image objects or strings (image filenames)
       dict with same keys as 'contrasts'; the values are paths of z-maps
       for the respective contrasts

    anat: 3D array (optional)
        brain image to serve bg unto which activation maps will be plotted;
        passed to viz.plot_map API

    anat_affine: 2D array (optional)
        affine data for the anat

    threshold: float (optional)
        threshold to be applied to activation maps voxel-wise

    cluster_th: int (optional)
        minimal voxel count for clusteres declared as 'activated'

    cmap: cmap object (default viz.cm.cold_hot)
        color-map to use in plotting activation maps

    start_time: string (optional)
        start time for the stats analysis (useful for the generated
        report page)

    user_script_name: string (optional, default None)
        existing filename, path to user script used in doing the analysis

    progress_logger: ProgressLogger object (optional)
        handle for logging progress

    shutdown_all_reloaders: bool (optional, default True)
        if True, all pages connected to the stats report page will
        be prevented from reloading after the stats report page
        has been completely generated

    **glm_kwargs:
        kwargs used to specify the control parameters used to specify the
        experimental paradigm and the GLM

    """

    # prepare for stats reporting
    if progress_logger is None:
        progress_logger = base_reporter.ProgressReport()

    output_dir = os.path.dirname(stats_report_filename)

    # copy css and js stuff to output dir
    base_reporter.copy_web_conf_files(output_dir)

    # initialize gallery of activation maps
    activation_thumbs = base_reporter.ResultsGallery(
        loader_filename=os.path.join(output_dir,
                                     "activation.html")
        )

    # get caller module handle from stack-frame
    if user_script_name is None:
        user_script_name = sys.argv[0]
    user_source_code = base_reporter.get_module_source_code(
        user_script_name)

    if start_time is None:
        start_time = time.ctime()

    ica_html_markup = base_reporter.get_ica_html_template(
        ).substitute(
        title=report_title,
        start_time=start_time,

        # insert source code stub
        source_script_name=user_script_name,
        source_code=user_source_code,

        methods=methods_text,
        cmap=cmap.name)

    with open(stats_report_filename, 'w') as fd:
        fd.write(str(ica_html_markup))
        fd.close()

    progress_logger.log("<b>ICA</b><br/><br/>")

    # make colorbar (place-holder, will be overridden, once we've figured out
    # the correct end points) for activations
    colorbar_outfile = os.path.join(output_dir,
                                    'activation_colorbar.png')
    base_reporter.make_standalone_colorbar(
        cmap, threshold, 8., colorbar_outfile)

    # generate thumbs for the gallery
    _vmax = 0
    _vmin = threshold
    for ica_map_id, ica_map in ica_maps.iteritems():
        # load the map
        if isinstance(ica_map, basestring):
            ica_map = nibabel.load(ica_map)

        # compute cut_coords for viz.plot_map(..) API
        cut_coords = base_reporter.get_cut_coords(
            ica_map.get_data(), n_axials=12, delta_z_axis=3)

        # compute vmin and vmax
        vmin, vmax = base_reporter.compute_vmin_vmax(ica_map.get_data())

        # update colorbar endpoints
        _vmax = max(_vmax, vmax)
        _vmin = min(_vmin, vmin)

        # plot activation proper
        viz.plot_map(ica_map.get_data(), ica_map.get_affine(),
                     cmap=cmap,
                     anat=anat,
                     anat_affine=anat_affine,
                     vmin=vmin,
                     vmax=vmax,
                     threshold=threshold,
                     slicer='z',
                     cut_coords=cut_coords,

                     black_bg=True,
                     )

        # store activation plot
        ica_map_plot = os.path.join(output_dir,
                                  "%s_ica_map.png" % ica_map_id)
        pl.savefig(ica_map_plot, dpi=200, bbox_inches='tight',
                   facecolor="k",
                   edgecolor="k")
        stats_table = ica_map_plot  # os.path.join(output_dir,
                                   # "%s_stats_table.html" % ica_map_id)

        # create thumbnail for activation
        thumbnail = base_reporter.Thumbnail()
        thumbnail.a = base_reporter.a(href=os.path.basename(stats_table))
        thumbnail.img = base_reporter.img(
            src=os.path.basename(ica_map_plot), height="200px",)
        thumbnail.description = "Component: %s" % ica_map_id
        activation_thumbs.commit_thumbnails(thumbnail)

    # make colorbar for activations
    base_reporter.make_standalone_colorbar(
        cmap, _vmin, _vmax, colorbar_outfile)

    # we're done, shut down re-loaders
    progress_logger.log('<hr/>')

    # prevent stats report page from reloading henceforth
    progress_logger.finish(stats_report_filename)

    # prevent any related page from reloading
    if shutdown_all_reloaders:
        progress_logger.finish_dir(output_dir)

    # return generated html
    with open(stats_report_filename, 'r') as fd:
        stats_report = fd.read()
        fd.close()

        return stats_report
예제 #2
0
def generate_ica_report(stats_report_filename,
                        ica_maps,
                        mask=None,
                        report_title='ICA Report',
                        methods_text='ICA',
                        anat=None,
                        anat_affine=None,
                        threshold=2.,
                        cluster_th=0,
                        cmap=viz.cm.cold_hot,
                        start_time=None,
                        user_script_name=None,
                        progress_logger=None,
                        shutdown_all_reloaders=True,
                        **glm_kwargs):
    """Generates a report summarizing the statistical methods and results

    Parameters
    ----------
    stats_report_filename: string:
        html file to which output (generated html) will be written

    contrasts: dict of arrays
        contrasts we are interested in; same number of contrasts as zmaps;
        same keys

    zmaps: dict of image objects or strings (image filenames)
        zmaps for contrasts we are interested in; one per contrast id

    mask: 'nifti image object'
        brain mask for ROI

    design_matrix: list of 'DesignMatrix', `numpy.ndarray` objects or of
    strings (.png, .npz, etc.) for filenames
        design matrices for the experimental conditions

    contrasts: dict of arrays
       dictionary of contrasts of interest; the keys are the contrast ids,
       the values are contrast values (lists)

    z_maps: dict of 3D image objects or strings (image filenames)
       dict with same keys as 'contrasts'; the values are paths of z-maps
       for the respective contrasts

    anat: 3D array (optional)
        brain image to serve bg unto which activation maps will be plotted;
        passed to viz.plot_map API

    anat_affine: 2D array (optional)
        affine data for the anat

    threshold: float (optional)
        threshold to be applied to activation maps voxel-wise

    cluster_th: int (optional)
        minimal voxel count for clusteres declared as 'activated'

    cmap: cmap object (default viz.cm.cold_hot)
        color-map to use in plotting activation maps

    start_time: string (optional)
        start time for the stats analysis (useful for the generated
        report page)

    user_script_name: string (optional, default None)
        existing filename, path to user script used in doing the analysis

    progress_logger: ProgressLogger object (optional)
        handle for logging progress

    shutdown_all_reloaders: bool (optional, default True)
        if True, all pages connected to the stats report page will
        be prevented from reloading after the stats report page
        has been completely generated

    **glm_kwargs:
        kwargs used to specify the control parameters used to specify the
        experimental paradigm and the GLM

    """

    # prepare for stats reporting
    if progress_logger is None:
        progress_logger = base_reporter.ProgressReport()

    output_dir = os.path.dirname(stats_report_filename)

    # copy css and js stuff to output dir
    base_reporter.copy_web_conf_files(output_dir)

    # initialize gallery of activation maps
    activation_thumbs = base_reporter.ResultsGallery(
        loader_filename=os.path.join(output_dir, "activation.html"))

    # get caller module handle from stack-frame
    if user_script_name is None:
        user_script_name = sys.argv[0]
    user_source_code = base_reporter.get_module_source_code(user_script_name)

    if start_time is None:
        start_time = time.ctime()

    ica_html_markup = base_reporter.get_ica_html_template().substitute(
        title=report_title,
        start_time=start_time,

        # insert source code stub
        source_script_name=user_script_name,
        source_code=user_source_code,
        methods=methods_text,
        cmap=cmap.name)

    with open(stats_report_filename, 'w') as fd:
        fd.write(str(ica_html_markup))
        fd.close()

    progress_logger.log("<b>ICA</b><br/><br/>")

    # make colorbar (place-holder, will be overridden, once we've figured out
    # the correct end points) for activations
    colorbar_outfile = os.path.join(output_dir, 'activation_colorbar.png')
    base_reporter.make_standalone_colorbar(cmap, threshold, 8.,
                                           colorbar_outfile)

    # generate thumbs for the gallery
    _vmax = 0
    _vmin = threshold
    for ica_map_id, ica_map in ica_maps.iteritems():
        # load the map
        if isinstance(ica_map, basestring):
            ica_map = nibabel.load(ica_map)

        # compute cut_coords for viz.plot_map(..) API
        cut_coords = base_reporter.get_cut_coords(ica_map.get_data(),
                                                  n_axials=12,
                                                  delta_z_axis=3)

        # compute vmin and vmax
        vmin, vmax = base_reporter.compute_vmin_vmax(ica_map.get_data())

        # update colorbar endpoints
        _vmax = max(_vmax, vmax)
        _vmin = min(_vmin, vmin)

        # plot activation proper
        viz.plot_map(
            ica_map.get_data(),
            ica_map.get_affine(),
            cmap=cmap,
            anat=anat,
            anat_affine=anat_affine,
            vmin=vmin,
            vmax=vmax,
            threshold=threshold,
            slicer='z',
            cut_coords=cut_coords,
            black_bg=True,
        )

        # store activation plot
        ica_map_plot = os.path.join(output_dir, "%s_ica_map.png" % ica_map_id)
        pl.savefig(ica_map_plot,
                   dpi=200,
                   bbox_inches='tight',
                   facecolor="k",
                   edgecolor="k")
        pl.close()
        stats_table = ica_map_plot  # os.path.join(output_dir,
        # "%s_stats_table.html" % ica_map_id)

        # create thumbnail for activation
        thumbnail = base_reporter.Thumbnail()
        thumbnail.a = base_reporter.a(href=os.path.basename(stats_table))
        thumbnail.img = base_reporter.img(
            src=os.path.basename(ica_map_plot),
            height="200px",
        )
        thumbnail.description = "Component: %s" % ica_map_id
        activation_thumbs.commit_thumbnails(thumbnail)

    # make colorbar for activations
    base_reporter.make_standalone_colorbar(cmap, _vmin, _vmax,
                                           colorbar_outfile)

    # we're done, shut down re-loaders
    progress_logger.log('<hr/>')

    # prevent stats report page from reloading henceforth
    progress_logger.finish(stats_report_filename)

    # prevent any related page from reloading
    if shutdown_all_reloaders:
        progress_logger.finish_dir(output_dir)

    # return generated html
    with open(stats_report_filename, 'r') as fd:
        stats_report = fd.read()
        fd.close()

        return stats_report
예제 #3
0
def generate_subject_stats_report(
    stats_report_filename,
    contrasts,
    z_maps,
    mask,
    design_matrices=None,
    subject_id=None,
    anat=None,
    anat_affine=None,
    slicer="z",
    cut_coords=None,
    statistical_mapping_trick=False,
    threshold=2.3,
    cluster_th=0,
    cmap=viz.cm.cold_hot,
    start_time=None,
    title=None,
    user_script_name=None,
    progress_logger=None,
    shutdown_all_reloaders=True,
    **glm_kwargs
    ):
    """Generates a report summarizing the statistical methods and results

    Parameters
    ----------
    stats_report_filename: string:
        html file to which output (generated html) will be written

    contrasts: dict of arrays
        contrasts we are interested in; same number of contrasts as zmaps;
        same keys

    zmaps: dict of image objects or strings (image filenames)
        zmaps for contrasts we are interested in; one per contrast id

    mask: 'nifti image object'
        brain mask for ROI

    design_matrix: list of 'DesignMatrix', `numpy.ndarray` objects or of
    strings (.png, .npz, etc.) for filenames
        design matrices for the experimental conditions

    contrasts: dict of arrays
       dictionary of contrasts of interest; the keys are the contrast ids,
       the values are contrast values (lists)

    z_maps: dict of 3D image objects or strings (image filenames)
       dict with same keys as 'contrasts'; the values are paths of z-maps
       for the respective contrasts

    anat: 3D array (optional)
        brain image to serve bg unto which activation maps will be plotted;
        passed to viz.plot_map API

    anat_affine: 2D array (optional)
        affine data for the anat

    threshold: float (optional)
        threshold to be applied to activation maps voxel-wise

    cluster_th: int (optional)
        minimal voxel count for clusteres declared as 'activated'

    cmap: cmap object (default viz.cm.cold_hot)
        color-map to use in plotting activation maps

    start_time: string (optional)
        start time for the stats analysis (useful for the generated
        report page)

    user_script_name: string (optional, default None)
        existing filename, path to user script used in doing the analysis

    progress_logger: ProgressLogger object (optional)
        handle for logging progress

    shutdown_all_reloaders: bool (optional, default True)
        if True, all pages connected to the stats report page will
        be prevented from reloading after the stats report page
        has been completely generated

    **glm_kwargs:
        kwargs used to specify the control parameters used to specify the
        experimental paradigm and the GLM

    """
    # Delayed import of nipy for more robustness when it is not present
    from nipy.modalities.fmri.design_matrix import DesignMatrix

    if slicer == "ortho":
        statistical_mapping_trick = False

        if not hasattr(cut_coords, "__iter__"):
            cut_coords = None
    
    # prepare for stats reporting
    if progress_logger is None:
        progress_logger = base_reporter.ProgressReport()

    output_dir = os.path.dirname(stats_report_filename)
    if not os.path.exists(output_dir):
        os.makedirs(output_dir)

    # copy css and js stuff to output dir
    base_reporter.copy_web_conf_files(output_dir)

    # initialize gallery of design matrices
    design_thumbs = base_reporter.ResultsGallery(
        loader_filename=os.path.join(output_dir,
                                     "design.html")
        )

    # initialize gallery of activation maps
    activation_thumbs = base_reporter.ResultsGallery(
        loader_filename=os.path.join(output_dir,
                                     "activation.html")
        )

    # get caller module handle from stack-frame
    if user_script_name is None:
        user_script_name = sys.argv[0]
    user_source_code = base_reporter.get_module_source_code(
        user_script_name)

    methods = """
    GLM and Statistical Inference have been done using the <i>%s</i> script, \
powered by <a href="%s">nipy</a>. Statistic images have been thresholded at \
Z>%s voxel-level.
    """ % (user_script_name, base_reporter.NIPY_URL, threshold)

    # report the control parameters used in the paradigm and analysis
    design_params = ""
    glm_kwargs["contrasts"] = contrasts
    if len(glm_kwargs):
        design_params += ("The following control parameters were used for  "
                    " specifying the experimental paradigm and fitting the "
                    "GLM:<br/><ul>")

        design_params += base_reporter.dict_to_html_ul(glm_kwargs)

    if start_time is None:
        start_time = base_reporter.pretty_time()

    if title is None:
        title = "GLM and Statistical Inference"
        if not subject_id is None:
            title += " for subject %s" % subject_id

    level1_html_markup = base_reporter.get_subject_report_stats_html_template(
        title=title,
        start_time=start_time,
        subject_id=subject_id,

        # insert source code stub
        source_script_name=user_script_name,
        source_code=user_source_code,

        design_params=design_params,
        methods=methods,
        threshold=threshold,
        cmap=cmap.name)

    with open(stats_report_filename, 'w') as fd:
        fd.write(str(level1_html_markup))
        fd.close()

    progress_logger.log("<b>Level 1 statistics</b><br/><br/>")

    # create design matrix thumbs
    if not design_matrices is None:
        if not hasattr(design_matrices, '__len__'):
            design_matrices = [design_matrices]

        for design_matrix, j in zip(design_matrices,
                                    xrange(len(design_matrices))):
            # sanitize design_matrix type
            if isinstance(design_matrix, basestring):
                if not isinstance(design_matrix, DesignMatrix):
                    if design_matrix.endswith('.npz'):
                        npz = np.load(design_matrix)
                        design_matrix = DesignMatrix(npz['X'],
                                                     npz['conditions'],
                                                     )
                else:
                    # XXX handle case of .png, jpeg design matrix image
                    raise TypeError(
                        "Unsupported design matrix type: %s" % type(
                            design_matrix))
            elif isinstance(design_matrix, np.ndarray) or isinstance(
                design_matrix,
                list):
                X = np.array(design_matrix)
                # assert len(X.shape) == 2
                conditions = ['%i' % i for i in xrange(X.shape[-1])]
                design_matrix = DesignMatrix(X, conditions)
            # else:
            #     raise TypeError(
            #         "Unsupported design matrix type '%s'" % type(
            #             design_matrix))

            # plot design_matrix proper
            ax = design_matrix.show(rescale=True)
            ax.set_position([.05, .25, .9, .65])
            dmat_outfile = os.path.join(output_dir,
                                        'design_matrix_%i.png' % (j + 1),
                                        )
            pl.savefig(dmat_outfile, bbox_inches="tight", dpi=200)
            pl.close()

            thumb = base_reporter.Thumbnail()
            thumb.a = base_reporter.a(href=os.path.basename(dmat_outfile))
            thumb.img = base_reporter.img(src=os.path.basename(dmat_outfile),
                                     height="500px",
                                     )
            thumb.description = "Design Matrix"
            thumb.description += " %s" % (j + 1) if len(
                design_matrices) > 1 else ""

            # commit activation thumbnail into gallery
            design_thumbs.commit_thumbnails(thumb)

    # make colorbar (place-holder, will be overridden, once we've figured out
    # the correct end points) for activations
    colorbar_outfile = os.path.join(output_dir,
                                    'activation_colorbar.png')
    base_reporter.make_standalone_colorbar(
        cmap, threshold, 8., colorbar_outfile)

    # create activation thumbs
    _vmax = 0
    _vmin = threshold
    for contrast_id, contrast_val in contrasts.iteritems():
        z_map = z_maps[contrast_id]

        # load the map
        if isinstance(z_map, basestring):
            z_map = nibabel.load(z_map)

        # compute vmin and vmax
        vmin, vmax = base_reporter.compute_vmin_vmax(z_map.get_data())

        # update colorbar endpoints
        _vmax = max(_vmax, vmax)
        _vmin = min(_vmin, vmin)

        # sanitize anat
        if not anat is None:
            if anat.ndim == 4:
                assert anat.shape[-1] == 1, (
                    "Expecting 3D array for ant, got shape %s" % str(
                        anat.shape))
                anat = anat[..., 0]
            else:
                assert anat.ndim == 3, (
                    "Expecting 3D array for ant, got shape %s" % str(
                        anat.shape))

        # generate level 1 stats table
        title = "Level 1 stats for %s contrast" % contrast_id
        stats_table = os.path.join(output_dir, "%s_stats_table.html" % (
                contrast_id))
        z_clusters = generate_level1_stats_table(
            z_map, mask,
            stats_table,
            cluster_th=cluster_th,
            z_threshold=threshold,
            title=title,
            )

        # compute cut_coords
        if statistical_mapping_trick:
            slicer = slicer.lower()
            if slicer in ["x", "y", "z"] and cut_coords is None or isinstance(
                cut_coords, int):
                axis = 'xyz'.index(slicer)
                if cut_coords is None:
                    cut_coords = min(5, len(z_clusters))
                _cut_coords = [x for zc in z_clusters for x in list(
                        set(zc['maxima'][..., axis]))]
                # # _cut_coords = _maximally_separated_subset(
                # #     _cut_coords, cut_coords)

                # assert len(_cut_coords) == cut_coords
                cut_coords = _cut_coords

        # plot activation proper
        viz.plot_map(z_map.get_data(), z_map.get_affine(),
                     cmap=cmap,
                     anat=anat,
                     anat_affine=anat_affine,
                     threshold=threshold,
                     slicer=slicer,
                     cut_coords=cut_coords,
                     black_bg=True
                     )

        # store activation plot
        z_map_plot = os.path.join(output_dir,
                                  "%s_z_map.png" % contrast_id)
        pl.savefig(z_map_plot, dpi=200, bbox_inches='tight', facecolor="k",
                   edgecolor="k")
        pl.close()

        # create thumbnail for activation
        thumbnail = base_reporter.Thumbnail()
        thumbnail.a = base_reporter.a(href=os.path.basename(stats_table))
        thumbnail.img = base_reporter.img(src=os.path.basename(z_map_plot),
                                          height="150px",)
        thumbnail.description = contrast_id
        activation_thumbs.commit_thumbnails(thumbnail)

    # make colorbar for activations
    base_reporter.make_standalone_colorbar(
        cmap, _vmin, _vmax, colorbar_outfile)

    # we're done, shut down re-loaders
    progress_logger.log('<hr/>')

    # prevent stats report page from reloading henceforth
    progress_logger.finish(stats_report_filename)

    # prevent any related page from reloading
    if shutdown_all_reloaders:
        progress_logger.finish_dir(output_dir)

    # return generated html
    with open(stats_report_filename, 'r') as fd:
        stats_report = fd.read()
        fd.close()

        return stats_report
예제 #4
0
def generate_subject_stats_report(stats_report_filename,
                                  contrasts,
                                  z_maps,
                                  mask,
                                  design_matrices=None,
                                  subject_id=None,
                                  anat=None,
                                  anat_affine=None,
                                  slicer="z",
                                  cut_coords=None,
                                  statistical_mapping_trick=False,
                                  threshold=2.3,
                                  cluster_th=0,
                                  cmap=viz.cm.cold_hot,
                                  start_time=None,
                                  title=None,
                                  user_script_name=None,
                                  progress_logger=None,
                                  shutdown_all_reloaders=True,
                                  **glm_kwargs):
    """Generates a report summarizing the statistical methods and results

    Parameters
    ----------
    stats_report_filename: string:
        html file to which output (generated html) will be written

    contrasts: dict of arrays
        contrasts we are interested in; same number of contrasts as zmaps;
        same keys

    zmaps: dict of image objects or strings (image filenames)
        zmaps for contrasts we are interested in; one per contrast id

    mask: 'nifti image object'
        brain mask for ROI

    design_matrix: list of 'DesignMatrix', `numpy.ndarray` objects or of
    strings (.png, .npz, etc.) for filenames
        design matrices for the experimental conditions

    contrasts: dict of arrays
       dictionary of contrasts of interest; the keys are the contrast ids,
       the values are contrast values (lists)

    z_maps: dict of 3D image objects or strings (image filenames)
       dict with same keys as 'contrasts'; the values are paths of z-maps
       for the respective contrasts

    anat: 3D array (optional)
        brain image to serve bg unto which activation maps will be plotted;
        passed to viz.plot_map API

    anat_affine: 2D array (optional)
        affine data for the anat

    threshold: float (optional)
        threshold to be applied to activation maps voxel-wise

    cluster_th: int (optional)
        minimal voxel count for clusteres declared as 'activated'

    cmap: cmap object (default viz.cm.cold_hot)
        color-map to use in plotting activation maps

    start_time: string (optional)
        start time for the stats analysis (useful for the generated
        report page)

    user_script_name: string (optional, default None)
        existing filename, path to user script used in doing the analysis

    progress_logger: ProgressLogger object (optional)
        handle for logging progress

    shutdown_all_reloaders: bool (optional, default True)
        if True, all pages connected to the stats report page will
        be prevented from reloading after the stats report page
        has been completely generated

    **glm_kwargs:
        kwargs used to specify the control parameters used to specify the
        experimental paradigm and the GLM

    """
    # Delayed import of nipy for more robustness when it is not present
    from nipy.modalities.fmri.design_matrix import DesignMatrix

    if slicer == "ortho":
        statistical_mapping_trick = False

        if not hasattr(cut_coords, "__iter__"):
            cut_coords = None

    # prepare for stats reporting
    if progress_logger is None:
        progress_logger = base_reporter.ProgressReport()

    output_dir = os.path.dirname(stats_report_filename)
    if not os.path.exists(output_dir):
        os.makedirs(output_dir)

    # copy css and js stuff to output dir
    base_reporter.copy_web_conf_files(output_dir)

    # initialize gallery of design matrices
    design_thumbs = base_reporter.ResultsGallery(
        loader_filename=os.path.join(output_dir, "design.html"))

    # initialize gallery of activation maps
    activation_thumbs = base_reporter.ResultsGallery(
        loader_filename=os.path.join(output_dir, "activation.html"))

    # get caller module handle from stack-frame
    if user_script_name is None:
        user_script_name = sys.argv[0]
    user_source_code = base_reporter.get_module_source_code(user_script_name)

    methods = """
    GLM and Statistical Inference have been done using the <i>%s</i> script, \
powered by <a href="%s">nipy</a>. Statistic images have been thresholded at \
Z>%s voxel-level.
    """ % (user_script_name, base_reporter.NIPY_URL, threshold)

    # report the control parameters used in the paradigm and analysis
    design_params = ""
    glm_kwargs["contrasts"] = contrasts
    if len(glm_kwargs):
        design_params += (
            "The following control parameters were used for  "
            " specifying the experimental paradigm and fitting the "
            "GLM:<br/><ul>")

        design_params += base_reporter.dict_to_html_ul(glm_kwargs)

    if start_time is None:
        start_time = base_reporter.pretty_time()

    if title is None:
        title = "GLM and Statistical Inference"
        if not subject_id is None:
            title += " for subject %s" % subject_id

    level1_html_markup = base_reporter.get_subject_report_stats_html_template(
        title=title,
        start_time=start_time,
        subject_id=subject_id,

        # insert source code stub
        source_script_name=user_script_name,
        source_code=user_source_code,
        design_params=design_params,
        methods=methods,
        threshold=threshold,
        cmap=cmap.name)

    with open(stats_report_filename, 'w') as fd:
        fd.write(str(level1_html_markup))
        fd.close()

    progress_logger.log("<b>Level 1 statistics</b><br/><br/>")

    # create design matrix thumbs
    if not design_matrices is None:
        if not hasattr(design_matrices, '__len__'):
            design_matrices = [design_matrices]

        for design_matrix, j in zip(design_matrices,
                                    xrange(len(design_matrices))):
            # sanitize design_matrix type
            if isinstance(design_matrix, basestring):
                if not isinstance(design_matrix, DesignMatrix):
                    if design_matrix.endswith('.npz'):
                        npz = np.load(design_matrix)
                        design_matrix = DesignMatrix(
                            npz['X'],
                            npz['conditions'],
                        )
                else:
                    # XXX handle case of .png, jpeg design matrix image
                    raise TypeError("Unsupported design matrix type: %s" %
                                    type(design_matrix))
            elif isinstance(design_matrix, np.ndarray) or isinstance(
                    design_matrix, list):
                X = np.array(design_matrix)
                # assert len(X.shape) == 2
                conditions = ['%i' % i for i in xrange(X.shape[-1])]
                design_matrix = DesignMatrix(X, conditions)
            # else:
            #     raise TypeError(
            #         "Unsupported design matrix type '%s'" % type(
            #             design_matrix))

            # plot design_matrix proper
            ax = design_matrix.show(rescale=True)
            ax.set_position([.05, .25, .9, .65])
            dmat_outfile = os.path.join(
                output_dir,
                'design_matrix_%i.png' % (j + 1),
            )
            pl.savefig(dmat_outfile, bbox_inches="tight", dpi=200)
            pl.close()

            thumb = base_reporter.Thumbnail()
            thumb.a = base_reporter.a(href=os.path.basename(dmat_outfile))
            thumb.img = base_reporter.img(
                src=os.path.basename(dmat_outfile),
                height="500px",
            )
            thumb.description = "Design Matrix"
            thumb.description += " %s" % (
                j + 1) if len(design_matrices) > 1 else ""

            # commit activation thumbnail into gallery
            design_thumbs.commit_thumbnails(thumb)

    # make colorbar (place-holder, will be overridden, once we've figured out
    # the correct end points) for activations
    colorbar_outfile = os.path.join(output_dir, 'activation_colorbar.png')
    base_reporter.make_standalone_colorbar(cmap, threshold, 8.,
                                           colorbar_outfile)

    # create activation thumbs
    _vmax = 0
    _vmin = threshold
    for contrast_id, contrast_val in contrasts.iteritems():
        z_map = z_maps[contrast_id]

        # load the map
        if isinstance(z_map, basestring):
            z_map = nibabel.load(z_map)

        # compute vmin and vmax
        vmin, vmax = base_reporter.compute_vmin_vmax(z_map.get_data())

        # update colorbar endpoints
        _vmax = max(_vmax, vmax)
        _vmin = min(_vmin, vmin)

        # sanitize anat
        if not anat is None:
            if anat.ndim == 4:
                assert anat.shape[-1] == 1, (
                    "Expecting 3D array for ant, got shape %s" %
                    str(anat.shape))
                anat = anat[..., 0]
            else:
                assert anat.ndim == 3, (
                    "Expecting 3D array for ant, got shape %s" %
                    str(anat.shape))

        # generate level 1 stats table
        title = "Level 1 stats for %s contrast" % contrast_id
        stats_table = os.path.join(output_dir,
                                   "%s_stats_table.html" % (contrast_id))
        z_clusters = generate_level1_stats_table(
            z_map,
            mask,
            stats_table,
            cluster_th=cluster_th,
            z_threshold=threshold,
            title=title,
        )

        # compute cut_coords
        if statistical_mapping_trick:
            slicer = slicer.lower()
            if slicer in ["x", "y", "z"] and cut_coords is None or isinstance(
                    cut_coords, int):
                axis = 'xyz'.index(slicer)
                if cut_coords is None:
                    cut_coords = min(5, len(z_clusters))
                _cut_coords = [
                    x for zc in z_clusters
                    for x in list(set(zc['maxima'][..., axis]))
                ]
                # # _cut_coords = _maximally_separated_subset(
                # #     _cut_coords, cut_coords)

                # assert len(_cut_coords) == cut_coords
                cut_coords = _cut_coords

        # plot activation proper
        viz.plot_map(z_map.get_data(),
                     z_map.get_affine(),
                     cmap=cmap,
                     anat=anat,
                     anat_affine=anat_affine,
                     threshold=threshold,
                     slicer=slicer,
                     cut_coords=cut_coords,
                     black_bg=True)

        # store activation plot
        z_map_plot = os.path.join(output_dir, "%s_z_map.png" % contrast_id)
        pl.savefig(z_map_plot,
                   dpi=200,
                   bbox_inches='tight',
                   facecolor="k",
                   edgecolor="k")
        pl.close()

        # create thumbnail for activation
        thumbnail = base_reporter.Thumbnail()
        thumbnail.a = base_reporter.a(href=os.path.basename(stats_table))
        thumbnail.img = base_reporter.img(
            src=os.path.basename(z_map_plot),
            height="150px",
        )
        thumbnail.description = contrast_id
        activation_thumbs.commit_thumbnails(thumbnail)

    # make colorbar for activations
    base_reporter.make_standalone_colorbar(cmap, _vmin, _vmax,
                                           colorbar_outfile)

    # we're done, shut down re-loaders
    progress_logger.log('<hr/>')

    # prevent stats report page from reloading henceforth
    progress_logger.finish(stats_report_filename)

    # prevent any related page from reloading
    if shutdown_all_reloaders:
        progress_logger.finish_dir(output_dir)

    # return generated html
    with open(stats_report_filename, 'r') as fd:
        stats_report = fd.read()
        fd.close()

        return stats_report