Additively add multiple compensation matrices together for round 2 Rosetta

[alex-l-kong]

Relevant background

Rosetta round 2 is at the stage where it's pretty much ready for review outside of one point Hadeesha brought up.

Users will likely need to iteratively run the first section of the Rosetta round 2 notebook a few times. This is because multiple output_channels may need further compensation, and they may each require a different current_channel. The current Rosetta structure isn't conducive to accomplishing this for two reasons:

• Each compensation matrix (along with each multiplier) gets written to a separate folder. There should only be one folder that holds the compensation matrices (on the other hand, each current_channel/output_channel pair should have its own tiled image folder)
• The user would have to manually combine the desired compensation matrices at the end of section 1 to create the final one.

Design overview

To address this, the folder structure for round 2 will need additional modification, and a utility function to additively combine the desired compensation matrices is required.

A single folder for compensation matrices is needed for Rosetta round 2, rather than one for each current_channel/output_channel pair.

The user should be asked to look inside this compensation matrix folder and set which ones they want to combine. They should also specify the name of this combined Rosetta file. The utility function will then add up the specified compensation matrices and save to the desired file name.

Code mockup

Define an additional variable called compensation_matrix_name in the cell that defines current_channel_name, output_channel_names, etc. folder_path will now just be used to prefix the tiled images folders ('-stitched_with'), so it should be renamed tiled_image_prefix. The check for os.path.exists(folder_path) should also be removed. NOTE: we may want to consider implementing similar logic for round 1 for consistency.

The cell that copies over the final Rosetta matrix should be modified as such:

# define the list of compensation matrices to use
compensation_matrix_names = []

# rename your rosetta matrix and put the path to final file here
final_matrix_name = 'cohort_name_rosetta_matrix_round2.csv'

# combine the desired compensation files and save to the final rosetta matrix file name
rosetta.combine_compensation_files(
    os.path.join(rosetta_testing_dir, cohort_name, folder_name),
    compensation_matrix_names,
    final_matrix_name
)

rosetta_path = os.path.join(rosetta_testing_dir, cohort_name, folder_name, final_matrix_name)

# copy final rosetta matrix to matrix folder
rosetta_matrix_dir = 'C:\\Users\\Customer.ION\\Documents\\rosetta_matrices'
shutil.copyfile(rosetta_path, os.path.join(rosetta_matrix_dir, final_matrix_name))

Documentation will direct the user to look into compensation_matrix_name and specify which Rosetta matrices to combine into final_matrix_name.

rosetta.combine_compensation_files will take the specified matrices, add them together, and save.

Required inputs

Name of the compensation matrix directory for round 2, as well as the list of compensation matrices to combine after they're generated.

Output files

The finalized compensation matrix, an additive aggregation of the specified compensation matrices to combine.

Timeline
Give a rough estimate for how long you think the project will take. In general, it's better to be too conservative rather than too optimistic.

• A couple days
• A week
• Multiple weeks. For large projects, make sure to agree on a plan that isn't just a single monster PR at the end.

Estimated date when a fully implemented version will be ready for review:
04/25

Estimated date when the finalized project will be merged in:
04/26 (into #319).

[alex-l-kong]

@ngreenwald @HPiyadasa let me know if this looks good.

[HPiyadasa]

Looks great! It would also be ok if all the tiled images are in the same folder similar to the compensation matrix

[ngreenwald]

I defer to Hadeesha on this whole PR, since he used it the most.