We welcome contributions or suggestions from other developers. Please contact us if you have questions or would like to discuss an addition or major modifications to the Giotto main code. The source code for Giotto Suite may be found on our GitHub repository.
The Giotto packages exist at the drieslab repository on GitHub. Some guidelines for pull requests (PRs) are the following:
drieslab/Giotto@suite_devdrieslab/GiottoVisuals@devdrieslab/GiottoClass@devdrieslab/GiottoUtils@devFollowing a particular programming style will help programmers read and understand source code conforming to the style, and help to avoid introducing errors. Here we present a small list of guidelines on what is considered a good practice when writing R code in Giotto package. Most of them are adapted from Bioconductor - coding style or Google’s R Style Guide. These guidelines are preferences and strongly encouraged!
# package installations
BiocManager::install("biocthis")
install.packages("styler")
# styling a file
b_style <- biocthis::bioc_style()
styler::style_file(path = "[???]", transformers = b_style)
# styling the active package (may lead to lots of conflicts)
# generally only run by core devs
styler::style_pkg(transformers = b_style)exported - Core functionality for users to directly use. These should have clear names and documentation
exported utility - Secondary functionalities that are helpful to also have available, but are not directly related to data processing, analysis, and visualization. Examples are dt_to_matrix() or wrap_msg(). Another reason for this type of function is because Giotto is modular and some functions that are not expected to be commonly used by end users also need to be exported so that they are available across the Giotto ecosystem.
internal - Functions that are never intended to be used outside of a module package. These are functions only relevant to the internals of one package, for example .detect_in_dir() from Giotto’s internals which is pretty nondescript and mainly there to help with code organization.
Use camelCase for exported functions. ex: functionName()
Use snake_case for exported utiliity functions. ex: function_name()
Use . prefix AND snake_case for internal functions. ex: .function_name()
Use snake_case for parameter/argument names.
Never use . as a separator in function naming. (in the S3 class system, fun(x) where x is class foo will dispatch to fun.foo())
Most Giotto commands can accept several matrix classes (DelayedMatrix, SparseM, Matrix or base matrix). To facilitate this we provide flexible wrappers that dispatch to our preferred methods for these operations.
mean_flex(): analogous to mean()
rowSums_flex(): analogous to rowSums()
rowMeans_flex(): analogous to rowMeans()
colSums_flex(): analogous to colSums()
colMeans_flex(): analogous to colMeans()
t_flex(): analogous to t()
cor_flex(): analogous to cor()
Giotto has a number of auxiliary or convenience functions that might help you to adapt your code or write new code for Giotto. We encourage you to use these small functions to maintain uniformity throughout the code.
lapply_flex(): analogous to lapply() and works for both windows and unix systems
all_plots_save_function(): compatible with Giotto instructions and helps to automatically save generated plots
plot_output_handler(): further wraps all_plots_save_function and includes handling for return_plot and show_plot and Giotto instructions checking
determine_cores(): determine the number of cores to use if a user does not set this explicitly
get_os(): identify the operating system
update_giotto_params(): will catch and store the parameters for each used command on a giotto object
wrap_txt(), wrap_msg(), etc: text and message formatting functions
vmsg(): framework for Giotto’s verbosity-flagged messages
package_check(): to check if a package exists, works for packages on CRAN, Bioconductor and Github
Should be used within your contribution code if it requires the use of packages not in Giotto’s DESCRIPTION file’s depends imports section.
Has the additional benefit that it will suggest to the user how to download the package if it is not available. To keep the size of Giotto within limits we prefer not to add too many new hard dependencies (packages in Depends or Suggests).
Giotto tracks packages and functions to import in a centralized file. When adding code that requires functions from another package, add the roxygen tags to the package_imports.R file for that Giotto module.
Giotto stores information in different slots, which can be accessed through these getters and setters functions. They can be found in the accessors.R file.
setGiotto(): Sets any Giotto subobject
getCellMetadata(): Gets cell metadata
setCellMetadata(): Sets cell metadata
getFeatureMetadata(): Gets feature metadata
getFeatureMetadata(): Sets feature metadata
getExpression(): To select the expression matrix to use
setExpression(): Sets a new expression matrix to the expression slot
getSpatialLocations(): Get spatial locations to use
setSpatialLocations(): Sets new spatial locations
getDimReduction(): To select the dimension reduction values to use
setDimReduction(): Sets new dimension reduction object
getNearestNetwork(): To select the nearest neighbor network (kNN or sNN) to use
setNearestNetwork(): Sets a new nearest neighbor network (kNN or sNN)
getSpatialNetwork(): To select the spatial network to use
setSpatialNetwork(): Sets a new spatial network
getPolygonInfo(): Gets spatial polygon information
setPolygonInfo(): Set new spatial polygon information
getFeatureInfo(): Gets spatial feature information
setFeatureInfo(): Sets new spatial feature information
getSpatialEnrichment(): Gets spatial enrichment information
setSpatialEnrichment(): Sets new spatial enrichment information
getMultiomics(): Gets multiomics information
setMultiomics(): Sets multiomics information
To use Python code we prefer to create a python wrapper/functions around the python code, which can then be sourced by reticulate. As an example we show the basic principles of how we implemented the Leiden clustering algorithm in Giotto.
python_leiden.py in /inst/python:import igraph as ig
import leidenalg as la
import pandas as pd
import networkx as nx
def python_leiden(df, partition_type, initial_membership=None, weights=None, n_iterations=2, seed=None, resolution_parameter = 1):
# create networkx object
Gx = nx.from_pandas_edgelist(df = df, source = 'from', target = 'to', edge_attr = 'weight')
# get weight attribute
myweights = nx.get_edge_attributes(Gx, 'weight')
....
return(leiden_dfr)
py_leiden_filepath = system.file("python", "python_leiden.py", package = 'Giotto')
reticulate::source_python(file = py_leiden_filepath)doLeidenCLuster() for more detailed information.
pyth_leid_result = python_leiden(
df = network_edge_dt,
partition_type = partition_type,
initial_membership = init_membership,
weights = 'weight',
n_iterations = n_iterations,
seed = seed_number,
resolution_parameter = resolution
)globalVariables() call under globals.R so that it does not get flagged by devtools::check()
To add a new example to the website https://drieslab.github.io/Giotto_website/, please follow these steps:
0. Clone the Giotto_website repository from https://github.com/drieslab/Giotto_website and switch to the “suite” branch.
1. Create a new .Rmd (R markdown) file under the folder “vignettes”.
---
title: "TITLE TO USE"
output:
html_document:
number_sections: true
toc: true
pkgdown:
as_is: true
vignette: >
%\VignetteIndexEntry{TITLE TO USE}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---eval=TRUE for example code. To save time when rendering the website, all chunks should not evaluate the code. Image results should be included via linking or a knitr chunk of this style:```{r, echo=FALSE, out.width="80%", fig.align="center"}
knitr::include_graphics("images/TUTORIAL_FOLDER/#_IMAGE_NAME.png")
```The upper case sections just show which areas should be edited, not that they need to be upper case
3. Create your example. Add the text and code of your tutorial. Please use similar variable names to previous tutorials, we have created a list of common variables and default values in this spreadsheet.
4. Session info Files should have a session info section at the end of the tutorial.
5. Preview the document with knitr. Knit the document to check if the vignette looks how you like, and that it actually knits properly.
Optionally, you can run pkgdown::build_site(), but this may be hard to run locally.
6. Edit the pkgdown.yml file. pkgdown.yml is a file at the repo toplevel and it details how the links are set up for the navbars and documentation in the website.
For most new articles:
.html).7. Push the changes to Github. If you are an outside collaborator, you may need to create a Pull Request. Changes usually take roughly 30 min to build and deploy on the website.