Plotting rework 3: renaming functions

[casblaauw]

Intro

Since before the preprint went out, I've been unhappy with the plotting functions' organisation. Now that we're revamping the plotting module anyway, I'd like to reorganise them.

Starting caveat: all functions will retain aliases to their old names. No old code will break.

Generally, my guiding principle here is that plotting functions should be organised by what they plot, rather than how they plot it. That is, I'd like to have the region-plotting functions (like bar.region, bar.region_predictions, and new scatter.region) together, so that it's immediately obvious which options you have when you want to plot a region. Similar arguments go for correlations: I shouldn't have to click through every module to find out that pl.heatmap, pl.scatter and pl.violin contain functions that visualize the correlations between data and predictions.

Changes

Reorganised groups proposal:

• pl.qc
  • pl.qc.normalization_weights
  • pl.qc.filter_cutoff (to match pp.filter_regions_on_specificity)
  • pl.qc.sort_and_filter_cutoff (to match pp.sort_and_filter_regions_on_specificity)
• pl.region (or prediction?)
  • pl.region.bar
  • pl.region.scatter
• pl.corr (or correlation?)
  • pl.corr.heatmap_self
  • pl.corr.heatmap
  • pl.corr.scatter
  • pl.corr.violin
• pl.explain
  • pl.explain.contribution_scores (could still be pl.sequence.contribution_scores)
• pl.locus
  • pl.locus.locus_scoring
  • pl.locus.track
• pl.dist
  • pl.dist.histogram (Group with QC? I'm honestly unsure when people use this function.)
• pl.modisco
  • pl.modisco.*
• pl.design
  • pl.design.step_predictions
  • pl.design.step_contribution_scores

Old name	New name
bar.region	region.bar
bar.region_predictions	region.bar
bar.normalization_weights	qc.normalization_weights
hist.distribution	dist.histogram (?)
heatmap.correlations_self	corr.heatmap_self
heatmap.correlations_predictions	corr.heatmap
locus.locus_scoring	unchanged
locus.track	unchanged
scatter.class_density	corr.scatter
scatter.region (new)	region.scatter
scatter.gini_filtering (new)	qc.filter_cutoff
scatter.gini_filtering_class (new)	qc.sort_and_filter_cutoff
violin.correlations	corr.violin
patterns.contribution_scores	explain.contribution_scores
patterns.modisco_*	modisco.*
patterns.enhancer_design_steps_contribution_scores	design.step_contribution_scores
patterns.enhancer_design_steps_predictions	design.step_predictions

tl functions

I've also slightly reorganised the enhancer design functions in tl:

Old name	New name
tl.enhancer_design_in_silico_evolution	{func}tl.design.in_silico_evolution <crested.tl.design.in_silico_evolution>
tl.enhancer_design_motif_insertion	{func}tl.design.motif_insertion <crested.tl.design.motif_insertion>
utils.EnhancerOptimizer	{func}tl.design.EnhancerOptimizer <crested.tl.design.EnhancerOptimizer>
utils.derive_intermediate_sequences	{func}tl.design.derive_intermediate_sequences <crested.tl.design.derive_intermediate_sequences>

FInal changes

This also changes the docs structure, to recursively generate docs for all functions in pp, tl, pl and utils. That means that for any function in those (the large majority), you no longer need to manually add it to the toctree list to get it to show up in the docs. Everything is handled automatically instead. See the contribution guide for more information.

[casblaauw]

I've also cleaned up functions and methods that have long been marked as deprecated:

• The methods of {class}~crested.tl.Crested which were superseded by {mod}~crested.tl functions:
  • get_embeddings -> {func}~crested.tl.extract_layer_embeddings
  • predict -> {func}~crested.tl.predict
  • predict_regions -> {func}~crested.tl.predict
  • predict_sequence -> {func}~crested.tl.predict
  • score_gene_locus -> {func}~crested.tl.score_gene_locus
  • calculate_contribution_scores -> {func}~crested.tl.contribution_scores
  • calculate_contribution_scores_regions -> {func}~crested.tl.contribution_scores
  • calculate_contribution_scores_sequence -> {func}~crested.tl.contribution_scores
  • calculate_contribution_scores_enhancer_design -> {func}~crested.tl.contribution_scores
  • tfmodisco_calculate_and_save_contribution_scores_sequences -> {func}~crested.tl.contribution_scores_specific
  • tfmodisco_calculate_and_save_contribution_scores -> {func}~crested.tl.contribution_scores_specific
  • enhancer_design_motif_implementation -> {func}~crested.tl.design.motif_insertion
  • enhancer_design_in_silico_evolution -> {func}~crested.tl.design.in_silico_evolution
  • _derive_intermediate_sequences -> {func}~crested.tl.design.derive_intermediate_sequences
• Aliases for models that didn't properly reflect their nature:
  • chrombpnet -> {func}~crested.tl.zoo.dilated_cnn
  • chrombpnet_decoupled -> {func}~crested.tl.zoo.dilated_cnn_decoupled
• Superseded or obsolete utility functions:
  • extract_bigwig_values_per_bp -> {func}~crested.utils.read_bigwig_region
  • get_value_from_dataframe -> df.loc[row_name, column_name]