Welcome to ASAP’s documentation!

README

ASAP-modules

ASAP is a set of modules to perform stitching and alignment of EM and Array tomography data. It is suitable for processing large-scale datasets and supports multiple computational environments.

Installation

Please refer the documentation Installation:Installation. on how to install and use ASAP modules

How to run

The order of processing is as follows;

Other Modules

A few other modules are included in ASAP to do the following.

Materialization - render intermediate/final aligned volume to disk for further processing
Fusion - Fuse global 3D non-linear aligned chunks together to make a complete volume
Point match filter - A module that performs point match filtering of an existing point match collection
Point match optimization - Performs a parameter sweep from a given set of ranges on a random sample of tilepairs to identify the optimal set of parameters
Registration - Register individual sections in an already aligned volume (useful in cases of aligning missing/reimaged sections)

Support

We are planning on occasional updating this tool with no fixed schedule. Community involvement is encouraged through both issues and pull requests. Please make pull requests against the dev branch, as we will test changes there before merging into master.

Acknowledgments

This project is supported by the Intelligence Advanced Research Projects Activity (IARPA) via Department of Interior / Interior Business Center (DoI/IBC) contract number D16PC00004. The U.S. Government is authorized to reproduce and distribute reprints for Governmental purposes notwithstanding any copyright annotation theron.

Disclaimer: The views and conclusions contained herein are those of the authors and should not be interpreted as necessarily representing the official policies or endorsements, either expressed or implied, of IARPA, DoI/IBC, or the U.S. Government.

Installation

Prerequisites

ASAP requires Render web service (https://github.com/saalfeldlab/render) to be installed for storing and processing the data. Please refer to Render for details on its installation.

Installing ASAP-modules

ASAP can be installed using the following commands.

Clone this repository

# git clone this repository
git clone https://github.com/AllenInstitute/asap-modules .

Install from source

CD to the cloned directory and run setup.py

python setup.py install

Docker setup

You can also install asap-modules using the provided docker file

docker build -t asap-modules:latest --target asap-modules .

Running docker

The built docker image can then be run using the following command

docker run --rm asap-modules:latest

Running modules of ASAP

Once ASAP is installed using the above command, you can use all of its functionalities as follows;

python -m asap.<submodule>.<function_to_run> --input_json <input_json_file.json> --output_json <output_json_file.json>

For example, the montage qc module can be run using the following command.

python -m asap.em_montage_qc.detect_montage_defects --input_json <your_input_json_file_with_required_parameters> --output_json <output_json_file_with_full_path>

and here is an example input json file for the detect_montage_defects module

{
    "render":{
        "host": <render_host>,
        "port": <render_port>,
        "owner": <render_project_owner>,
        "project": <render_project_name>,
        "client_scripts": <path_to_render_client_scripts>
    },
    "prestitched_stack": <pre_montage_stack>,
    "poststitched_stack": <montaged_stack>,
    "match_collection_owner": <owner_of_point_match_collection>,
    "match_collection": <name_of_point_match_collection>,
    "out_html_dir": <path_to_directory_to_store_the_qc_plot_html_file>,
    "plot_sections": <True/False>,
    "minZ": <z_index_of_the_first_section_to_run_qc_for>,
    "maxZ": <z_index_of_the_last_section_to_run_qc_for>,
    "neighbors_distance": <qc_parameter>,
    "min_cluster_size": <qc_parameter>,
    "residual_threshold": <qc_parameter>,
    "pool_size": <pool_size_for_parallel_processing>
}

The list of parameters required for each module can be found out using the –help option.

# find the list of parameters for the solver module using its help option
python -m asap.solver.solve --help

Lens distortion correction

The lens distortion correction transforms can be computed using the following modules

Step 1 - Compute lens distortion correction

Compute lens distortion correction transformation

(Assumes that the images for computation are loaded into a render stack. )

python -m asap.mesh_lens_correction.do_mesh_lens_correction --input_json <input_parameter_json_file> --output_json <output_json_file>

An example input json file is provided in the do_mesh_lens_correcton.py file

Step 2 - Apply lens correction

Apply lens correction transformations to the input render stack (update the raw tilespecs)

python -m asap.lens_correction.apply_lens_correction --input_json <input_parameter_json_file> --output_json <output_json_file>

An example input json file is provided in the apply_lens_correction.py file

Generate MIPmaps

MIPmaps are essential for stitching and alignment and is used to generate point matches, used for visualization, etc.

MIPmaps can be generated for a dataset loaded into a render stack.

Step 1 - Generate MIPmaps

python -m asap.dataimport.create_mipmaps --input_json <input_parameter_json_file> --output_json <output_json_file>

Step 2 - Apply MIPmaps to Render stack

python -m asap.dataimport.apply_mipmaps_to_render --input_json <input_parameter_json_file> --output_json <output_json_file>

Example input parameter json files are included in the module’s script files.

2D Stitching

2D stitching of serial sections involves the following process

Step 1 - Create tilepairs

python -m asap.pointmatch.create_tilepairs --input_json <input_parameter_json_file> --output_json <output_json_file>

Step 2 - Generate point matches for the serial section

ASAP utilizes the SIFT point matching module in Render to compute the point matches. There also exists an opencv version of SIFT computation in ASAP.

Point matching implementation from Render to be run on Spark cluster

This requires Spark to be installed in the setup.

python -m asap.pointmatch.generate_point_matches_spark --input_json <input_parameter_json_file> --output_json <output_json_file>

Point matching implementation from Render to be run on PBS cluster

python -m asap.pointmatch.generate_point_matches_qsub --input_json <input_parameter_json_file> --output_json <output_json_file>

Point matching implementation using opencv

python -m asap.pointmatch.generate_point_matches_opencv --input_json <input_parameter_json_file> --output_json <output_json_file>

The point matches will be saved in a point match collection in the Render web service.

Step 3 - Solve for transformations

The bigfeta solver can be invoked from asap to solve for transformations using the following commmand

python -m asap.solver.solve --input_json <input_parameter_json_file> --output_json <output_json_file>

Step 4 - Montage QC

The solver writes the transformations in the tilespecs associated with the serial section in the render stack. Once this is done, the QC module can be run to gather statistics about the quality of the stitching and also visualization plots of the stitched section.

python -m asap.em_montage_qc.detect_montage_defects --input_json <input_parameter_json_file> --output_json <output_json_file>

The QC plots will be saved in the output directory specified in the input_parameter_json_file and the sections with issues will be found in the output_json_file.

Global 3D non-linear alignment

Global 3D non-linear alignment can be performed on a stack in chunks as well as the entire dataset (if all the serial sections are montaged and available). The following steps illustrate the global 3D non-linear alignment process.

Step 1 - Montage scapes generation

Montage scapes are downsampled versions of the serial sections and are used in the global 3D alignment process. Montage scapes can be generated as follows.

# Generate downsampled versions of montaged serial sections
python -m asap.materialize.render_downsample_sections --input_json <input_parameter_json_file> --output_json <output_json_file>

# Create a downsampled montage stack
python -m asap.dataimport.make_montage_scapes_stack --input_json <input_parameter_json_file> --output_json <output_json_file>

Step 2 - Generate tilepairs

3D tilepairs for the downsampled stack can be generated using the following command.

python -m asap.pointmatch.create_tilepairs --input_json <input_parameter_json_file> --output_json <output_json_file>

Step 3 - Generate point matches

3D point matches can be generated using the generated tile pairs. The following command can be used to generate point matches using a Spark cluster

python -m asap.pointmatch.generate_point_matches_using_spark --input_json <input_parameter_json_file> --output_json <output_json_file>

Step 4 - Solve for 3D non-linear transformations

This step in practice is done as a multi-step 3D alignment process, where a series of transformations (rigid, affine, non-linear) are computed and used as initialization for the computation of next higher order transformation.

A mesh based alignment can also be applied as a last step and is available in Bigfeta.

The command to run the solver is shown below.

python -m asap.solver.solve --input_json <input_parameter_json_file> --output_json <output_json_file>

NOTE: Each of the modules’ script include an example input json file for reference and the list of input and output parameters can also be listed using the –help option in each of the above commands.

asap-modules

asap package

Subpackages

asap.dataimport package

Submodules

asap.dataimport.apply_mipmaps_to_render module

class asap.dataimport.apply_mipmaps_to_render.AddMipMapsToStack(schema_type=None, *args, **kwargs)[source]

Bases: asap.module.render_module.StackTransitionModule

Note

This class takes a ArgSchema as an input to parse inputs , with a default schema of type AddMipMapsToStackParameters

default_output_schema: alias of asap.dataimport.schemas.AddMipMapsToStackOutput

default_schema: alias of asap.dataimport.schemas.AddMipMapsToStackParameters

run()[source]

asap.dataimport.apply_mipmaps_to_render.addMipMapsToRender(render, input_stack, mipmap_prefix, imgformat, levels, z)[source]

asap.dataimport.create_mipmaps module

exception asap.dataimport.create_mipmaps.CreateMipMapException[source]

Bases: asap.module.render_module.RenderModuleException

Exception raised when there is a problem creating a mipmap

asap.dataimport.create_mipmaps.create_mipmaps(inputImage, outputDirectory='.', *args, **kwargs): legacy create_mipmaps function

asap.dataimport.create_mipmaps.create_mipmaps_legacy(inputImage, outputDirectory='.', *args, **kwargs)[source]: legacy create_mipmaps function

asap.dataimport.create_mipmaps.create_mipmaps_uri(inputImage, outputDirectory=None, method='block_reduce', mipmaplevels=[1, 2, 3], outputformat='tif', convertTo8bit=True, force_redo=True, **kwargs)[source]

function to create downsampled images from an input image

Parameters

inputImage (str) – path to input image
outputDirectory (str) – path to save output images (default to current directory)
mipmaplevels (list or tuple) – list or tuple of integers (default to (1,2,3))
outputformat (str) – string representation of extension of image format (default tif)
convertTo8bit (boolean) – whether to convert the image to 8 bit, dividing each value by 255
force_redo (boolean) – whether to recreate mip map images if they already exist
method (str) – string corresponding to downsampling method
block_func (str) – string corresponding to function used by block_reduce
ds_filter (str) – string corresponding to PIL downsample mode

Returns

list of output images created in order of levels

Return type

list

Raises

MipMapException – if an image cannot be created for some reason

asap.dataimport.create_mipmaps.mipmap_PIL(im, levels_file_map, ds_filter='NEAREST', force_redo=True, **kwargs)[source]

asap.dataimport.create_mipmaps.mipmap_block_reduce(im, levels_file_map, block_func='mean', force_redo=True, **kwargs)[source]

asap.dataimport.create_mipmaps.writeImage(img, outpath, force_redo)[source]

asap.dataimport.generate_EM_tilespecs_from_metafile module

create tilespecs from TEMCA metadata file

class asap.dataimport.generate_EM_tilespecs_from_metafile.GenerateEMTileSpecsModule(schema_type=None, *args, **kwargs)[source]

Bases: asap.module.render_module.StackOutputModule

Note

This class takes a ArgSchema as an input to parse inputs , with a default schema of type GenerateEMTileSpecsParameters

default_output_schema: alias of asap.dataimport.schemas.GenerateEMTileSpecsOutput

default_schema: alias of asap.dataimport.schemas.GenerateEMTileSpecsParameters

static image_coords_from_stage(stage_coords, resX, resY, rotation)[source]

run()[source]

static sectionId_from_z(z)[source]

tileId_from_basename(fname)[source]

ts_from_imgdata(imgdata, imgprefix, x, y, minint=0, maxint=255, maskUrl=None, width=3840, height=3840, z=None, sectionId=None, scopeId=None, cameraId=None, pixelsize=None)[source]

asap.dataimport.generate_mipmaps module

class asap.dataimport.generate_mipmaps.GenerateMipMaps(schema_type=None, *args, **kwargs)[source]

Bases: asap.module.render_module.StackInputModule

Note

This class takes a ArgSchema as an input to parse inputs , with a default schema of type GenerateMipMapsParameters

default_output_schema: alias of asap.dataimport.schemas.GenerateMipMapsOutput

default_schema: alias of asap.dataimport.schemas.GenerateMipMapsParameters

run()[source]

asap.dataimport.generate_mipmaps.create_mipmap_from_tuple(mipmap_tuple, levels=[1, 2, 3], imgformat='tif', convertTo8bit=True, force_redo=True, **kwargs)[source]

asap.dataimport.generate_mipmaps.create_mipmap_from_tuple_uri(mipmap_tuple, levels=[1, 2, 3], imgformat='tif', convertTo8bit=True, force_redo=True, **kwargs)[source]

asap.dataimport.generate_mipmaps.get_filepath_from_tilespec(ts)[source]

asap.dataimport.generate_mipmaps.make_tilespecs_and_cmds(render, inputStack, output_prefix, zvalues, levels, imgformat, convert_to_8bit, force_redo, pool_size, method)[source]

asap.dataimport.make_montage_scapes_stack module

class asap.dataimport.make_montage_scapes_stack.MakeMontageScapeSectionStack(schema_type=None, *args, **kwargs)[source]

Bases: asap.module.render_module.StackOutputModule

Note

This class takes a ArgSchema as an input to parse inputs , with a default schema of type MakeMontageScapeSectionStackParameters

default_output_schema: alias of asap.dataimport.schemas.MakeMontageScapeSectionStackOutput

default_schema: alias of asap.dataimport.schemas.MakeMontageScapeSectionStackParameters

run()[source]

asap.dataimport.make_montage_scapes_stack.create_montage_scape_tile_specs(render, input_stack, image_directory, scale, project, tagstr, imgformat, Z, apply_scale=False, uuid_prefix=True, uuid_prefix_length=10, **kwargs)[source]

asap.dataimport.schemas module

class asap.dataimport.schemas.AddMipMapsToStackOutput(extra=None, only=None, exclude=(), prefix='', strict=None, many=False, context=None, load_only=(), dump_only=(), partial=False)[source]

AddMipMapsToStackOutput
key	description	default	field_type	json_type
output_stack	no description	(REQUIRED)	`String`	str
missing_ts_zs	Z values for which apply mipmaps failed	[]	`List`	int

AddMipMapsToStackParameters
key	description	default	field_type	json_type
pool_size	no description	1	`Integer`	int
minZ	no description	NA	`Integer`	int
maxZ	no description	NA	`Integer`	int
z	no description	NA	`Integer`	int
zValues	no description	NA	`List`	int
input_json	file path of input json file	NA	`InputFile`	str
output_json	file path to output json file	NA	`OutputFile`	str
log_level	set the logging level of the module	ERROR	`LogLevel`	str
render	parameters to connect to render server	(REQUIRED)	`RenderClientParameters`	dict
input_stack	no description	(REQUIRED)	`String`	str
output_stack	no description	(REQUIRED)	`String`	str
close_stack	no description	False	`Boolean`	bool
overwrite_zlayer	no description	False	`Boolean`	bool
output_stackVersion	no description	NA	`RenderStackVersion`	dict
mipmap_dir	directory to which the mipmaps will be stored	NA	`InputDir`	str
mipmap_prefix	uri prefix from which mipmap locations are built.	(REQUIRED)	`String`	str
levels	number of levels of mipmaps, default is 6	6	`Integer`	int
imgformat	mipmap image format, default is tiff	tiff	`String`	str

GenerateEMTileSpecsParameters
key	description	default	field_type	json_type
pool_size	no description	1	`Integer`	int
minZ	no description	NA	`Integer`	int
maxZ	no description	NA	`Integer`	int
z	no description	NA	`Integer`	int
zValues	no description	NA	`List`	int
input_json	file path of input json file	NA	`InputFile`	str
output_json	file path to output json file	NA	`OutputFile`	str
log_level	set the logging level of the module	ERROR	`LogLevel`	str
render	parameters to connect to render server	(REQUIRED)	`RenderClientParameters`	dict
output_stack	no description	(REQUIRED)	`String`	str
close_stack	no description	False	`Boolean`	bool
overwrite_zlayer	no description	False	`Boolean`	bool
output_stackVersion	no description	NA	`RenderStackVersion`	dict
metafile	metadata file containing TEMCA acquisition data	NA	`InputFile`	str
metafile_uri	uri of metadata containing TEMCA acquisition data	(REQUIRED)	`String`	str
maskUrl	absolute path to image mask to apply	None	`InputFile`	str
maskUrl_uri	uri of image mask to apply	None	`String`	str
image_directory	directory used in determining absolute paths to images. Defaults to parent directory containing metafile if omitted.	NA	`InputDir`	str
image_prefix	prefix used in determining full uris of images in metadata. Defaults to using the / delimited prefix to the metadata_uri if omitted	NA	`String`	str
maximum_intensity	intensity value to interpret as white	255	`Integer`	int
minimum_intensity	intensity value to interpret as black	0	`Integer`	int
sectionId	sectionId to apply to tiles during ingest. If unspecified will default to a string representation of the float value of z_index.	NA	`String`	str

GenerateMipMapsOutput
key	description	default	field_type	json_type
levels	no description	(REQUIRED)	`Integer`	int
output_prefix	no description	(REQUIRED)	`String`	str

Welcome to ASAP’s documentation!

README

ASAP-modules

Installation

How to run

Other Modules

Support

Acknowledgments

Installation

Prerequisites

Installing ASAP-modules

Install from source

Docker setup

Running docker

Running modules of ASAP

Lens distortion correction

Step 1 - Compute lens distortion correction

Step 2 - Apply lens correction

Generate MIPmaps

Step 1 - Generate MIPmaps

Step 2 - Apply MIPmaps to Render stack

2D Stitching

Step 1 - Create tilepairs

Step 2 - Generate point matches for the serial section

Point matching implementation from Render to be run on Spark cluster

Point matching implementation from Render to be run on PBS cluster

Point matching implementation using opencv

Step 3 - Solve for transformations

Step 4 - Montage QC

Global 3D non-linear alignment

Step 1 - Montage scapes generation

Step 2 - Generate tilepairs

Step 3 - Generate point matches

Step 4 - Solve for 3D non-linear transformations

asap-modules

asap package

Subpackages

asap.dataimport package

Submodules

asap.dataimport.apply_mipmaps_to_render module

asap.dataimport.create_mipmaps module

asap.dataimport.generate_EM_tilespecs_from_metafile module

asap.dataimport.generate_mipmaps module

asap.dataimport.make_montage_scapes_stack module

asap.dataimport.schemas module

Module contents

asap.em_montage_qc package

Submodules

asap.em_montage_qc.detect_montage_defects module

asap.em_montage_qc.plots module

asap.em_montage_qc.schemas module

Module contents

asap.intensity_correction package

Submodules

asap.intensity_correction.apply_multiplicative_correction module

asap.intensity_correction.calculate_multiplicative_correction module

asap.intensity_correction.schemas module

Module contents

asap.lens_correction package

Submodules

asap.lens_correction.apply_lens_correction module

asap.lens_correction.lens_correction module

asap.lens_correction.schemas module

Module contents

asap.materialize package

Submodules

asap.materialize.materialize_sections module

asap.materialize.render_downsample_sections module

asap.materialize.schemas module

Module contents

asap.module package

Subpackages

Submodules

asap.module.render_module module

asap.module.template_module module

Module contents

asap.montage package

Submodules

asap.montage.run_montage_job_for_section module

asap.montage.schemas module