├── .Rbuildignore
├── .gitignore
├── DESCRIPTION
├── IRIS_logo.png
├── LICENSE.md
├── NAMESPACE
├── R
    ├── IRIS.run.R
    ├── RcppExports.R
    ├── utilities.R
    └── visualization.R
├── README.md
├── docs
    ├── IRIS_logo1.png
    ├── _config.yml
    ├── documentation
    │   ├── 01_About.md
    │   ├── 02_installation.md
    │   ├── 03_data.md
    │   ├── 04_IRIS_Example.md
    │   ├── 05_Experiments.md
    │   ├── Example_analysis_prop_slice3.png
    │   ├── Example_analysis_visualizeDomain.png
    │   └── screenshot_zhoulab.png
    ├── index.md
    └── style.css
├── man
    ├── IRIS-class.Rd
    ├── IRIS-package.Rd
    ├── IRIS.visualize.domain.Rd
    ├── IRIS.visualize.eachProp.Rd
    ├── IRIS_Marker_iter.Rd
    ├── IRIS_ref_iter.Rd
    ├── IRIS_spatial.Rd
    ├── IRISfree-class.Rd
    ├── createA.Rd
    ├── createIRISObject.Rd
    ├── createscRef.Rd
    ├── getConcated.Rd
    ├── getMu_and_STR.Rd
    ├── kmeansFunc_Initialize.Rd
    ├── kmeansFunc_Iter.Rd
    ├── sc_QC.Rd
    └── selectInfo.Rd
├── src
    ├── IRIS_ref_iter.cpp
    ├── Makevars
    ├── Makevars.win
    └── RcppExports.cpp
└── vignettes
    ├── .gitignore
    ├── IRISfree-single.html
    ├── SCC_IRIS.html
    ├── SlideseqTestis_IRIS.html
    ├── Stereoseq_IRIS.html
    ├── Vizgen_IRIS.html
    ├── Xenium_IRIS.html
    └── my-vignette.Rmd


/.Rbuildignore:
--------------------------------------------------------------------------------
1 | ^.git$
2 | ^.*\.Rproj$
3 | ^\.Rproj\.user$
4 | ^LICENSE\.md$
5 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | # Retrieved 2017-Oct-12 from https://github.com/github/gitignore/blob/master/R.gitignore
 2 | # Licensed under CC0-1.0 https://github.com/github/gitignore/blob/master/LICENSE
 3 | 
 4 | # History files
 5 | .Rhistory
 6 | .Rapp.history
 7 | 
 8 | # Session Data files
 9 | .RData
10 | 
11 | # Example code in package build process
12 | *-Ex.R
13 | 
14 | # Output files from R CMD build
15 | /*.tar.gz
16 | 
17 | # Output files from R CMD check
18 | /*.Rcheck/
19 | 
20 | # RStudio files
21 | .Rproj.user/
22 | 
23 | # produced vignettes
24 | vignettes/*.html
25 | vignettes/*.pdf
26 | 
27 | # OAuth2 token, see https://github.com/hadley/httr/releases/tag/v0.3
28 | .httr-oauth
29 | 
30 | # knitr and R markdown default cache directories
31 | /*_cache/
32 | /cache/
33 | 
34 | # Temporary files created by R markdown
35 | *.utf8.md
36 | *.knit.md
37 | inst/doc
38 | 


--------------------------------------------------------------------------------
/DESCRIPTION:
--------------------------------------------------------------------------------
 1 | Package: IRIS
 2 | Type: Package
 3 | Title: Integrative and Reference-Informed Spatial Domain Detection for
 4 |         Spatial Transcriptomics.
 5 | Version: 1.0
 6 | Date: 2023-01-15
 7 | Author: Ying Ma
 8 | Maintainer: Ying Ma <yingma@umich.edu>
 9 | Description: Briefly, IRIS is a reference-informed integrative method for detecting spatial domains on multiple tissue slices from spatial transcriptomics with spot-level, single-cell level, or subcellular level resolutions. IRIS builds upon the fact that each spatial domain on the tissue is characterized by a unique composition of cell types and that similar composition is observed for the same spatial domain across different slices of the same tissue 28,29. Consequently, IRIS integrates a reference scRNA-seq data to inform and characterize the cell type composition on the tissue of spatial transcriptomics for accurate and interpretable spatial domain detection. In the process, IRIS accommodates cell type compositional similarity across locations within the same slice and across different slices on the same domain to borrow information both within and between tissue slices for integrative and accurate spatial domain detection. Importantly, IRIS comes with an efficient optimization framework with multiple algebraic innovations for scalable computation and can easily handle multiple spatial transcriptomics datasets with millions of spatial locations and tens of thousands of genes. IRIS is implemented as an open-source R package, freely available at www.xzlab.org/software.html.
10 | License: GPL (>= 3)
11 | Encoding: UTF-8
12 | RoxygenNote: 7.2.3
13 | Imports: Rcpp (>= 1.0.9), RcppArmadillo, SingleCellExperiment,
14 |         SummarizedExperiment, methods, Matrix, MCMCpack, fields,
15 |         wrMisc, RANN, stats, ggplot2, grDevices, reshape2, rliger
16 | LinkingTo: Rcpp, RcppArmadillo
17 | Suggests: knitr, rmarkdown
18 | VignetteBuilder: knitr
19 | NeedsCompilation: yes
20 | Packaged: 2024-01-09 17:12:19 UTC; yingma
21 | 


--------------------------------------------------------------------------------
/IRIS_logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/YingMa0107/IRIS/79285560385a63fd3094251cfe7306ccf8389107/IRIS_logo.png


--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
  1 | GNU General Public License
  2 | ==========================
  3 | 
  4 | _Version 3, 29 June 2007_  
  5 | _Copyright © 2007 Free Software Foundation, Inc. &lt;<http://fsf.org/>&gt;_
  6 | 
  7 | Everyone is permitted to copy and distribute verbatim copies of this license
  8 | document, but changing it is not allowed.
  9 | 
 10 | ## Preamble
 11 | 
 12 | The GNU General Public License is a free, copyleft license for software and other
 13 | kinds of works.
 14 | 
 15 | The licenses for most software and other practical works are designed to take away
 16 | your freedom to share and change the works. By contrast, the GNU General Public
 17 | License is intended to guarantee your freedom to share and change all versions of a
 18 | program--to make sure it remains free software for all its users. We, the Free
 19 | Software Foundation, use the GNU General Public License for most of our software; it
 20 | applies also to any other work released this way by its authors. You can apply it to
 21 | your programs, too.
 22 | 
 23 | When we speak of free software, we are referring to freedom, not price. Our General
 24 | Public Licenses are designed to make sure that you have the freedom to distribute
 25 | copies of free software (and charge for them if you wish), that you receive source
 26 | code or can get it if you want it, that you can change the software or use pieces of
 27 | it in new free programs, and that you know you can do these things.
 28 | 
 29 | To protect your rights, we need to prevent others from denying you these rights or
 30 | asking you to surrender the rights. Therefore, you have certain responsibilities if
 31 | you distribute copies of the software, or if you modify it: responsibilities to
 32 | respect the freedom of others.
 33 | 
 34 | For example, if you distribute copies of such a program, whether gratis or for a fee,
 35 | you must pass on to the recipients the same freedoms that you received. You must make
 36 | sure that they, too, receive or can get the source code. And you must show them these
 37 | terms so they know their rights.
 38 | 
 39 | Developers that use the GNU GPL protect your rights with two steps: **(1)** assert
 40 | copyright on the software, and **(2)** offer you this License giving you legal permission
 41 | to copy, distribute and/or modify it.
 42 | 
 43 | For the developers' and authors' protection, the GPL clearly explains that there is
 44 | no warranty for this free software. For both users' and authors' sake, the GPL
 45 | requires that modified versions be marked as changed, so that their problems will not
 46 | be attributed erroneously to authors of previous versions.
 47 | 
 48 | Some devices are designed to deny users access to install or run modified versions of
 49 | the software inside them, although the manufacturer can do so. This is fundamentally
 50 | incompatible with the aim of protecting users' freedom to change the software. The
 51 | systematic pattern of such abuse occurs in the area of products for individuals to
 52 | use, which is precisely where it is most unacceptable. Therefore, we have designed
 53 | this version of the GPL to prohibit the practice for those products. If such problems
 54 | arise substantially in other domains, we stand ready to extend this provision to
 55 | those domains in future versions of the GPL, as needed to protect the freedom of
 56 | users.
 57 | 
 58 | Finally, every program is threatened constantly by software patents. States should
 59 | not allow patents to restrict development and use of software on general-purpose
 60 | computers, but in those that do, we wish to avoid the special danger that patents
 61 | applied to a free program could make it effectively proprietary. To prevent this, the
 62 | GPL assures that patents cannot be used to render the program non-free.
 63 | 
 64 | The precise terms and conditions for copying, distribution and modification follow.
 65 | 
 66 | ## TERMS AND CONDITIONS
 67 | 
 68 | ### 0. Definitions
 69 | 
 70 | “This License” refers to version 3 of the GNU General Public License.
 71 | 
 72 | “Copyright” also means copyright-like laws that apply to other kinds of
 73 | works, such as semiconductor masks.
 74 | 
 75 | “The Program” refers to any copyrightable work licensed under this
 76 | License. Each licensee is addressed as “you”. “Licensees” and
 77 | “recipients” may be individuals or organizations.
 78 | 
 79 | To “modify” a work means to copy from or adapt all or part of the work in
 80 | a fashion requiring copyright permission, other than the making of an exact copy. The
 81 | resulting work is called a “modified version” of the earlier work or a
 82 | work “based on” the earlier work.
 83 | 
 84 | A “covered work” means either the unmodified Program or a work based on
 85 | the Program.
 86 | 
 87 | To “propagate” a work means to do anything with it that, without
 88 | permission, would make you directly or secondarily liable for infringement under
 89 | applicable copyright law, except executing it on a computer or modifying a private
 90 | copy. Propagation includes copying, distribution (with or without modification),
 91 | making available to the public, and in some countries other activities as well.
 92 | 
 93 | To “convey” a work means any kind of propagation that enables other
 94 | parties to make or receive copies. Mere interaction with a user through a computer
 95 | network, with no transfer of a copy, is not conveying.
 96 | 
 97 | An interactive user interface displays “Appropriate Legal Notices” to the
 98 | extent that it includes a convenient and prominently visible feature that **(1)**
 99 | displays an appropriate copyright notice, and **(2)** tells the user that there is no
100 | warranty for the work (except to the extent that warranties are provided), that
101 | licensees may convey the work under this License, and how to view a copy of this
102 | License. If the interface presents a list of user commands or options, such as a
103 | menu, a prominent item in the list meets this criterion.
104 | 
105 | ### 1. Source Code
106 | 
107 | The “source code” for a work means the preferred form of the work for
108 | making modifications to it. “Object code” means any non-source form of a
109 | work.
110 | 
111 | A “Standard Interface” means an interface that either is an official
112 | standard defined by a recognized standards body, or, in the case of interfaces
113 | specified for a particular programming language, one that is widely used among
114 | developers working in that language.
115 | 
116 | The “System Libraries” of an executable work include anything, other than
117 | the work as a whole, that **(a)** is included in the normal form of packaging a Major
118 | Component, but which is not part of that Major Component, and **(b)** serves only to
119 | enable use of the work with that Major Component, or to implement a Standard
120 | Interface for which an implementation is available to the public in source code form.
121 | A “Major Component”, in this context, means a major essential component
122 | (kernel, window system, and so on) of the specific operating system (if any) on which
123 | the executable work runs, or a compiler used to produce the work, or an object code
124 | interpreter used to run it.
125 | 
126 | The “Corresponding Source” for a work in object code form means all the
127 | source code needed to generate, install, and (for an executable work) run the object
128 | code and to modify the work, including scripts to control those activities. However,
129 | it does not include the work's System Libraries, or general-purpose tools or
130 | generally available free programs which are used unmodified in performing those
131 | activities but which are not part of the work. For example, Corresponding Source
132 | includes interface definition files associated with source files for the work, and
133 | the source code for shared libraries and dynamically linked subprograms that the work
134 | is specifically designed to require, such as by intimate data communication or
135 | control flow between those subprograms and other parts of the work.
136 | 
137 | The Corresponding Source need not include anything that users can regenerate
138 | automatically from other parts of the Corresponding Source.
139 | 
140 | The Corresponding Source for a work in source code form is that same work.
141 | 
142 | ### 2. Basic Permissions
143 | 
144 | All rights granted under this License are granted for the term of copyright on the
145 | Program, and are irrevocable provided the stated conditions are met. This License
146 | explicitly affirms your unlimited permission to run the unmodified Program. The
147 | output from running a covered work is covered by this License only if the output,
148 | given its content, constitutes a covered work. This License acknowledges your rights
149 | of fair use or other equivalent, as provided by copyright law.
150 | 
151 | You may make, run and propagate covered works that you do not convey, without
152 | conditions so long as your license otherwise remains in force. You may convey covered
153 | works to others for the sole purpose of having them make modifications exclusively
154 | for you, or provide you with facilities for running those works, provided that you
155 | comply with the terms of this License in conveying all material for which you do not
156 | control copyright. Those thus making or running the covered works for you must do so
157 | exclusively on your behalf, under your direction and control, on terms that prohibit
158 | them from making any copies of your copyrighted material outside their relationship
159 | with you.
160 | 
161 | Conveying under any other circumstances is permitted solely under the conditions
162 | stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
163 | 
164 | ### 3. Protecting Users' Legal Rights From Anti-Circumvention Law
165 | 
166 | No covered work shall be deemed part of an effective technological measure under any
167 | applicable law fulfilling obligations under article 11 of the WIPO copyright treaty
168 | adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention
169 | of such measures.
170 | 
171 | When you convey a covered work, you waive any legal power to forbid circumvention of
172 | technological measures to the extent such circumvention is effected by exercising
173 | rights under this License with respect to the covered work, and you disclaim any
174 | intention to limit operation or modification of the work as a means of enforcing,
175 | against the work's users, your or third parties' legal rights to forbid circumvention
176 | of technological measures.
177 | 
178 | ### 4. Conveying Verbatim Copies
179 | 
180 | You may convey verbatim copies of the Program's source code as you receive it, in any
181 | medium, provided that you conspicuously and appropriately publish on each copy an
182 | appropriate copyright notice; keep intact all notices stating that this License and
183 | any non-permissive terms added in accord with section 7 apply to the code; keep
184 | intact all notices of the absence of any warranty; and give all recipients a copy of
185 | this License along with the Program.
186 | 
187 | You may charge any price or no price for each copy that you convey, and you may offer
188 | support or warranty protection for a fee.
189 | 
190 | ### 5. Conveying Modified Source Versions
191 | 
192 | You may convey a work based on the Program, or the modifications to produce it from
193 | the Program, in the form of source code under the terms of section 4, provided that
194 | you also meet all of these conditions:
195 | 
196 | * **a)** The work must carry prominent notices stating that you modified it, and giving a
197 | relevant date.
198 | * **b)** The work must carry prominent notices stating that it is released under this
199 | License and any conditions added under section 7. This requirement modifies the
200 | requirement in section 4 to “keep intact all notices”.
201 | * **c)** You must license the entire work, as a whole, under this License to anyone who
202 | comes into possession of a copy. This License will therefore apply, along with any
203 | applicable section 7 additional terms, to the whole of the work, and all its parts,
204 | regardless of how they are packaged. This License gives no permission to license the
205 | work in any other way, but it does not invalidate such permission if you have
206 | separately received it.
207 | * **d)** If the work has interactive user interfaces, each must display Appropriate Legal
208 | Notices; however, if the Program has interactive interfaces that do not display
209 | Appropriate Legal Notices, your work need not make them do so.
210 | 
211 | A compilation of a covered work with other separate and independent works, which are
212 | not by their nature extensions of the covered work, and which are not combined with
213 | it such as to form a larger program, in or on a volume of a storage or distribution
214 | medium, is called an “aggregate” if the compilation and its resulting
215 | copyright are not used to limit the access or legal rights of the compilation's users
216 | beyond what the individual works permit. Inclusion of a covered work in an aggregate
217 | does not cause this License to apply to the other parts of the aggregate.
218 | 
219 | ### 6. Conveying Non-Source Forms
220 | 
221 | You may convey a covered work in object code form under the terms of sections 4 and
222 | 5, provided that you also convey the machine-readable Corresponding Source under the
223 | terms of this License, in one of these ways:
224 | 
225 | * **a)** Convey the object code in, or embodied in, a physical product (including a
226 | physical distribution medium), accompanied by the Corresponding Source fixed on a
227 | durable physical medium customarily used for software interchange.
228 | * **b)** Convey the object code in, or embodied in, a physical product (including a
229 | physical distribution medium), accompanied by a written offer, valid for at least
230 | three years and valid for as long as you offer spare parts or customer support for
231 | that product model, to give anyone who possesses the object code either **(1)** a copy of
232 | the Corresponding Source for all the software in the product that is covered by this
233 | License, on a durable physical medium customarily used for software interchange, for
234 | a price no more than your reasonable cost of physically performing this conveying of
235 | source, or **(2)** access to copy the Corresponding Source from a network server at no
236 | charge.
237 | * **c)** Convey individual copies of the object code with a copy of the written offer to
238 | provide the Corresponding Source. This alternative is allowed only occasionally and
239 | noncommercially, and only if you received the object code with such an offer, in
240 | accord with subsection 6b.
241 | * **d)** Convey the object code by offering access from a designated place (gratis or for
242 | a charge), and offer equivalent access to the Corresponding Source in the same way
243 | through the same place at no further charge. You need not require recipients to copy
244 | the Corresponding Source along with the object code. If the place to copy the object
245 | code is a network server, the Corresponding Source may be on a different server
246 | (operated by you or a third party) that supports equivalent copying facilities,
247 | provided you maintain clear directions next to the object code saying where to find
248 | the Corresponding Source. Regardless of what server hosts the Corresponding Source,
249 | you remain obligated to ensure that it is available for as long as needed to satisfy
250 | these requirements.
251 | * **e)** Convey the object code using peer-to-peer transmission, provided you inform
252 | other peers where the object code and Corresponding Source of the work are being
253 | offered to the general public at no charge under subsection 6d.
254 | 
255 | A separable portion of the object code, whose source code is excluded from the
256 | Corresponding Source as a System Library, need not be included in conveying the
257 | object code work.
258 | 
259 | A “User Product” is either **(1)** a “consumer product”, which
260 | means any tangible personal property which is normally used for personal, family, or
261 | household purposes, or **(2)** anything designed or sold for incorporation into a
262 | dwelling. In determining whether a product is a consumer product, doubtful cases
263 | shall be resolved in favor of coverage. For a particular product received by a
264 | particular user, “normally used” refers to a typical or common use of
265 | that class of product, regardless of the status of the particular user or of the way
266 | in which the particular user actually uses, or expects or is expected to use, the
267 | product. A product is a consumer product regardless of whether the product has
268 | substantial commercial, industrial or non-consumer uses, unless such uses represent
269 | the only significant mode of use of the product.
270 | 
271 | “Installation Information” for a User Product means any methods,
272 | procedures, authorization keys, or other information required to install and execute
273 | modified versions of a covered work in that User Product from a modified version of
274 | its Corresponding Source. The information must suffice to ensure that the continued
275 | functioning of the modified object code is in no case prevented or interfered with
276 | solely because modification has been made.
277 | 
278 | If you convey an object code work under this section in, or with, or specifically for
279 | use in, a User Product, and the conveying occurs as part of a transaction in which
280 | the right of possession and use of the User Product is transferred to the recipient
281 | in perpetuity or for a fixed term (regardless of how the transaction is
282 | characterized), the Corresponding Source conveyed under this section must be
283 | accompanied by the Installation Information. But this requirement does not apply if
284 | neither you nor any third party retains the ability to install modified object code
285 | on the User Product (for example, the work has been installed in ROM).
286 | 
287 | The requirement to provide Installation Information does not include a requirement to
288 | continue to provide support service, warranty, or updates for a work that has been
289 | modified or installed by the recipient, or for the User Product in which it has been
290 | modified or installed. Access to a network may be denied when the modification itself
291 | materially and adversely affects the operation of the network or violates the rules
292 | and protocols for communication across the network.
293 | 
294 | Corresponding Source conveyed, and Installation Information provided, in accord with
295 | this section must be in a format that is publicly documented (and with an
296 | implementation available to the public in source code form), and must require no
297 | special password or key for unpacking, reading or copying.
298 | 
299 | ### 7. Additional Terms
300 | 
301 | “Additional permissions” are terms that supplement the terms of this
302 | License by making exceptions from one or more of its conditions. Additional
303 | permissions that are applicable to the entire Program shall be treated as though they
304 | were included in this License, to the extent that they are valid under applicable
305 | law. If additional permissions apply only to part of the Program, that part may be
306 | used separately under those permissions, but the entire Program remains governed by
307 | this License without regard to the additional permissions.
308 | 
309 | When you convey a copy of a covered work, you may at your option remove any
310 | additional permissions from that copy, or from any part of it. (Additional
311 | permissions may be written to require their own removal in certain cases when you
312 | modify the work.) You may place additional permissions on material, added by you to a
313 | covered work, for which you have or can give appropriate copyright permission.
314 | 
315 | Notwithstanding any other provision of this License, for material you add to a
316 | covered work, you may (if authorized by the copyright holders of that material)
317 | supplement the terms of this License with terms:
318 | 
319 | * **a)** Disclaiming warranty or limiting liability differently from the terms of
320 | sections 15 and 16 of this License; or
321 | * **b)** Requiring preservation of specified reasonable legal notices or author
322 | attributions in that material or in the Appropriate Legal Notices displayed by works
323 | containing it; or
324 | * **c)** Prohibiting misrepresentation of the origin of that material, or requiring that
325 | modified versions of such material be marked in reasonable ways as different from the
326 | original version; or
327 | * **d)** Limiting the use for publicity purposes of names of licensors or authors of the
328 | material; or
329 | * **e)** Declining to grant rights under trademark law for use of some trade names,
330 | trademarks, or service marks; or
331 | * **f)** Requiring indemnification of licensors and authors of that material by anyone
332 | who conveys the material (or modified versions of it) with contractual assumptions of
333 | liability to the recipient, for any liability that these contractual assumptions
334 | directly impose on those licensors and authors.
335 | 
336 | All other non-permissive additional terms are considered “further
337 | restrictions” within the meaning of section 10. If the Program as you received
338 | it, or any part of it, contains a notice stating that it is governed by this License
339 | along with a term that is a further restriction, you may remove that term. If a
340 | license document contains a further restriction but permits relicensing or conveying
341 | under this License, you may add to a covered work material governed by the terms of
342 | that license document, provided that the further restriction does not survive such
343 | relicensing or conveying.
344 | 
345 | If you add terms to a covered work in accord with this section, you must place, in
346 | the relevant source files, a statement of the additional terms that apply to those
347 | files, or a notice indicating where to find the applicable terms.
348 | 
349 | Additional terms, permissive or non-permissive, may be stated in the form of a
350 | separately written license, or stated as exceptions; the above requirements apply
351 | either way.
352 | 
353 | ### 8. Termination
354 | 
355 | You may not propagate or modify a covered work except as expressly provided under
356 | this License. Any attempt otherwise to propagate or modify it is void, and will
357 | automatically terminate your rights under this License (including any patent licenses
358 | granted under the third paragraph of section 11).
359 | 
360 | However, if you cease all violation of this License, then your license from a
361 | particular copyright holder is reinstated **(a)** provisionally, unless and until the
362 | copyright holder explicitly and finally terminates your license, and **(b)** permanently,
363 | if the copyright holder fails to notify you of the violation by some reasonable means
364 | prior to 60 days after the cessation.
365 | 
366 | Moreover, your license from a particular copyright holder is reinstated permanently
367 | if the copyright holder notifies you of the violation by some reasonable means, this
368 | is the first time you have received notice of violation of this License (for any
369 | work) from that copyright holder, and you cure the violation prior to 30 days after
370 | your receipt of the notice.
371 | 
372 | Termination of your rights under this section does not terminate the licenses of
373 | parties who have received copies or rights from you under this License. If your
374 | rights have been terminated and not permanently reinstated, you do not qualify to
375 | receive new licenses for the same material under section 10.
376 | 
377 | ### 9. Acceptance Not Required for Having Copies
378 | 
379 | You are not required to accept this License in order to receive or run a copy of the
380 | Program. Ancillary propagation of a covered work occurring solely as a consequence of
381 | using peer-to-peer transmission to receive a copy likewise does not require
382 | acceptance. However, nothing other than this License grants you permission to
383 | propagate or modify any covered work. These actions infringe copyright if you do not
384 | accept this License. Therefore, by modifying or propagating a covered work, you
385 | indicate your acceptance of this License to do so.
386 | 
387 | ### 10. Automatic Licensing of Downstream Recipients
388 | 
389 | Each time you convey a covered work, the recipient automatically receives a license
390 | from the original licensors, to run, modify and propagate that work, subject to this
391 | License. You are not responsible for enforcing compliance by third parties with this
392 | License.
393 | 
394 | An “entity transaction” is a transaction transferring control of an
395 | organization, or substantially all assets of one, or subdividing an organization, or
396 | merging organizations. If propagation of a covered work results from an entity
397 | transaction, each party to that transaction who receives a copy of the work also
398 | receives whatever licenses to the work the party's predecessor in interest had or
399 | could give under the previous paragraph, plus a right to possession of the
400 | Corresponding Source of the work from the predecessor in interest, if the predecessor
401 | has it or can get it with reasonable efforts.
402 | 
403 | You may not impose any further restrictions on the exercise of the rights granted or
404 | affirmed under this License. For example, you may not impose a license fee, royalty,
405 | or other charge for exercise of rights granted under this License, and you may not
406 | initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging
407 | that any patent claim is infringed by making, using, selling, offering for sale, or
408 | importing the Program or any portion of it.
409 | 
410 | ### 11. Patents
411 | 
412 | A “contributor” is a copyright holder who authorizes use under this
413 | License of the Program or a work on which the Program is based. The work thus
414 | licensed is called the contributor's “contributor version”.
415 | 
416 | A contributor's “essential patent claims” are all patent claims owned or
417 | controlled by the contributor, whether already acquired or hereafter acquired, that
418 | would be infringed by some manner, permitted by this License, of making, using, or
419 | selling its contributor version, but do not include claims that would be infringed
420 | only as a consequence of further modification of the contributor version. For
421 | purposes of this definition, “control” includes the right to grant patent
422 | sublicenses in a manner consistent with the requirements of this License.
423 | 
424 | Each contributor grants you a non-exclusive, worldwide, royalty-free patent license
425 | under the contributor's essential patent claims, to make, use, sell, offer for sale,
426 | import and otherwise run, modify and propagate the contents of its contributor
427 | version.
428 | 
429 | In the following three paragraphs, a “patent license” is any express
430 | agreement or commitment, however denominated, not to enforce a patent (such as an
431 | express permission to practice a patent or covenant not to sue for patent
432 | infringement). To “grant” such a patent license to a party means to make
433 | such an agreement or commitment not to enforce a patent against the party.
434 | 
435 | If you convey a covered work, knowingly relying on a patent license, and the
436 | Corresponding Source of the work is not available for anyone to copy, free of charge
437 | and under the terms of this License, through a publicly available network server or
438 | other readily accessible means, then you must either **(1)** cause the Corresponding
439 | Source to be so available, or **(2)** arrange to deprive yourself of the benefit of the
440 | patent license for this particular work, or **(3)** arrange, in a manner consistent with
441 | the requirements of this License, to extend the patent license to downstream
442 | recipients. “Knowingly relying” means you have actual knowledge that, but
443 | for the patent license, your conveying the covered work in a country, or your
444 | recipient's use of the covered work in a country, would infringe one or more
445 | identifiable patents in that country that you have reason to believe are valid.
446 | 
447 | If, pursuant to or in connection with a single transaction or arrangement, you
448 | convey, or propagate by procuring conveyance of, a covered work, and grant a patent
449 | license to some of the parties receiving the covered work authorizing them to use,
450 | propagate, modify or convey a specific copy of the covered work, then the patent
451 | license you grant is automatically extended to all recipients of the covered work and
452 | works based on it.
453 | 
454 | A patent license is “discriminatory” if it does not include within the
455 | scope of its coverage, prohibits the exercise of, or is conditioned on the
456 | non-exercise of one or more of the rights that are specifically granted under this
457 | License. You may not convey a covered work if you are a party to an arrangement with
458 | a third party that is in the business of distributing software, under which you make
459 | payment to the third party based on the extent of your activity of conveying the
460 | work, and under which the third party grants, to any of the parties who would receive
461 | the covered work from you, a discriminatory patent license **(a)** in connection with
462 | copies of the covered work conveyed by you (or copies made from those copies), or **(b)**
463 | primarily for and in connection with specific products or compilations that contain
464 | the covered work, unless you entered into that arrangement, or that patent license
465 | was granted, prior to 28 March 2007.
466 | 
467 | Nothing in this License shall be construed as excluding or limiting any implied
468 | license or other defenses to infringement that may otherwise be available to you
469 | under applicable patent law.
470 | 
471 | ### 12. No Surrender of Others' Freedom
472 | 
473 | If conditions are imposed on you (whether by court order, agreement or otherwise)
474 | that contradict the conditions of this License, they do not excuse you from the
475 | conditions of this License. If you cannot convey a covered work so as to satisfy
476 | simultaneously your obligations under this License and any other pertinent
477 | obligations, then as a consequence you may not convey it at all. For example, if you
478 | agree to terms that obligate you to collect a royalty for further conveying from
479 | those to whom you convey the Program, the only way you could satisfy both those terms
480 | and this License would be to refrain entirely from conveying the Program.
481 | 
482 | ### 13. Use with the GNU Affero General Public License
483 | 
484 | Notwithstanding any other provision of this License, you have permission to link or
485 | combine any covered work with a work licensed under version 3 of the GNU Affero
486 | General Public License into a single combined work, and to convey the resulting work.
487 | The terms of this License will continue to apply to the part which is the covered
488 | work, but the special requirements of the GNU Affero General Public License, section
489 | 13, concerning interaction through a network will apply to the combination as such.
490 | 
491 | ### 14. Revised Versions of this License
492 | 
493 | The Free Software Foundation may publish revised and/or new versions of the GNU
494 | General Public License from time to time. Such new versions will be similar in spirit
495 | to the present version, but may differ in detail to address new problems or concerns.
496 | 
497 | Each version is given a distinguishing version number. If the Program specifies that
498 | a certain numbered version of the GNU General Public License “or any later
499 | version” applies to it, you have the option of following the terms and
500 | conditions either of that numbered version or of any later version published by the
501 | Free Software Foundation. If the Program does not specify a version number of the GNU
502 | General Public License, you may choose any version ever published by the Free
503 | Software Foundation.
504 | 
505 | If the Program specifies that a proxy can decide which future versions of the GNU
506 | General Public License can be used, that proxy's public statement of acceptance of a
507 | version permanently authorizes you to choose that version for the Program.
508 | 
509 | Later license versions may give you additional or different permissions. However, no
510 | additional obligations are imposed on any author or copyright holder as a result of
511 | your choosing to follow a later version.
512 | 
513 | ### 15. Disclaimer of Warranty
514 | 
515 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
516 | EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
517 | PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
518 | EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
519 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
520 | QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
521 | DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
522 | 
523 | ### 16. Limitation of Liability
524 | 
525 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
526 | COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS
527 | PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
528 | INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
529 | PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE
530 | OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
531 | WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
532 | POSSIBILITY OF SUCH DAMAGES.
533 | 
534 | ### 17. Interpretation of Sections 15 and 16
535 | 
536 | If the disclaimer of warranty and limitation of liability provided above cannot be
537 | given local legal effect according to their terms, reviewing courts shall apply local
538 | law that most closely approximates an absolute waiver of all civil liability in
539 | connection with the Program, unless a warranty or assumption of liability accompanies
540 | a copy of the Program in return for a fee.
541 | 
542 | _END OF TERMS AND CONDITIONS_
543 | 
544 | ## How to Apply These Terms to Your New Programs
545 | 
546 | If you develop a new program, and you want it to be of the greatest possible use to
547 | the public, the best way to achieve this is to make it free software which everyone
548 | can redistribute and change under these terms.
549 | 
550 | To do so, attach the following notices to the program. It is safest to attach them
551 | to the start of each source file to most effectively state the exclusion of warranty;
552 | and each file should have at least the “copyright” line and a pointer to
553 | where the full notice is found.
554 | 
555 |     <one line to give the program's name and a brief idea of what it does.>
556 |     Copyright (C) <year>  <name of author>
557 | 
558 |     This program is free software: you can redistribute it and/or modify
559 |     it under the terms of the GNU General Public License as published by
560 |     the Free Software Foundation, either version 3 of the License, or
561 |     (at your option) any later version.
562 | 
563 |     This program is distributed in the hope that it will be useful,
564 |     but WITHOUT ANY WARRANTY; without even the implied warranty of
565 |     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
566 |     GNU General Public License for more details.
567 | 
568 |     You should have received a copy of the GNU General Public License
569 |     along with this program.  If not, see <http://www.gnu.org/licenses/>.
570 | 
571 | Also add information on how to contact you by electronic and paper mail.
572 | 
573 | If the program does terminal interaction, make it output a short notice like this
574 | when it starts in an interactive mode:
575 | 
576 |     <program>  Copyright (C) <year>  <name of author>
577 |     This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
578 |     This is free software, and you are welcome to redistribute it
579 |     under certain conditions; type 'show c' for details.
580 | 
581 | The hypothetical commands `show w` and `show c` should show the appropriate parts of
582 | the General Public License. Of course, your program's commands might be different;
583 | for a GUI interface, you would use an “about box”.
584 | 
585 | You should also get your employer (if you work as a programmer) or school, if any, to
586 | sign a “copyright disclaimer” for the program, if necessary. For more
587 | information on this, and how to apply and follow the GNU GPL, see
588 | &lt;<http://www.gnu.org/licenses/>&gt;.
589 | 
590 | The GNU General Public License does not permit incorporating your program into
591 | proprietary programs. If your program is a subroutine library, you may consider it
592 | more useful to permit linking proprietary applications with the library. If this is
593 | what you want to do, use the GNU Lesser General Public License instead of this
594 | License. But first, please read
595 | &lt;<http://www.gnu.org/philosophy/why-not-lgpl.html>&gt;.
596 | 


--------------------------------------------------------------------------------
/NAMESPACE:
--------------------------------------------------------------------------------
 1 | useDynLib(IRIS)
 2 | import(methods)
 3 | import(Matrix)
 4 | import(ggplot2)
 5 | import(RcppArmadillo)
 6 | import(rliger)
 7 | importFrom(Rcpp, evalCpp)
 8 | importFrom(Rcpp, sourceCpp)
 9 | importFrom(SingleCellExperiment, SingleCellExperiment)
10 | importFrom(SummarizedExperiment, assays)
11 | importFrom(SummarizedExperiment, colData)
12 | importFrom(SummarizedExperiment, rowData)
13 | importFrom(MCMCpack, rdirichlet)
14 | importFrom(fields, rdist)
15 | importFrom(wrMisc, rowGrpMeans)
16 | importFrom(stats, quantile)
17 | importFrom(stats, kmeans)
18 | importFrom(stats, aggregate)
19 | importFrom(stats, var)
20 | importFrom(stats, reshape)
21 | importFrom(RANN, nn2)
22 | importFrom(reshape2, melt)
23 | importFrom(grDevices, colorRampPalette)
24 | ## export all regularly named functions
25 | ## (but allow for private functions whose name starts with a dot).name <- function(...)
26 | exportPattern("^[[:alpha:]]+")
27 | 


--------------------------------------------------------------------------------
/R/IRIS.run.R:
--------------------------------------------------------------------------------
  1 | ####################################################################################################
  2 | ## Package : IRIS
  3 | ## Version : 1.0.1
  4 | ## Date    : 2024-01-04 09:10:08
  5 | ## Title   : Accurate and Efficient Integrative Reference-Informed Spatial Domain Detection for Spatial Transcriptomics   
  6 | ## Authors : Ying Ma
  7 | ####################################################################################################
  8 | 
  9 | #' Accurate and Efficient Integrative Reference-Informed Spatial Domain Detection for Spatial Transcriptomics
 10 | #'
 11 | #' @param IRIS_object IRIS object create by the createIRISObject function
 12 | #' @param numCluster A numeric value indicating the number of clusters
 13 | #' @useDynLib IRIS
 14 | #' @import RcppArmadillo
 15 | #' @import rliger
 16 | #' @importFrom Rcpp sourceCpp
 17 | #' @importFrom MCMCpack rdirichlet
 18 | #' @importFrom fields rdist
 19 | #' @importFrom SummarizedExperiment assays rowData colData
 20 | #' @return Returns a IRIS object with domain labels stored in IRIS_object@spatial_domain for each tissue slice.
 21 | #'
 22 | #' @export
 23 | #' 
 24 | IRIS_spatial <- function(IRIS_object,numCluster){
 25 | version = IRIS_object@project
 26 | ct.select = IRIS_object@internal_info$ct.select
 27 | ct.varname = IRIS_object@internal_info$ct.varname
 28 | sample.varname = IRIS_object@internal_info$sample.varname
 29 | sc_eset = IRIS_object@internal_info$sc_eset
 30 | sliceNames = IRIS_object@internal_info$sliceNames
 31 | countList = IRIS_object@countList
 32 | locationList = IRIS_object@locationList
 33 | K = numCluster
 34 | nSlices = length(countList)
 35 | if(version == "IRIS"){
 36 | cat(paste0("## Extract information from the scRNA-seq reference data! ...\n"))
 37 | Basis = createscRef(assays(sc_eset)$counts, colData(sc_eset),ct.select, ct.varname, sample.varname)
 38 | Basis = Basis[,match(ct.select,colnames(Basis))]
 39 | common_genes_sp = Reduce(intersect, lapply(countList, row.names))
 40 | common_genes = intersect(common_genes_sp,rownames(Basis))
 41 | ##### rm the mito- genes 
 42 | common_genes  = common_genes[!(common_genes %in% common_genes[grep("mt-",common_genes)])]
 43 | info_genes = selectInfo(Basis,sc_eset,common_genes,ct.select,ct.varname) 
 44 | rm(sc_eset)
 45 | IRIS_object@internal_info$sc_eset <- NULL
 46 | gc()
 47 | }else if(version == "IRISfree"){
 48 |   markerList = IRIS_object@internal_info$markerList
 49 |   info_genes = IRIS_object@internal_info$marker
 50 | }
 51 | ##### create the files that IRIS used for
 52 | countList = lapply(countList, function(x) { x[row.names(x) %in% info_genes,] })
 53 | countList = lapply(countList, function(x) { x[sort(rownames(x)),] })
 54 | countList = lapply(countList, function(x) { x[rowSums(x) > 0,] }) 
 55 | countList = lapply(countList, function(x) { x[,colSums(x) > 0] }) 
 56 | common_info_genes = Reduce(intersect, lapply(countList, row.names))
 57 | countList = lapply(countList, function(x) { x[row.names(x) %in% common_info_genes,] })
 58 | countList = lapply(countList, function(x) { x[rowSums(x) > 0,] }) 
 59 | countList = lapply(countList, function(x) { x[,colSums(x) > 0] }) 
 60 | 
 61 | ###### normalize the count data set
 62 | countList = lapply(countList, function(x) { sweep(x,2,colSums(x),"/") })
 63 | 
 64 | ###### check the location list
 65 | for(islice in 1:length(countList)){
 66 |   locationList[[islice]] = locationList[[islice]][rownames(locationList[[islice]]) %in% colnames(countList[[islice]]),]
 67 |   locationList[[islice]] = locationList[[islice]][match(colnames(countList[[islice]]),rownames(locationList[[islice]])),]
 68 | }
 69 | 
 70 | if(version == "IRIS"){
 71 | ###### retain the common_info_genes in the B matrtix
 72 | B = Basis[rownames(Basis) %in% common_info_genes,]
 73 | B = B[order(rownames(B)),]
 74 | rm(Basis)
 75 | gc()
 76 | ###### initialize V list
 77 | initVList = list()
 78 | for(islice in 1:nSlices){
 79 | set.seed(islice)
 80 | V = as.matrix(rdirichlet(ncol(countList[[islice]]), rep(1,ncol(B))))
 81 | V = t(V)
 82 | rownames(V) = colnames(B)
 83 | colnames(V) = colnames(countList[[islice]])
 84 | initVList[[islice]] <- t(V)
 85 | }
 86 | }else if(version == "IRISfree"){
 87 | numK = length(IRIS_object@internal_info$markerList)
 88 | ###### Initialize B matrix
 89 | for(i in 1:length(countList)){
 90 |   colnames(countList[[i]]) = paste0("Slice",i,"_",colnames(countList[[i]]) )
 91 | }
 92 | ifnb_liger <- createLiger(countList,remove.missing = F,take.gene.union = T, verbose = F)
 93 | ifnb_liger <- normalize(ifnb_liger,remove.missing = F, verbose = F)
 94 | #ifnb_liger <- selectGenes(ifnb_liger,var.thresh = -1)
 95 | ifnb_liger@var.genes <- rownames(countList[[1]])
 96 | ifnb_liger <- scaleNotCenter(ifnb_liger, verbose = F)
 97 | ifnb_liger <- optimizeALS(ifnb_liger, k = numK, verbose = F)
 98 | initB = t(ifnb_liger@W)
 99 | ###### remove the "_" in liger
100 | for(i in 1:length(countList)){
101 |   colnames(countList[[i]]) = gsub(paste0("Slice",i,"_"),"",colnames(countList[[i]]) )
102 | }
103 | rownames(initB) = rownames(countList[[1]])
104 | colnames(initB) = paste0("CT",1:numK)
105 | ###### initialize V list
106 | initVList = list()
107 | for(islice in 1:length(ifnb_liger@H)){
108 | set.seed(islice)
109 | V = ifnb_liger@H[[islice]]
110 | colnames(V) = paste0("CT",1:numK)
111 | rownames(V) = colnames(countList[[islice]])
112 | initVList[[islice]] <- V
113 | }
114 | }
115 | ###### create the adjacency matrix between spatial locations in each slice
116 | cat(paste0("### Graph construction! ...\n"))
117 | AList <- createA(locationList)
118 | 
119 | ###### scale the data 
120 | countList = lapply(countList, function(x) { x * 1e-01  / mean(x) }) ############ faster needed
121 | if(version == "IRIS"){
122 | B = B * 1e-01  / mean(B)
123 | CommonCellTypes = colnames(B)
124 | }else if(version == "IRISfree"){
125 |   initB = initB * 1e-01  / mean(initB)
126 |   CommonCellTypes = colnames(initB)
127 | }
128 | 
129 | ######  initialize the contatenated matrix
130 | MatrixCombined = getConcated(initVList,locationList,sliceNames)
131 | ###### initialize the spatial domain labels for each tissue slice
132 | kmeans = kmeansFunc_Initialize(MatrixCombined[,CommonCellTypes],K)
133 | numCluster = length(unique(kmeans$kmeans))
134 | MatrixCombined$kmeans_cluster = as.numeric(kmeans$kmeans)
135 | MatrixCombined$kmeans_cluster = MatrixCombined$kmeans_cluster - 1
136 | TotalClusters = unique(MatrixCombined$kmeans_cluster)[order(unique(MatrixCombined$kmeans_cluster))]
137 | 
138 | ###### Initialize the Mu and STRlist
139 | Mu_STR = getMu_and_STR(CommonCellTypes,TotalClusters,MatrixCombined,nSlices,sliceNames)
140 | cat(paste0("### ",version," starts to run the domain detection! ...\n"))
141 | ###### Initialize IRIS
142 | if(version == "IRIS"){
143 | ResList= IRIS_ref_iter(countList,B,AList,initVList,Mu_STR$STRList,Mu_STR$Mu)
144 | }else if(version == "IRISfree"){
145 |   ResList= IRIS_Marker_iter(countList,initB,AList,initVList,Mu_STR$STRList,Mu_STR$Mu)
146 | }
147 | obj_old = ResList$Obj 
148 | epsilon = 5e-04
149 | 
150 | for(iter in 1:1000){
151 | ###### add the column names and rownames to the V matrix of each tissue slice
152 | for(islice in 1:length(ResList$VList)){
153 |   rownames(ResList$VList[[islice]]) <- colnames(countList[[islice]])
154 |   colnames(ResList$VList[[islice]]) <- CommonCellTypes
155 | }
156 | VList = ResList$VList
157 | if(version == "IRISfree"){
158 |   B = ResList$B
159 |   colnames(B) = colnames(initB)
160 |   rownames(B) = rownames(initB)
161 |   B = B * 1e-01  / mean(B)
162 | }
163 | rm(ResList)
164 | ######  update the contatenated matrix
165 | MatrixCombined = getConcated(VList,locationList,sliceNames)
166 | if(iter == 1){
167 |   centers_old = NULL
168 | }
169 | kmeans = kmeansFunc_Iter(MatrixCombined[,CommonCellTypes],K,centers_old)
170 | numCluster = length(unique(kmeans$kmeans))
171 | MatrixCombined$kmeans_cluster = as.numeric(kmeans$kmeans)
172 | rm(kmeans)
173 | MatrixCombined$kmeans_cluster = MatrixCombined$kmeans_cluster - 1
174 | TotalClusters = unique(MatrixCombined$kmeans_cluster)[order(unique(MatrixCombined$kmeans_cluster))]
175 | ##### update Mu and STRLIst
176 | Mu_STR = getMu_and_STR(CommonCellTypes,TotalClusters,MatrixCombined,nSlices,sliceNames)
177 | centers_old = t(Mu_STR$Mu)
178 | countList = lapply(countList, function(x) {as(x,"sparseMatrix")})
179 | if(version == "IRIS"){
180 | #### The following line is suggested by Dr. Saishi Cun from Dr. Wei Sun's lab! Thank you! It will help void the errors due to data format issues.
181 | countList <- lapply(countList, function(x){if(!inherits(x, "dgCMatrix")){return(as(x, "CsparseMatrix"))}else{return(x)}})  
182 | ResList= IRIS_ref_iter(countList,B,AList,initVList,Mu_STR$STRList,Mu_STR$Mu)
183 | }else if(version == "IRISfree"){
184 |   ResList= IRIS_Marker_iter(countList,B,AList,initVList,Mu_STR$STRList,Mu_STR$Mu)
185 | }
186 | obj = ResList$Obj 
187 | logicalObjective = (obj_old - obj) * 2.0 / abs(obj + obj_old) < epsilon;
188 | if(is.na(obj) || logicalObjective){
189 | if(iter >= 30){  #### run at least 30 iterations
190 |   break;
191 | }else{
192 |   obj_old = obj
193 | }
194 | }else if(obj >= obj_old){
195 |   break;
196 |   }else{
197 |   obj_old = obj
198 | }
199 | }
200 | cat(paste0("### ",version," Finished the domain detection! ...\n"))
201 | ###### store the current domain that makes the minimum objective function
202 | spatialDomain = MatrixCombined[,c("Slice","spotName","x","y","kmeans_cluster")]
203 | colnames(spatialDomain)[colnames(spatialDomain) == "kmeans_cluster"] <- paste0(version,"_domain")
204 | if(version == "IRISfree"){
205 |   IRIS_object@internal_info$B = B
206 | }
207 | IRIS_object@spatialDomain = spatialDomain
208 | IRIS_object@IRIS_Prop = MatrixCombined[,c("Slice","spotName","x","y",CommonCellTypes)]
209 | return(IRIS_object)
210 | }
211 | 
212 | 
213 | #' Construct the mean gene expression basis matrix (B), this is the faster version 
214 | #'
215 | #' @param countMat single-cell RNA-seq count data as the reference
216 | #' @param metadata meta data containing the cell type annotations in the scRNA-seq reference data. The rows matched with the columns of countMat
217 | #' @param ct.select vector of cell type names that you are interested in to deconvolute, default as NULL. If NULL, then use all cell types provided by single cell dataset;
218 | #' @param ct.varname character, the name of the column in metaData that specifies the cell type annotation information
219 | #' @param sample.varname character,the name of the column in metaData that specifies the sample information. If NULL, we just use the whole as one sample.
220 | #'
221 | #' @importFrom SummarizedExperiment assays colData
222 | #' @importFrom wrMisc rowGrpMeans
223 | #' @return Return a list of basis (B) matrix
224 | #'
225 | #'
226 | createscRef <- function(countMat, metadata, ct.select = NULL, ct.varname, sample.varname = NULL){
227 |   metadata <- metadata[metadata[, ct.varname] %in% ct.select,]
228 |   ct.id <- droplevels(as.factor(metadata[, ct.varname]))
229 |   sample.id <- as.character(metadata[, sample.varname])
230 |   ct_sample.id <- paste(ct.id, sample.id, sep = "$*$")
231 |   colSums_countMat <- colSums(countMat)
232 |   colSums_countMat_Ct = aggregate(colSums_countMat ~ ct.id + sample.id, FUN = 'sum')
233 |   colSums_countMat_Ct_wide = reshape(colSums_countMat_Ct, idvar = "sample.id", timevar = "ct.id", direction = "wide")
234 |   colnames(colSums_countMat_Ct_wide) = gsub("colSums_countMat.","",colnames(colSums_countMat_Ct_wide))
235 |   rownames(colSums_countMat_Ct_wide) = colSums_countMat_Ct_wide$sample.id
236 |   colSums_countMat_Ct_wide$sample.id <- NULL
237 |   tbl <- table(sample.id,ct.id)
238 |   colSums_countMat_Ct_wide = colSums_countMat_Ct_wide[,match(colnames(tbl),colnames(colSums_countMat_Ct_wide))]
239 |   colSums_countMat_Ct_wide = colSums_countMat_Ct_wide[match(rownames(tbl),rownames(colSums_countMat_Ct_wide)),]
240 |   S_JK <- colSums_countMat_Ct_wide / tbl
241 |   S_JK <- as.matrix(S_JK)
242 |   S_JK[S_JK == 0] = NA
243 |   S_JK[!is.finite(S_JK)] = NA
244 |   S = colMeans(S_JK, na.rm = TRUE)
245 |   rm(S_JK)
246 |   rm(colSums_countMat_Ct_wide)
247 |   gc()
248 |   S = S[match(unique(ct.id),names(S))]
249 |   Theta_S_rowSums <- rowsum(t(countMat),ct_sample.id)
250 |   Theta_S_rowSums <- t(Theta_S_rowSums)
251 |   Theta_S <- sweep(Theta_S_rowSums,2,colSums(Theta_S_rowSums),"/")
252 |   grp <- sapply(strsplit(colnames(Theta_S),split="$*$",fixed = TRUE),"[",1)
253 |   Theta = rowGrpMeans(Theta_S, grp = grp, na.rm = TRUE)
254 |   Theta = Theta[,match(unique(ct.id),colnames(Theta))]
255 |   S = S[match(colnames(Theta),names(S))]
256 |   basis = sweep(Theta,2,S,"*")
257 |   colnames(basis) = colnames(Theta)
258 |   rownames(basis) = rownames(Theta)
259 |   return(basis)
260 | }
261 | 
262 | #' Select Informative Genes used in the deconvolution
263 | #'
264 | #' @param Basis Reference basis matrix.
265 | #' @param sc_eset scRNAseq data along with meta data stored in the S4 class format (SingleCellExperiment).
266 | #' @param commonGene common genes between scRNAseq count data and spatial resolved transcriptomics data.
267 | #' @param ct.select vector of cell type names that you are interested in to deconvolute, default as NULL. If NULL, then use all cell types provided by single cell dataset;
268 | #' @param ct.varname character, the name of the column in metaData that specifies the cell type annotation information
269 | #' 
270 | #' @importFrom SummarizedExperiment assays colData
271 | #' @importFrom stats quantile
272 | #' @return a vector of informative genes selected
273 | #'
274 | selectInfo <- function(Basis,sc_eset,commonGene,ct.select,ct.varname){
275 | #### log2 mean fold change >0.5
276 | gene1 = lapply(ct.select,function(ict){
277 | rest = rowMeans(Basis[,colnames(Basis) != ict])
278 | FC = log((Basis[,ict] + 1e-06)) - log((rest + 1e-06))
279 | rownames(Basis)[FC > 1.25 & Basis[,ict] > 0]
280 | })
281 | gene1 = unique(unlist(gene1))
282 | gene1 = intersect(gene1,commonGene)
283 | counts = assays(sc_eset)$counts
284 | counts = counts[rownames(counts) %in% gene1,]
285 | sd_within = sapply(ct.select,function(ict){
286 |   temp = counts[,colData(sc_eset)[,ct.varname] == ict]
287 |   apply(temp,1,var) / apply(temp,1,mean)
288 |   })
289 | ##### remove the outliers that have high dispersion across cell types
290 | gene2 = rownames(sd_within)[apply(sd_within,1,mean,na.rm = T) < quantile(apply(sd_within,1,mean,na.rm = T),prob = 0.99,na.rm = T)]
291 | return(gene2)
292 | }
293 | 
294 | #' Construct the adjacency matrix for each tissue slice
295 | #'
296 | #' @param locationList a list of spatial location matrix
297 | #' @import Matrix
298 | #' @importFrom RANN nn2
299 | #' @return Return a list of Ajacency matrix
300 | #'
301 | #'
302 | createA <- function(locationList){
303 |   nSlices = length(locationList)
304 |   AList = list()
305 |   for(islice in 1:nSlices){
306 |     location = as.data.frame(locationList[[islice]])
307 |     norm_cords = location[ ,c("x","y")]
308 |     norm_cords$x = norm_cords$x - min(norm_cords$x)
309 |     norm_cords$y = norm_cords$y - min(norm_cords$y)
310 |     scaleFactor = max(norm_cords$x,norm_cords$y)
311 |     norm_cords$x = norm_cords$x / scaleFactor
312 |     norm_cords$y = norm_cords$y / scaleFactor
313 |     rownames(norm_cords) <- rownames(location)
314 |     ##### find 10 nearest neighbors
315 |     ineibor = 11
316 |     ##### find neiibors
317 |     near_data = nn2(norm_cords[ ,1:2],k = ineibor)
318 |     neibors = near_data$nn.idx
319 |     neibors = neibors[,-1] #### delete itself
320 |     Nmat = Matrix(0,nrow = nrow(neibors),ncol = nrow(neibors),sparse = TRUE)
321 |     for(icol in 1:ncol(neibors)){
322 |     edges = data.frame(i = 1:nrow(neibors), j = neibors[,icol])
323 |     adjacency = sparseMatrix(i = as.integer(edges$i),
324 |                               j = as.integer(edges$j),
325 |                               x = 1,
326 |                               dims = rep(nrow(neibors), 2),
327 |                               use.last.ij = TRUE)
328 |     Nmat = Nmat + adjacency
329 |     }
330 |     ##### only keep mutual neiibors
331 |     Nmat= Nmat * t(Nmat)
332 |     rownames(Nmat) = colnames(Nmat) = rownames(norm_cords)
333 |     AList[[islice]] = Nmat
334 |   }
335 |   return(AList)
336 | 
337 | }
338 | 
339 | #' Construct the concatenated matrix from V across tissue_slices
340 | #'
341 | #' @param VList a list of V matrix across all tissue slices
342 | #' @param locationList a list of location matrix matched with the spatial locations in the VList
343 | #' @param sliceNames a vector of slice names corresponding to the input tissue slices
344 | #' @return Return a list of Ajacency matrix
345 | #'
346 | #'
347 | getConcated <- function(VList,locationList,sliceNames){
348 |   MatrixCombined = NULL
349 |   for(islice in 1:length(VList)){
350 |    V_slice = VList[[islice]]
351 |    V_slice = sweep(V_slice,1,rowSums(V_slice),"/")
352 |    V_slice = as.data.frame(V_slice)
353 |    V_slice$Slice = sliceNames[islice]
354 |    V_slice$ID = paste0(V_slice$Slice,"_",rownames(V_slice))
355 |    V_slice$spotName = rownames(V_slice)
356 |    V_slice$x = locationList[[islice]]$x
357 |    V_slice$y = locationList[[islice]]$y
358 |    MatrixCombined = rbind(MatrixCombined,V_slice)
359 |  }
360 |   return(MatrixCombined)
361 | }
362 | 
363 | #' get the Mu and spatial domain label list
364 | #'
365 | #' @param CommonCellTypes cell types in the reference matrix
366 | #' @param TotalClusters number of total spatial odmains across all tissue slices
367 | #' @param MatrixCombined a concatenated matrix of V matrix across tissue slices
368 | #' @param nSlices number of total slices analyzed
369 | #' @param sliceNames names of the tissue slices in the count list
370 | #' @return Return a list of Mu and the spatial domain labels for each tissue slice
371 | #'
372 | #'
373 | getMu_and_STR <- function(CommonCellTypes,TotalClusters,MatrixCombined,nSlices,sliceNames){
374 |   STRList = list()
375 |   Mu = Matrix(0,nrow = length(CommonCellTypes),ncol = length(TotalClusters))
376 |   for(islice in 1:nSlices){
377 |    Vslice = MatrixCombined[MatrixCombined$Slice == sliceNames[islice],]
378 |    STRList[[islice]] = Vslice$kmeans_cluster
379 |    Clusters = unique(Vslice$kmeans_cluster)[order(unique(Vslice$kmeans_cluster))]
380 |    mu = Matrix(0,nrow = length(CommonCellTypes),ncol = length(TotalClusters))
381 |    colnames(mu) = TotalClusters
382 |    for(i in Clusters){
383 |       mu[,colnames(mu) == i] <- colMeans(Vslice[Vslice$kmeans_cluster == i,CommonCellTypes])
384 |    }
385 |    Mu = Mu + mu
386 |   }
387 |   Mu = Mu / nSlices
388 |   Mu = as.matrix(Mu)
389 |   rownames(Mu) = CommonCellTypes
390 |   return(list(Mu = Mu,STRList = STRList))
391 | }
392 | 
393 | #' Initialize the spatial domain labels
394 | #'
395 | #' @param data Contatnated matrix from all tissue slices.
396 | #' @param k number of spatial domains
397 | #' 
398 | #' @importFrom stats kmeans
399 | #' @return a list of the kmeans clustering results
400 | #'
401 | kmeansFunc_Initialize <- function(data,k){
402 | set.seed(12345678)
403 | ##### use more iterations to initialize the data
404 | if(nrow(data)  < 300000){
405 |   numStart = 100
406 | }else{
407 |     numStart = 1
408 | }
409 | cl <- suppressWarnings(try(kmeans(data, k,nstart = numStart,iter.max=100),silent = TRUE))
410 | 
411 | return(list(kmeans =cl$cluster))
412 | }
413 | 
414 | #' Cluster the spatial domain labels in each iterartion
415 | #'
416 | #' @param data Contatnated matrix from all tissue slices.
417 | #' @param k number of spatial domains
418 | #' @param centers_old centers from last iteration
419 | #' 
420 | #' @importFrom stats kmeans
421 | #' @return a list of the kmeans clustering results and the centers for this iteration
422 | #'
423 | kmeansFunc_Iter <- function(data,k,centers_old = NULL){
424 | set.seed(12345678)
425 | if(nrow(data)  < 300000){
426 |   numStart = 10
427 | }else{
428 |     numStart = 1
429 | }
430 | if(is.null(centers_old)){
431 | cl <- suppressWarnings(try(kmeans(data, k,nstart = 1,iter.max=numStart),silent = TRUE))
432 | }else{
433 | cl <- suppressWarnings(try(kmeans(data, centers_old,nstart = 2,iter.max=numStart),silent = TRUE))
434 | }
435 | if(class(cl) == "try-error"){
436 |   cl <- suppressWarnings(try(kmeans(data, k,nstart = 1,iter.max=numStart),silent = TRUE))
437 | }
438 | resList = list(kmeans =cl$cluster,centers = cl$centers)
439 | return(resList)
440 | }
441 | 
442 | 


--------------------------------------------------------------------------------
/R/RcppExports.R:
--------------------------------------------------------------------------------
 1 | # Generated by using Rcpp::compileAttributes() -> do not edit by hand
 2 | # Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393
 3 | 
 4 | #' IRIS_ref function 
 5 | #' @param XList The input list of normalized spatial data
 6 | #' @param BIn The input list of cell type specific basis matrix B
 7 | #' @param AList The constructed Ajacency matrix for each tissue slice
 8 | #' @param VList List of initial matrix of cell type compositions V
 9 | #' @param StrList List of initial spatial domains for each tissue slice
10 | #' @param MuIn Initial matrix of mean cell type proportion across slices
11 | #'
12 | #' @return A list
13 | #'
14 | #' @export
15 | IRIS_ref_iter <- function(XList, BIn, AList, VList, StrList, MuIn) {
16 |     .Call('_IRIS_IRIS_ref_iter', PACKAGE = 'IRIS', XList, BIn, AList, VList, StrList, MuIn)
17 | }
18 | 
19 | #' IRIS_ref function 
20 | #' @param XList The input list of normalized spatial data
21 | #' @param BIn The input list of cell type specific basis matrix B
22 | #' @param AList The constructed Ajacency matrix for each tissue slice
23 | #' @param VList List of initial matrix of cell type compositions V
24 | #' @param StrList List of initial spatial domains for each tissue slice
25 | #' @param MuIn Initial matrix of mean cell type proportion across slices
26 | #'
27 | #' @return A list
28 | #'
29 | #' @export
30 | IRIS_Marker_iter <- function(XList, BIn, AList, VList, StrList, MuIn) {
31 |     .Call('_IRIS_IRIS_Marker_iter', PACKAGE = 'IRIS', XList, BIn, AList, VList, StrList, MuIn)
32 | }
33 | 
34 | 


--------------------------------------------------------------------------------
/R/utilities.R:
--------------------------------------------------------------------------------
  1 | ####################################################################################################
  2 | ## Package : IRIS
  3 | ## Version : 1.0.1
  4 | ## Date    : 2022-11-13 09:10:08
  5 | ## Title   : Accurate and Scalable Spatial Domain Detection via Integrated Reference-Informed Segmentation for Spatial transcriptomics 
  6 | ## Authors : Ying Ma
  7 | ####################################################################################################
  8 | #' Each IRIS object has a number of slots which store information. Key slots to access
  9 | #' are listed below.
 10 | #'
 11 | #' @slot countList A list of spatial count data matrix. Each spatial count data with rows as the genes and column as measured spatial locations
 12 | #' @slot locationList A list of spatial location matrix. Each spatial location with rows as the measured spatial locations matched with those in the spatial_countMat_list and columns as theccccczzzz
 13 | #' @slot spatialDomain A meta data frame of spatial domain labels detected by IRIS.
 14 | #' @slot project The name of the project, default is "IRIS".
 15 | #' @slot IRIS_Prop A meta data frame of concatenated V matrix estimated by IRIS.
 16 | #' @slot internal_info The neccessary information that are used by IRIS computation.
 17 | #'
 18 | setClass("IRIS", 
 19 | 	slots = list(
 20 | 	countList = "list",
 21 | 	locationList = "list",
 22 | 	spatialDomain = "data.frame",
 23 | 	project = "character",
 24 | 	IRIS_Prop = "data.frame",
 25 | 	internal_info = "list")
 26 | 	)
 27 | #' Each IRISfree object has a number of slots which store information. Key slots to access
 28 | #' are listed below.
 29 | #'
 30 | #' @slot countList A list of spatial count data matrix. Each spatial count data with rows as the genes and column as measured spatial locations
 31 | #' @slot locationList A list of spatial location matrix. Each spatial location with rows as the measured spatial locations matched with those in the spatial_countMat_list and columns as theccccczzzz
 32 | #' @slot spatialDomain A meta data frame of spatial domain labels detected by IRIS.
 33 | #' @slot project The name of the project, default is "IRIS".
 34 | #' @slot IRIS_Prop A meta data frame of concatenated V matrix estimated by IRIS.
 35 | #' @slot internal_info The neccessary information that are used by IRIS computation.
 36 | #'
 37 | setClass("IRISfree", 
 38 | 	slots = list(
 39 | 	countList = "list",
 40 | 	locationList = "list",
 41 | 	spatialDomain = "data.frame",
 42 | 	project = "character",
 43 | 	IRIS_Prop = "data.frame",
 44 | 	internal_info = "list")
 45 | 	)
 46 | 
 47 | 
 48 | 
 49 | #' Quality control of scRNA-seq count data
 50 | #'
 51 | #' @param sc_count Raw scRNAseq count data, each column is a cell and each row is a gene.
 52 | #' @param sc_meta data frame, metaData with "ct.varname" specify the cell type annotation information and "sample.varname" specify the sample information
 53 | #' @param ct.varname character, the name of the column in metaData that specifies the cell type annotation information
 54 | #' @param sample.varname character,the name of the column in metaData that specifies the sample information. If NULL, we just use the whole as one sample.
 55 | #' @param min.cells numeric, we filtered out the non-expressed cells.
 56 | #' @param min.genes numeric we filtered out the non-expressed genes
 57 | #'
 58 | #' @importFrom SingleCellExperiment SingleCellExperiment
 59 | #' @return Return the filtered scRNA-seq data and meta data stored in a S4 class (SingleCellExperiment)
 60 | #'
 61 | #' @export
 62 | #'
 63 | sc_QC <- function(sc_count,sc_meta,ct.varname,sample.varname = NULL, min.cells = 0,min.genes = 0){
 64 |     if(is(sc_count,"matrix")){
 65 | 	sc_count  <- as(as.matrix(sc_count), "sparseMatrix")
 66 | 	}else if(is(sc_count,"vector")){
 67 | 		sc_count  <- as(t(as.matrix(sc_count)), "sparseMatrix")
 68 | 		}else if(is(sc_count,"sparseMatrix")){
 69 | 			sc_count  <- sc_count
 70 | 			}else{
 71 | 				stop("scRNASeq counts has to be of following forms: vector,matrix or sparseMatrix")
 72 | }
 73 | if (missing(x = sc_count)) {
 74 | 	stop("Please provide scRNASeq count data")
 75 | 	} else if (is.null(sample.varname) || missing(sample.varname)) {
 76 | 		sample.varname = "Sample"
 77 | 		sc_meta = as.data.frame(sc_meta)
 78 | 		sc_meta$sampleID = "Sample"
 79 | 		} else if (any(rownames(x = sc_count) == '')) {
 80 | 			stop("Feature names of sc_count matrix cannot be empty", call. = FALSE)
 81 | 			} else if(sum(rownames(sc_meta) == colnames(sc_count)) != ncol(sc_count)){
 82 | 				stop("Cell name in sc_count count data does not match with the rownames of sc_meta")
 83 | 				} else if(ncol(sc_count)!=nrow(sc_meta)){
 84 | 					stop("The number of cells in sc_count and sc_meta should be consistent! (sc_count -- p x c; sc_meta -- c x 2 or c x m)")
 85 | }
 86 | if (is.null(ct.varname)){
 87 | 	stop("Please provide the column name indicating the cell type information in the sc_count")
 88 | }
 89 | ct.select <- unique(sc_meta[, ct.varname])
 90 | if (is.null(ct.select)){
 91 | 	stop("No cell type information in the column of ct.varname in the sc_meta")
 92 | }
 93 | # Filter based on min.features
 94 | if (min.genes >= 0) {
 95 |     nfeatures <- colSums(x = sc_count )
 96 |     keep = which(nfeatures > min.genes)
 97 |     sc_count <- sc_count[, keep]
 98 |     sc_meta <- sc_meta[keep,]
 99 | }
100 | # filter genes on the number of cells expressing
101 | if (min.cells >= 0) {
102 |     num.cells <- rowSums(x = sc_count > 0)
103 |     sc_count <- sc_count[which(x = num.cells > min.cells), ]
104 | }
105 | fdata = as.data.frame(rownames(sc_count))
106 | rownames(fdata) = rownames(sc_count)
107 | ct.select <- as.character(ct.select[!is.na(ct.select)])
108 | ####### at least two cells
109 | ct.select = names(table(sc_meta[,ct.varname]))[table(sc_meta[,ct.varname]) > 1]
110 | keepCell = as.character(sc_meta[,ct.varname]) %in% ct.select
111 | sc_count = sc_count[,keepCell]
112 | sc_meta = sc_meta[keepCell,]
113 | keepGene = rowSums(sc_count) > 0
114 | fdata = as.data.frame(fdata[keepGene,])
115 | sc_count = sc_count[keepGene,]
116 | sce <- SingleCellExperiment(list(counts=sc_count),
117 | colData=as.data.frame(sc_meta),
118 | rowData=as.data.frame(fdata))
119 | return(sce)
120 | }
121 | 
122 | #' Create the IRIS object
123 | #'
124 | #' @param spatial_countMat_list A list of raw spatial resolved transcriptomics data. In each spatial transcriptomics data, it is a sparse matrix with each column is a spatial location, and each row is a gene. 
125 | #' @param spatial_location_list A list of spatial location data frames, with two columns representing the x and y coordinates of the spatial location (The column names must contain "x" and "y"). The rownames of this data frame should match eaxctly with the columns of the corresponding spatial_count in the spatial_countMat_list.
126 | #' @param sc_count Reference scRNA-seq count data, each column is a cell and each row is a gene.
127 | #' @param sc_meta A data frame of meta data providing information on each cell in the sc_count, with each row representing the cell type and/or sample information of a specific cell. The row names of this data frame should match exactly with the column names of the sc_count data
128 | #' @param ct.varname character, the name of the column in metaData that provides the cell type annotation information for IRIS to perform informed domain detection.
129 | #' @param sample.varname character,the name of the column in metaData that specifies the sample information. If NULL, we just use the whole as one sample.
130 | #' @param markerList a list of marker genes, with each element of the list being the vector of cell type specific marker genes, default is NULL
131 | #' @param version A character indicating whether to use IRIS, IRISfree or IRISsingle. The default version is "IRIS". We highly recommend using the original IRIS version.
132 | #' @param minCountGene Minimum counts for each gene in the spatial count data
133 | #' @param minCountSpot Minimum counts for each spatial location in the spatial count data
134 | 
135 | #'
136 | #' @importFrom SummarizedExperiment assays rowData
137 | #' @import methods
138 | #' @return Returns IRIS object with filtered spatial count list, location list and reference scRNA-seq dataset.
139 | #'
140 | #' @export
141 | #'
142 | createIRISObject <- function(spatial_countMat_list,spatial_location_list,sc_count,sc_meta,ct.varname,sample.varname,markerList = NULL,version = "IRIS",minCountGene = 100,minCountSpot =5){  
143 | 
144 | #### QC on spatial dataset
145 | cat(paste0("## QC on spatially-resolved dataset! ...\n"))
146 | if (length(spatial_countMat_list) != length(spatial_location_list)) {
147 | 			stop("The length of spatial_countMat_list does not equal to the length of spatial_location_list", call. = FALSE)
148 | }
149 | Nslices = length(spatial_countMat_list)
150 | sliceNames = names(spatial_countMat_list)
151 | if(is.null(sliceNames)){
152 | 	if(length(spatial_countMat_list) >= 2){
153 | 	cat(paste0("## There are no names for the tissue slice, we will use Slice 1, ..., Slice",length(sliceNames)," to represent! ...\n"))
154 | 	}
155 | 	sliceNames = paste0("Slice",1:length(spatial_countMat_list))
156 | }
157 | countList = list()
158 | locationList = list()
159 | for(islice in 1:Nslices){
160 | 	spatial_count = spatial_countMat_list[[islice]]
161 | 	spatial_location = spatial_location_list[[islice]]
162 | 	if(is(spatial_count,"matrix")){
163 | 		spatial_count  <- as(as.matrix(spatial_count), "sparseMatrix")
164 | 	}else if(is(spatial_count,"vector")){
165 | 		spatial_count  <- as(t(as.matrix(spatial_count)), "sparseMatrix")
166 | 		}else if(is(spatial_count,"sparseMatrix")){
167 | 			spatial_count <- spatial_count
168 | 			}else{
169 | 				stop(paste0("The ",islice,"-th spatial resolved transcriptomic counts has to be of following forms: vector,matrix or sparseMatrix"))
170 | 			}
171 | 	if (any(rownames(x = spatial_count) == '')) {
172 | 			stop(paste0("Gene names of the ",islice,"-th spatial count matrix cannot be empty"), call. = FALSE)
173 | 	}
174 | 	if(is.null(spatial_location)){
175 | 	stop(paste0("Please provide the matched spatial location data frame for the ",islice,"-th spatial count matrix"))
176 |     }
177 |     if(ncol(spatial_count)!=nrow(spatial_location)){
178 | 	stop(paste0("The number of the columns in the ",islice,"-th spatial_count and the number of rows in the ",islice,"-th spatial_location should be consistent! (spatial_count -- p x n_slice; spatial_location -- n_slice x 2)"))
179 | 	}# end fi
180 | 	## check data order should consistent
181 | 	if(!identical(colnames(spatial_count), rownames(spatial_location))){
182 | 	stop(paste0("The column names of the ",islice,"-th spatial_count and row names of the ",islice,"-th spatial_location should be consistent! (spatial_count -- p x n; spatial_location -- n x 2)"))
183 | 	}# end fi
184 | 	spatial_count = spatial_count[rowSums(spatial_count > 0) > minCountSpot,]
185 |     spatial_count = spatial_count[,(colSums(spatial_count) >= minCountGene)]
186 |     spatial_location = spatial_location[rownames(spatial_location) %in% colnames(spatial_count),]
187 |     spatial_location = spatial_location[match(colnames(spatial_count),rownames(spatial_location)),] 
188 |     countList[[islice]] <- spatial_count 
189 |     locationList[[islice]] <- spatial_location
190 | }
191 | names(countList) = names(spatial_countMat_list)
192 | rm(spatial_countMat_list)
193 | rm(spatial_location_list)
194 | gc()
195 | common_names = Reduce(intersect, lapply(countList, row.names))
196 | if (length(common_names) == 0) {
197 | 			stop("There are no common gene names in the spatial_countMat_list", call. = FALSE)
198 | }
199 | ## QC on scRNA-seq count
200 | if(version == "IRIS"){
201 | 	#### create SingleCellExperiment Object and QC on the scRNA-seq reference data
202 | 	cat(paste0("## QC on scRNA-seq dataset! ...\n"))
203 | 	sc_eset = sc_QC(sc_count,sc_meta,ct.varname,sample.varname)
204 | 	ct.select = as.character(unique(colData(sc_eset)[,ct.varname]))
205 | 	common_genes = markerList = NULL
206 | 	rm(sc_count)
207 | 	rm(sc_meta)
208 | 	gc()
209 | }else if(version == "IRISfree"){
210 | 	if(is.null(markerList)){
211 | 		stop("Please provide marker genes for at least two cell types in the markerList")
212 | 	}else if(!is.null(markerList) & length(markerList) == 1){
213 | 		stop("The length of markerList is 1, please provide marker genes for at least two cell types in the markerList")
214 | 	}else if(!is.null(markerList) & length(markerList) > 1){
215 | 	numK = length(markerList)
216 | 	marker = unique(unlist(markerList))
217 | 	#marker = toupper(marker)
218 | 	cat(paste0("## Number of unique marker genes: ",length(marker)," for ",numK," cell types ...\n"))
219 | 	commonGene = intersect(toupper(common_names),toupper(marker))
220 | 	#### remove mitochondrial and ribosomal genes
221 | 	commonGene  = commonGene[!(commonGene %in% commonGene[grep("mt-",commonGene)])]
222 | 	if(length(commonGene) < numK * 10){
223 | 		cat(paste0("## STOP! The average number of unique marker genes for each cell type is less than 10 ...\n"))
224 | 	}
225 | 	marker = unique(unlist(markerList))
226 | 	numK = length(markerList)
227 | 	common_genes = intersect(common_names,marker)
228 | 	##### rm the mito- genes 
229 | 	common_genes  = common_genes[!(common_genes %in% common_genes[grep("mt-",common_genes)])]
230 | 	sc_eset = sample.varname = ct.select = ct.varname = NULL
231 | 
232 | }
233 | }
234 | object <- new(
235 | 		Class = version,
236 | 		countList = countList,
237 | 		locationList = locationList,
238 | 		project = version,
239 | 		internal_info = list(ct.varname = ct.varname,ct.select = ct.select,sample.varname = sample.varname,sc_eset = sc_eset,sliceNames = sliceNames, markerList = markerList, marker = common_genes)
240 | 		)
241 | gc()
242 | return(object)
243 | }
244 | 
245 | 
246 | 


--------------------------------------------------------------------------------
/R/visualization.R:
--------------------------------------------------------------------------------
  1 | ####################################################################################################
  2 | ## Package : IRIS
  3 | ## Version : 1.0.1
  4 | ## Date    : 2022-11-13 09:10:08
  5 | ## Title   : Integrative and Reference-Informed Spatial Domain Detection for Spatial Transcriptomics  
  6 | ## Authors : Ying Ma
  7 | ####################################################################################################
  8 | 
  9 | ####################################################################################################
 10 | #' Visualize the spatial domains
 11 | #'
 12 | #' @param IRIS_domain Data frame, spatial domains infered by IRIS across multiple slices. The column "IRIS_domain" contains the domain label. With each row representing one spatial location from each slice.
 13 | #' @param spatial_location Data frame, spatial location information for each spot in IRIS_domain in each tissue slice. The row names must be consistent with the row names in the data frame IRIS_domain. The data contains two columns, with the first column representing the x coordinates, with the second column representing the y coordinates
 14 | #' @param colors Vector of color names that you want to use, if NULL, we will use the default color. 
 15 | #' @param numCols Numeric, number of figure panels, it depends on the number of tissue slices you want to visualize.
 16 | #'
 17 | #' @import ggplot2 
 18 | #' @importFrom grDevices colorRampPalette
 19 | #' @return Returns a ggplot2 figure. 
 20 | #'
 21 | #' @export
 22 | #'
 23 | 
 24 | IRIS.visualize.domain <- function(IRIS_domain,spatial_location,colors = NULL,numCols){
 25 | colorValBasic = c("#eec7b6","#e79d8d","#8ed7e6","#219ebc","#2A9D8F",
 26 | "#CC9A81","#81b29a","#A9CBCA","#f4f1de","#B18D97",
 27 | "#FAD471","#8e9aaf","#cbc0d3","#ffb703","#F7BEEC",
 28 | "#5965B0","#E16E6E")
 29 | if(sum(rownames(IRIS_domain) == rownames(spatial_location)) != nrow(IRIS_domain)){
 30 |     stop("The rownames of IRIS_domain data does not match with the rownames of spatial_location data")
 31 | }
 32 | if(is.null(colors)){
 33 |     if(length(unique(IRIS_domain$IRIS_domain)) > length(colorVal)){
 34 |     colors = colorRampPalette(colorValBasic)(length(unique(IRIS_domain$IRIS_domain)))
 35 |     }else{
 36 |         colors = colorValBasic
 37 |     }
 38 | }else{
 39 |     colors = colors
 40 | }
 41 | 
 42 | colnames(spatial_location) = c("plotx","ploty")
 43 | data_plot = cbind(IRIS_domain,spatial_location)
 44 | data_plot$IRIS_domain = factor(data_plot$IRIS_domain,levels = sort(unique(data_plot$IRIS_domain)))
 45 | data_plot$Slice = factor(data_plot$Slice,levels = sort(unique(data_plot$Slice)))
 46 | p = suppressMessages(ggplot(data_plot) + 
 47 |     geom_point(aes(x = plotx, y = ploty, colour = IRIS_domain),alpha = 1.0,size = 1.0,stroke = 0, shape = 16) +
 48 |     scale_colour_manual(values =  colors) + 
 49 |     #coord_fixed()+
 50 |     #facet_wrap(~Slice,nrow = floor(sqrt(Nslice)),scales = "free") + 
 51 |     facet_wrap(~Slice,scales = "free",ncol = numCols)+
 52 |     #geom_label(data = data, aes(x = 300, y = -80,label = ARI,fill = colorARI),hjust = "middle",colour = "#4D4E4D",size = 7,fontface = "bold")+
 53 |     #scale_fill_manual(values =  c("#e07a5f","#f4f1de")) + 
 54 |     theme(plot.margin = margin(0.35, 0.35, 0.35, 0.35, "cm"),
 55 |         panel.background = element_rect(colour = "white", fill="white"),
 56 |         plot.background = element_rect(colour = "white", fill="white"),
 57 |         panel.border = element_rect(colour = "grey39", fill=NA, size=0.5),
 58 |         axis.text.y=element_blank(),
 59 |         axis.text.x=element_blank(),
 60 |         axis.title.y=element_blank(),
 61 |         axis.title.x=element_blank(),
 62 |           legend.text=element_text(size=12),
 63 |           legend.title=element_text(size = 13,face="bold"),
 64 |           legend.position = 'bottom',
 65 |           strip.text = element_text(size = 16,face="bold"),
 66 |           legend.key = element_rect(colour = "transparent", fill = "white"),
 67 |           legend.key.size = unit(1.0, 'cm'))+
 68 |     guides(color = guide_legend(override.aes = list(size = 7,alpha=1),nrow=2),fill = 'none')+
 69 |     labs(color='IRIS domain'))
 70 | return(p)
 71 | }
 72 | 
 73 | #' Visualize the spatial distribution of cell type proportion
 74 | #'
 75 | #' @param proportion Data frame, cell type proportion estimated by IRIS in either original resolution or enhanced resolution.
 76 | #' @param spatial_location Data frame, spatial location information.
 77 | #' @param ct.visualize Vector of selected cell type names that are interested to visualize
 78 | #' @param colors Vector of color names that you want to use, if NULL, we will use the default color scale c("lightblue","lightyellow","red")
 79 | #' @param numCols Numeric, number of columns in the figure panel, it depends on the number of cell types you want to visualize.
 80 | #'
 81 | #' @import ggplot2 
 82 | #' @importFrom reshape2 melt
 83 | #' @return Returns a ggplot2 figure. 
 84 | #'
 85 | #' @export
 86 | #'
 87 | 
 88 | IRIS.visualize.eachProp <- function(proportion,spatial_location,ct.visualize = ct.visualize,colors = c("lightblue","lightyellow","red"),numCols){
 89 | if(is.null(colors)){
 90 |     colors = c("lightblue","lightyellow","red")
 91 | }else{
 92 |     colors = colors
 93 | }
 94 | res_IRIS = as.data.frame(proportion)
 95 | res_IRIS = res_IRIS[,order(colnames(res_IRIS))]
 96 | location = as.data.frame(spatial_location)
 97 | if(sum(rownames(res_IRIS)==rownames(location))!= nrow(res_IRIS)){
 98 |    stop("The rownames of proportion data does not match with the rownames of spatial location data")
 99 | }
100 | ct.select = ct.visualize
101 | res_IRIS = res_IRIS[,ct.select]
102 | res_IRIS_scale = as.data.frame(apply(res_IRIS,2,function(x){
103 |     (x - min(x)) / (max(x) - min(x))
104 | } ))
105 | res_IRIS_scale$x = as.numeric(location$x)
106 | res_IRIS_scale$y = as.numeric(location$y)
107 | mData = melt(res_IRIS_scale,id.vars = c("x","y"))
108 | colnames(mData)[3] <- "Cell_Type"
109 | b = c(0,1)
110 | p = suppressMessages(ggplot(mData, aes(x, y)) + 
111 | geom_point(aes(colour = value),alpha = 1.0,size = 1.0,stroke = 0, shape = 16) +
112 | scale_color_gradientn(colours = colors) + 
113 | #scale_color_viridis_c(option = 2)+
114 | scale_x_discrete(expand = c(0, 1)) + scale_y_discrete(expand = c(0,1))+ 
115 | facet_wrap(~Cell_Type,ncol = numCols)+ 
116 | theme(plot.margin = margin(0.1, 0.1, 0.1, 0.1, "cm"),
117 |     #legend.position=c(0.14,0.76),
118 |     panel.background = element_blank(),
119 |     plot.background = element_blank(),
120 |     panel.border = element_rect(colour = "grey89", fill=NA, size=0.5),
121 |     axis.text =element_blank(),
122 |     axis.ticks =element_blank(),
123 |     axis.title =element_blank(),
124 |     legend.title=element_text(size = 13,face="bold"),
125 |     legend.text=element_text(size = 12),
126 |     strip.text = element_text(size = 16,face="bold"),
127 |     legend.key = element_rect(colour = "transparent", fill = "white"),
128 |     legend.key.size = unit(1.0, 'cm')))
129 | return(p)
130 | }
131 | 
132 | 
133 | 
134 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # IRIS
 2 | ## Integrative and Reference-Informed Spatial Domain Detection for Spatial Transcriptomics 
 3 | 
 4 | <p align="center">
 5 | <img src="https://github.com/YingMa0107/IRIS/blob/master/IRIS_logo.png" width="400" />
 6 | </p>
 7 | We developed a statistical method for Integrative and Reference-Informed Spatial Domain Detection for Spatial Transcriptomics. IRIS is a reference-informed integrative method for detecting spatial domains on multiple tissue slices from spatial transcriptomics with spot-level, single-cell level, or subcellular level resolutions. IRIS builds upon the fact that each spatial domain on the tissue is characterized by a unique composition of cell types and that similar composition is observed for the same spatial domain across different slices of the same tissue 28,29. Consequently, IRIS integrates a reference scRNA-seq data to inform and characterize the cell type composition on the tissue of spatial transcriptomics for accurate and interpretable spatial domain detection. In the process, IRIS accommodates cell type compositional similarity across locations within the same slice and across different slices on the same domain to borrow information both within and between tissue slices for integrative and accurate spatial domain detection. Importantly, IRIS comes with an efficient optimization framework with multiple algebraic innovations for scalable computation and can easily handle multiple spatial transcriptomics datasets with millions of spatial locations and tens of thousands of genes. 
 8 | 
 9 | Installation
10 | ------------
11 | You can install the released version of IRIS from Github with the following code, for more installation details or solutions that might solve related issues (specifically MacOS system) see the [link](https://yingma0107.github.io/IRIS/documentation/02_installation.html).
12 | 
13 | ## Dependencies 
14 | * R version >= 4.2.2.
15 | * Dependent R packages: Rcpp (>= 1.0.9), RcppArmadillo, SingleCellExperiment, SummarizedExperiment, methods, Matrix, MCMCpack, fields, wrMisc, RANN, stats, ggplot2, grDevices, reshape2
16 | 
17 | 
18 | ``` r
19 | # install devtools if necessary
20 | install.packages('devtools')
21 | 
22 | # install the IRIS package
23 | devtools::install_github('YingMa0107/IRIS')
24 | 
25 | # load package
26 | library(IRIS)
27 | 
28 | ```
29 | The R package has been installed successfully on Operating systems: 
30 | * macOS Catalina 10.15, macOS Monterey 12.4
31 | * Ubuntu 18.04.6 LTS
32 | * Windows 10
33 | 
34 | # Issues
35 | All feedback, bug reports and suggestions are warmly welcomed! Please make sure to raise issues with a detailed and reproducible example and also please provide the output of your sessionInfo() in R! 
36 | 
37 | How to cite `IRIS`
38 | -------------------
39 | Ying Ma and Xiang Zhou. Integrative and Reference-Informed Spatial Domain Detection for Spatial Transcriptomics, Nature Methods 2024， [link](https://www.nature.com/articles/s41592-024-02284-9)
40 | 
41 | How to use `IRIS`
42 | -------------------
43 | Details in [Tutorial](https://yingma0107.github.io/IRIS/)
44 | 


--------------------------------------------------------------------------------
/docs/IRIS_logo1.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/YingMa0107/IRIS/79285560385a63fd3094251cfe7306ccf8389107/docs/IRIS_logo1.png


--------------------------------------------------------------------------------
/docs/_config.yml:
--------------------------------------------------------------------------------
 1 | remote_theme: allejo/jekyll-docs-theme
 2 | name: IRIS
 3 | 
 4 | project:
 5 |   version: 1.0.0
 6 |   download_url: https://github.com/YingMa0107/IRIS/
 7 |   download_text: Download
 8 | 
 9 | license:
10 |   software: GNU License 3.0
11 |   software_url: https://www.gnu.org/licenses/licenses.en.html
12 |  
13 | links:
14 |   header:
15 |     - title: GitHub
16 |       icon: github
17 |       brand: true
18 |       url: https://github.com/YingMa0107/IRIS/
19 |   homepage:
20 |     - title: View on GitHub
21 |       icon: github
22 |       brand: true
23 |       url: https://github.com/YingMa0107/IRIS/
24 |   footer:
25 |     - title: GitHub
26 |       icon: github
27 |       brand: true
28 |       url: https://github.com/YingMa0107/IRIS/
29 |     - title: Issues
30 |       icon: bug
31 |       url: https://github.com/YingMa0107/IRIS/issues?state=open
32 | 
33 | ui:
34 |   mode: 'auto' # 'auto', 'dark', 'light'
35 |   brand:
36 |     dark: "#f7c1d2"
37 |     light: "#a20000"
38 |   border_color:
39 |     dark: "#ababab"
40 |     light: "#324B69" #"#e4edf7"
41 |   header:
42 |     trianglify: true
43 |     dark:
44 |       color1: "#3d5a80" #"#e69eae"
45 |       color2: "#98c1d9" #"#a5cccc"
46 |     light:
47 |       color1: "#375274" #"#080331"
48 |       color2: "#8FABBE" #"#673051"
49 |   masthead:
50 |     color:
51 |       dark: "#fff"
52 |       light: "#fff"
53 |     align:
54 |       homepage: 'center'
55 |       page: 'left'
56 | 
57 | social:
58 |   github:
59 |     user: YingMa0107
60 |     repo: IRIS
61 |   twitter:
62 |     enabled: false
63 |     via:
64 |     hash:
65 |     account:
66 |   facebook:
67 |     enabled: false
68 |     profileUrl:
69 | 
70 | analytics:
71 |   google: UA-123456-1
72 | 
73 | # Build settings
74 | markdown: kramdown
75 | exclude:
76 |   - LICENSE.md
77 |   - README.md
78 | 


--------------------------------------------------------------------------------
/docs/documentation/01_About.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | layout: page
 3 | title: About
 4 | ---
 5 | 
 6 | We developed a deconvolution method, 'IRIS', that can characterize the spatial organization of complex tissues through accurate and efficient detection of spatial domains. IRIS is unique in its ability in leveraging single-cell RNA-seq data for reference-informed spatial domain detection, integrating multiple SRT tissue slices jointly while explicitly accounting for the correlation both within and across slices, and taking advantage of multiple algorithmic innovations for highly scalable computation. We demonstrate the advantages of IRIS through in-depth analysis of six SRT datasets from different technologies across distinct tissues, species, and spatial resolutions. In addition, IRIS comes with an efficient optimization framework with multiple algebraic innovations for scalable computation and can easily handle multiple spatial transcriptomics datasets with millions of spatial locations and tens of thousands of genes
 7 | 
 8 | Cite `IRIS`
 9 | -------------------
10 | Ma Y, Zhou X. Accurate and efficient integrative reference-informed spatial domain detection for spatial transcriptomics. Nat Methods. 2024 Jun 6. doi: 10.1038/s41592-024-02284-9. Epub ahead of print. PMID: 38844627.
11 | 
12 | Contact
13 | -------------------
14 | if you have questions, feel free to leave messages on the [github issues](https://github.com/YingMa1993/IRIS/issues) 
15 | 
16 | 
17 | 
18 | 


--------------------------------------------------------------------------------
/docs/documentation/02_installation.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | layout: page
 3 | title: Installation
 4 | description: ~
 5 | ---
 6 | 
 7 | `IRIS` is implemented as an Rcpp package, which can be installed from GitHub by:
 8 | 
 9 | ### Dependencies 
10 | * R version >= 4.2.2.
11 | * Dependent R packages: Rcpp (>= 1.0.9), RcppArmadillo, SingleCellExperiment, SummarizedExperiment, methods, Matrix, MCMCpack, fields, wrMisc, RANN, stats, ggplot2, grDevices, reshape2
12 | 
13 | 
14 | #### 1. Install `devtools` if necessary
15 | ```r
16 | install.packages('devtools')
17 | ```
18 | 
19 | #### 2. Install `CARD`
20 | ```r
21 | devtools::install_github('YingMa0107/IRIS')
22 | ```
23 | #### 3. Load package
24 | ```r
25 | library(IRIS)
26 | ```
27 | 
28 | This package is supported for Windows 10, MAC and Linux. The package has been tested on the following systems:
29 | - MAC (Catalina 10.15, Monterey 12.4)
30 | - Linux: Ubuntu (16.04.6)
31 | - Windows 10: Home (1903)
32 | 
33 | #### 4. Some possible issues when installing the package, especially on the MacOS system
34 | (1) Cannot find tools necessary when using R in the MacOS system.
35 | ```r
36 | Error: Failed to install 'IRIS' from GitHub:
37 |   Could not find tools necessary to compile a package
38 | Call `pkgbuild::check_build_tools(debug = TRUE)` to diagnose the problem.
39 | ``` 
40 | possible solution: in R, type the code ``` options(buildtools.check = function(action) TRUE )```, see the discussion about this error, [link](https://stackoverflow.com/questions/37776377/error-when-installing-an-r-package-from-github-could-not-find-build-tools-neces)
41 | 
42 | (2) library not found for -lgfortran when using R in the MacOS system.
43 | ```r
44 | ld: library not found for -lgfortran
45 | ```
46 | It seems the gfortran is not well installed on the MacOS system. Please check this [link](https://thecoatlessprofessor.com/programming/cpp/r-compiler-tools-for-rcpp-on-macos/) for the gfortran installation to see if it helps. 
47 | 
48 | 
49 | 


--------------------------------------------------------------------------------
/docs/documentation/03_data.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | layout: page
 3 | title: Data Input
 4 | description: Link to download the example dataset
 5 | ---
 6 | The following are the links for the example dataset used in the IRIS main tutorial. 
 7 | 
 8 | 1. list of spatial transcriptomics data across multiple slices, here we use 4 slices from 10x Visium DLPFC as an example
 9 |   * [sp_input](https://drive.google.com/drive/folders/1I0ZQw8qm_XPYqXXrt7wpTB13sttMetLU)
10 |   
11 | 2. single cell RNA-seq as reference 
12 |   * [sc_input](https://drive.google.com/drive/folders/1I0ZQw8qm_XPYqXXrt7wpTB13sttMetLU)
13 |   
14 | Details of the sources of these two example data sets can be found in the paper's Data Availability session.
15 | 


--------------------------------------------------------------------------------
/docs/documentation/04_IRIS_Example.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | layout: page
  3 | title: Example Analysis
  4 | description: ~
  5 | ---
  6 | This tutorial is the example analysis with IRIS on the 10x Visium human dorsolateral pre-frontal cortex (DLPFC) spatial transcriptomics data from [Maynard et al, 2021](https://www.nature.com/articles/s41593-020-00787-0). Before running the tutorial, please make sure that the IRIS package was installed. Installation instructions see the [link](https://yingma0107.github.io/IRIS/documentation/02_installation.html)
  7 | 
  8 | ## Required input data
  9 | `IRIS` requires two types of input data:
 10 | - A list of spatial transcriptomics count data across multiple slices, along with spatial location information for each tissue slice.  
 11 | - A reference single cell RNA-seq (scRNA-seq) count data, along with meta information indicating the cell type information and the sample (subject) information for each cell.  
 12 | 
 13 | The example data for running the tutorial can be downloaded in this [page](https://yingma0107.github.io/IRIS/documentation/03_data.html)
 14 | Here are the details about the required data input illustrated by the example datasets. 
 15 | ### 1. spatial transcriptomics data, e.g.,
 16 | ```r
 17 | #### read in the example spatial transcriptomics data
 18 | sp_input = readRDS("./countList_spatial_LIBD.RDS")
 19 | #### print the names of sp_input list
 20 | print(names(sp_input))
 21 | "spatial_countMat_list" "spatial_location_list"
 22 | #### extract the count data list and location list
 23 | spatial_countMat_list = sp_input$spatial_countMat_list
 24 | spatial_location_list = sp_input$spatial_location_list
 25 | #### check the count and spatial location, for example, the third tissue slice 151509
 26 | print(dim(spatial_countMat_list[[3]]))
 27 | [1] 33514  4730
 28 | ####### print the first three rows and columns of the count data of the third tissue 
 29 | print(spatial_countMat_list[[3]][1:3,1:3])
 30 | 3 x 3 sparse Matrix of class "dgCMatrix"
 31 |             389.198933296x417.326747046 133.43834843x233.033311356
 32 | MIR1302-2HG                           .                          .
 33 | FAM138A                               .                          .
 34 | OR4F5                                 .                          .
 35 |             437.983813464x157.830788514
 36 | MIR1302-2HG                           .
 37 | FAM138A                               .
 38 | OR4F5                                 .
 39 | ####### print the dimension of the location data
 40 | print(dim(spatial_location_list[[3]]))
 41 | [1] 4730    2
 42 | ####### print the first three rows of spatial location data of the third tissue 
 43 | print(spatial_location_list[[3]][1:3,])
 44 |                                    x        y
 45 | 389.198933296x417.326747046 389.1989 417.3267
 46 | 133.43834843x233.033311356  133.4383 233.0333
 47 | 437.983813464x157.830788514 437.9838 157.8308
 48 | ```
 49 | The spatial transcriptomics count data for each tissue slice must be in the format of matrix or sparseMatrix, while each row represents a gene and each column represents a spatial location. The column names of the spatial data can be in the "XcoordxYcoord" (i.e., 10x10) format, but you can also maintain your original spot names, for example, barcode names. Correspondingly, the spatial location information for each tissue slice must be in the format of data frame or matrix, with each row matches with the spatial location in the spatial count data, and each column represents either the x coordinate or the y coordinate, then column names of the spatial location data must be "x" and "y".
 50 | 
 51 | ### 2. Reference single-cell RNAseq ((scRNA-seq)) data,  e.g.,
 52 | ```r
 53 | #### read in the example reference scRNA-seq data, 
 54 | sc_input = readRDS("./scRef_input_mainExample.RDS")
 55 | #### extract the count data, metadata, column name indicating cell type annotation, and column name indicating samples/subjects.
 56 | sc_count = sc_input$sc_count
 57 | sc_meta = sc_input$sc_meta
 58 | ct.varname = sc_input$ct.varname
 59 | sample.varname = sc_input$sample.varname
 60 | #### check the sc_count data
 61 | print(sc_count[1:4,1:4])
 62 | 4 x 4 sparse Matrix of class "dgCMatrix"
 63 |            AAACGGGAGATCCCGC.1 AAATGCCTCCAATGGT.1 AACCATGTCAGTGCAT.1
 64 | FO538757.2                  .                  1                  1
 65 | SAMD11                      .                  .                  .
 66 | NOC2L                       .                  .                  .
 67 | KLHL17                      .                  .                  .
 68 |            AACCATGTCTGTACGA.1
 69 | FO538757.2                  .
 70 | SAMD11                      .
 71 | NOC2L                       1
 72 | KLHL17                      .
 73 | 
 74 | ```
 75 | The scRNA-seq count data must be in the format of matrix or sparseMatrix, while each row represents a gene and each column represents a cell.
 76 | 
 77 | ```r
 78 | #### check the meta data
 79 | print(sc_meta[1:4,])
 80 |                                   TAG   projid cellType sampleID
 81 | AAACGGGAGATCCCGC.1 AAACGGGAGATCCCGC.1 11409232      Ex8        1
 82 | AAATGCCTCCAATGGT.1 AAATGCCTCCAATGGT.1 11409232      Ex0        1
 83 | AACCATGTCAGTGCAT.1 AACCATGTCAGTGCAT.1 11409232      Ex8        1
 84 | AACCATGTCTGTACGA.1 AACCATGTCTGTACGA.1 11409232      Ex0        1
 85 | ```
 86 | The scRNAseq meta data must be in the format of data frame while each row represents a cell. The rownames of the scRNAseq meta data should match exactly with the column names of the scRNAseq count data. The sc_meta data must contain the column indicating the cell type assignment for each cell (e.g., "cellType" column in the example sc_meta data). Sample/subject information should be provided, if there is only one sample, we can add a column by ```sc_meta$sampleInfo = "sample1"```.
 87 | 
 88 | We suggest the users to check their single cell RNASeq data carefully before running IRIS. We suggest the users to input the single cell RNAseq data with each cell type containing at least 2 cells. i.e. print(table(sc_meta$cellType,useNA = "ifany"))
 89 | 
 90 | ## Integrative and Reference-Informed Spatial Domain Detection for Spatial Transcriptomics
 91 | ```r
 92 | library(IRIS)
 93 | ``` 
 94 | ### 1. Create an `IRIS` object
 95 | The IRIS object is created by the function `createIRISObject`. The essential inputs are:
 96 | - spatial_countMat_list A list of raw spatial resolved transcriptomics count data across multiple slices. In each tissue slice, it is a sparse matrix with each column is a spatial location, and each row is a gene. 
 97 | - spatial_location_list A list of spatial location data frames across multiple slices, with two columns representing the x and y coordinates of the spatial location (The column names must contain "x" and "y"). The rownames of this data frame should match exactly with the columns of the corresponding spatial_count in the spatial_countMat_list. The order of the tissue slices in the spatial_location_list must match with the order of that in the spatial_countMat_list
 98 | - sc_count Reference scRNA-seq count data, each column is a cell and each row is a gene.
 99 | - sc_meta A data frame of meta data providing information on each cell in the sc_count, with each row representing the cell type and/or sample information of a specific cell. The row names of this data frame should match exactly with the column names of the sc_count data
100 | - ct.varname character, the name of the column in metaData that provides the cell type annotation information for IRIS to perform informed domain detection.
101 | - sample.varname character,the name of the column in metaData that specifies the sample information. If NULL, we just use the whole as one sample.
102 | - minCountGene Minimum counts for each gene in the spatial count data, default is 100
103 | - minCountSpot Minimum counts for each spatial location in the spatial count data, default is 5
104 | 
105 | ```r
106 | IRIS_object <- createIRISObject(
107 | spatial_countMat_list = spatial_countMat_list,
108 | spatial_location_list = spatial_location_list,
109 | sc_count = sc_count,
110 | sc_meta = sc_meta,
111 | ct.varname = ct.varname,
112 | sample.varname = sample.varname,
113 | minCountGene = 100,
114 | minCountSpot =5) 
115 | ```
116 | The spatial data are stored in `IRIS_object@spatial_countMat` and `IRIS_object@spatial_location` while the scRNA-seq data is stored in IRIS_object@sc_eset in the format of SingleCellExperiment. 
117 | 
118 | ### 2. Integrative spatial domain detection using IRIS
119 | Now we have everything stored in the IRIS object, we can use IRIS to perform the integrative and reference-informed spatial domain detection for spatial transcriptomics. IRIS is computationally fast and memory efficient. IRIS relies on an efficient optimization algorithm for constrained maximum likelihood estimation and is scalable to spatial transcriptomics with tens of thousands of spatial locations and tens of thousands of genes. For the example dataset with four tissue slices in 17780 spatial locations, it takes within 5 minutes to finish the analysis. 
120 | 
121 | ```r
122 | #### preselect the number of spatial domains 
123 | numCluster = 7
124 | #### perform the integrative and refernce-informed domain detection
125 | IRIS_object <- IRIS_spatial(IRIS_object,numCluster = numCluster)
126 | ```
127 | The results of detected domains are stored in `IRIS_obj@spatialDomain`. 
128 | ```r
129 | print(IRIS_object@spatialDomain[1:4,])
130 |                              Slice                    spotName        x
131 | 113.141318028x147.434748552 151507 113.141318028x147.434748552 113.1413
132 | 383.43835704x413.051319356  151507  383.43835704x413.051319356 383.4384
133 | 129.522956756x231.008108766 151507 129.522956756x231.008108766 129.5230
134 | 431.188133662x155.805585924 151507 431.188133662x155.805585924 431.1881
135 |                                    y IRIS_domain
136 | 113.141318028x147.434748552 147.4347           3
137 | 383.43835704x413.051319356  413.0513           1
138 | 129.522956756x231.008108766 231.0081           4
139 | 431.188133662x155.805585924 155.8056           6
140 | ```
141 | ### 3. Visualize the spatial domains detected by IRIS
142 | First, we jointly visualize the spatial domains detected by IRIS across multiple slices through scatter plot. In this plot, each panel represents on tissue slice with x and y axis represents the coordiates while each point is colored by their spatial domains.
143 | ```r
144 | #### set the colors. Here, I just use the colors in the manuscript, if the color is not provided, the function will use default color in the package. 
145 | colors = c("#ebe5c2", "#D57358", "#023047", "#F7CA71", "#1697a6", "#8bc6cc", "#C9DEC3")
146 | #### extract the domain labels detected by IRIS
147 | IRIS_domain =  IRIS_object@spatialDomain[,c("Slice","spotName","IRIS_domain")]
148 | #### relevel the spatial domains, to make it consistent with the orders from Layer 1 to Layer 6 to white matter.
149 | IRIS_domain$IRIS_domain = plyr::mapvalues(IRIS_domain$IRIS_domain,from = c(0:6), to = c(5,2,3,1,0,4,6))
150 | #### extract the spatial location information
151 | spatial_location = IRIS_object@spatialDomain[,c("x","y")]
152 | spatial_location$x = IRIS_object@spatialDomain$y
153 | spatial_location$y = -IRIS_object@spatialDomain$x #### make it consistent with many previous visualizations on this tissue. Note that this is only for visualization purpose.
154 | p1 = IRIS.visualize.domain(IRIS_domain,spatial_location,colors = colors,numCols = 4)
155 | print(p1)
156 | ```
157 | Here is an example output: 
158 | ![Example_Pie](Example_analysis_visualizeDomain.png)
159 | 
160 | ### 4. Visualize the cell type proportions seperately
161 | As a secondary output of IRIS, IRIS is also able to generate the cell type proportion distributions for each slice. 
162 | ```r
163 | #### Here we use the third slice 151509 as an example
164 | #### select the cell type that we are interested
165 | ct.visualize = c("Ast3","Ex6","Oli0","In7")
166 | #### visualize the spatial distribution of the cell type proportion
167 | library(viridis)
168 | #### set the color values
169 | colors = magma(256)
170 | #### extract the cell type proportion matrix for the example slice
171 | IRIS_prop = IRIS_object@IRIS_Prop
172 | IRIS_prop = IRIS_prop[IRIS_prop$Slice == "151509",]
173 | #### extract the spatial information matrix for the example slice
174 | IRIS_prop_location = IRIS_prop[,c("Slice","spotName","x","y")]
175 | #### This is only for visualization purpose
176 | IRIS_prop_location$x = IRIS_prop$y
177 | IRIS_prop_location$y = -IRIS_prop$x
178 | 
179 | p2 <- IRIS.visualize.eachProp(
180 | 	proportion = IRIS_prop,        
181 | 	spatial_location = IRIS_prop_location, 
182 | 	ct.visualize = ct.visualize,                 #### selected cell types to visualize
183 | 	colors = colors,                             #### if not provide, we will use the default colors
184 | 	numCols = 4)                                 #### number of columns in the figure panel
185 | print(p2)
186 | 
187 | ```
188 | Here is an example output: 
189 | <p align="left"> 
190 | <img src="Example_analysis_prop_slice3.png" width="700">
191 | </p>
192 | 


--------------------------------------------------------------------------------
/docs/documentation/05_Experiments.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | layout: page
 3 | title: Experiments
 4 | description: Link to download the example dataset
 5 | ---
 6 | 
 7 | Here are the code for runing analysis in IRIS manuscript. 
 8 | 
 9 | #### Data sets for experiments
10 | * Raw data can be downloaded through the link listed in the manuscript
11 | * [processed real data](https://drive.google.com/drive/folders/19q8qVoKDFS6d1u2IL5XAocLSJgkYIEhW)
12 | 
13 | #### Code for experiments
14 |   * [Human dorsolateral prefrontal cortex (DLPFC) 10x Visium data analysis with IRIS](https://yingma0107.github.io/IRIS/documentation/04_IRIS_Example.html)
15 |   * [Human squamous cell carcinoma (SCC) ST data analysis with IRIS](https://htmlpreview.github.io/?https://github.com/YingMa0107/IRIS/blob/master/vignettes/SCC_IRIS.html)
16 |   * [Mouse spermatogenesis Slide-seq data analysis with IRIS](https://htmlpreview.github.io/?https://github.com/YingMa0107/IRIS/blob/master/vignettes/SlideseqTestis_IRIS.html)
17 |   * [Mouse brain Vizgen MERFISH data analysis with IRIS](https://htmlpreview.github.io/?https://github.com/YingMa0107/IRIS/blob/master/vignettes/Vizgen_IRIS.html)
18 |   * [High resolution mouse olfactory bulb Stereo-seq data analysis with IRIS](https://htmlpreview.github.io/?https://github.com/YingMa0107/IRIS/blob/master/vignettes/Stereoseq_IRIS.html)
19 |   * [High resolution human breast cancer 10x Xenium data analysis with IRIS](https://htmlpreview.github.io/?https://github.com/YingMa0107/IRIS/blob/master/vignettes/Xenium_IRIS.html)
20 |    * [Reference-free and single versions of IRIS analysis](https://htmlpreview.github.io/?https://github.com/YingMa0107/IRIS/blob/master/vignettes/IRISfree-single.html)
21 | 
22 | 
23 |   
24 | 


--------------------------------------------------------------------------------
/docs/documentation/Example_analysis_prop_slice3.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/YingMa0107/IRIS/79285560385a63fd3094251cfe7306ccf8389107/docs/documentation/Example_analysis_prop_slice3.png


--------------------------------------------------------------------------------
/docs/documentation/Example_analysis_visualizeDomain.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/YingMa0107/IRIS/79285560385a63fd3094251cfe7306ccf8389107/docs/documentation/Example_analysis_visualizeDomain.png


--------------------------------------------------------------------------------
/docs/documentation/screenshot_zhoulab.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/YingMa0107/IRIS/79285560385a63fd3094251cfe7306ccf8389107/docs/documentation/screenshot_zhoulab.png


--------------------------------------------------------------------------------
/docs/index.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | layout: full
 3 | homepage: true
 4 | disable_anchors: true
 5 | description: Integrative and Reference-Informed Spatial Domain Detection for Spatial Transcriptomics 
 6 | ---
 7 | ## IRIS Overview
 8 | <p align="center">
 9 | <img src="IRIS_logo1.png" width="650" height="400">
10 | </p>
11 | We developed a statistical method for Integrative and Reference-Informed Spatial Domain Detection for Spatial Transcriptomics. IRIS is a reference-informed integrative method for detecting spatial domains on multiple tissue slices from spatial transcriptomics with spot-level, single-cell level, or subcellular level resolutions. IRIS builds upon the fact that each spatial domain on the tissue is characterized by a unique composition of cell types and that similar composition is observed for the same spatial domain across different slices of the same tissue 28,29. Consequently, IRIS integrates a reference scRNA-seq data to inform and characterize the cell type composition on the tissue of spatial transcriptomics for accurate and interpretable spatial domain detection. In the process, IRIS accommodates cell type compositional similarity across locations within the same slice and across different slices on the same domain to borrow information both within and between tissue slices for integrative and accurate spatial domain detection. Importantly, IRIS comes with an efficient optimization framework with multiple algebraic innovations for scalable computation and can easily handle multiple spatial transcriptomics datasets with millions of spatial locations and tens of thousands of genes. IRIS is implemented as an open-source R package, freely available at www.xzlab.org/software.html. 
12 | 
13 | 
14 | Installation
15 | ------------
16 | You can install the released version of IRIS from Github with the following code, for more installation details or solutions that might solve related issues (specifically MacOS system) see the [link](https://yingma0107.github.io/IRIS/documentation/02_installation.html).
17 | 
18 | ## Dependencies 
19 | * R version >= 4.2.2.
20 | * Dependent R packages: Rcpp (>= 1.0.9), RcppArmadillo, SingleCellExperiment, SummarizedExperiment, methods, Matrix, MCMCpack, fields, wrMisc, RANN, stats, ggplot2, grDevices, reshape2
21 | 
22 | 
23 | ``` r
24 | # install devtools if necessary
25 | install.packages('devtools')
26 | 
27 | # install the IRIS package
28 | devtools::install_github('YingMa0107/IRIS')
29 | 
30 | # load package
31 | library(IRIS)
32 | 
33 | ```
34 | The R package has been installed successfully on Operating systems: 
35 | * macOS Catalina 10.15, macOS Monterey 12.4
36 | * Ubuntu 18.04.6 LTS
37 | * Windows 10
38 | 
39 | # Issues
40 | All feedback, bug reports and suggestions are warmly welcomed! Please make sure to raise issues with a detailed and reproducible example and also please provide the output of your sessionInfo() in R! 
41 | 
42 | How to cite `IRIS`
43 | -------------------
44 | Ying Ma, Xiang Zhou. Integrative and Reference-Informed Spatial Domain Detection for Spatial Transcriptomics, 2023. 
45 | 
46 | How to use `IRIS`
47 | -------------------
48 | Example Analysis with IRIS: [here](https://yingma0107.github.io/IRIS/documentation/04_IRIS_Example.html).
49 | 


--------------------------------------------------------------------------------
/docs/style.css:
--------------------------------------------------------------------------------
  1 | div.author{
  2 | 	display: inline-block;
  3 | 	vertical-align: top;
  4 | 	padding-right: 2em;
  5 | }
  6 | 
  7 | body, td {
  8 |    background-color: white;
  9 | }
 10 | 
 11 | /* element spacing */
 12 | 
 13 | p, pre { 
 14 |   margin: 0em 0em 1em;
 15 | }
 16 | 
 17 | /* center images and tables */
 18 | img, table {
 19 |   margin: 0em auto 1em;
 20 | }
 21 | 
 22 | p {
 23 |   text-align: justify;
 24 | }
 25 | 
 26 | tt, code, pre {
 27 |    font-family: 'DejaVu Sans Mono', 'Droid Sans Mono', 'Lucida Console', Consolas, Monaco, monospace;
 28 | }
 29 | 
 30 | h1, h2, h3, h4, h5, h6 { 
 31 |   font-family: Helvetica, Arial, sans-serif;
 32 |   margin: 1.2em 0em 0.6em 0em;
 33 |   font-weight: bold;
 34 | 
 35 | }
 36 | 
 37 | h1.title {
 38 |   color: #87b13f;
 39 |   line-height: 1.1em;
 40 |   margin-top: 0px;
 41 |   border-bottom: 0px;
 42 | }
 43 | 
 44 | h1 {
 45 |   font-size: 160%;
 46 |   font-weight: normal;
 47 |   line-height: 1.1em;
 48 |   padding-bottom: 2px;
 49 |   border-bottom: 3px solid;
 50 | }
 51 | 
 52 | h2 {
 53 |   font-size: 130%;
 54 | }
 55 | 
 56 | h1, h2, h3 {
 57 | /*  color: #1a81c2; */
 58 | }
 59 | 
 60 | h3, h4, h5, h6 {
 61 |   font-size:115%;
 62 | } /* not expecting to dive deeper than four levels on a single page */
 63 | 
 64 | /* links are simply blue, hovering slightly less blue */
 65 | /*a { color: #1a81c2; }
 66 | a:active { outline: none; }
 67 | a:visited { color: #1a81c2; }
 68 | a:hover { color: #4c94c2; }
 69 | */
 70 | 
 71 | pre, img {
 72 |   max-width: 100%;
 73 |   display: block;
 74 | }
 75 | 
 76 | pre {
 77 |   border: 0px none;
 78 |   background-color: #F8F8F8;
 79 |   white-space: pre;
 80 |   overflow-x: auto;
 81 | }
 82 | 
 83 | pre code {
 84 |   border: 1px #aaa dashed;
 85 |   background-color: white;
 86 |   display: block;
 87 |   padding: 1em;  
 88 |   color: #111;
 89 |   overflow-x: inherit;
 90 | }
 91 | 
 92 | /* markdown v1 */
 93 | pre code[class] {
 94 |   background-color: inherit;
 95 | }
 96 | 
 97 | /* markdown v2 */
 98 | pre[class] code {
 99 |   background-color: inherit;
100 | }
101 | 
102 | /* formatting of inline code */
103 | code { 
104 |   background-color: transparent;
105 |   color: #87b13f;
106 |   font-size: 92%;
107 | }
108 | 
109 | /* formatting of tables */
110 | 
111 | table, td, th {
112 |   border: none;
113 |   padding: 0 0.5em;
114 | }
115 | 
116 | /* alternating row colors */
117 | tbody tr:nth-child(odd) td {
118 |   background-color: #F8F8F8;
119 | }
120 | 
121 | blockquote {
122 |    color:#666666;
123 |    margin:0;
124 |    padding-left: 1em;
125 |    border-left: 0.5em #EEE solid;
126 | }
127 | 
128 | hr {
129 |    height: 0px;
130 |    border-bottom: none;
131 |    border-top-width: thin;
132 |    border-top-style: dotted;
133 |    border-top-color: #999999;
134 | }
135 | 
136 | span.header-section-number {
137 |   padding-right: 1em;
138 | }
139 | 
140 | span.toc-section-number::after {
141 |     content: "  ";
142 |     white-space: pre;
143 | }
144 | 
145 | @media print {
146 |    * {
147 |       background: transparent !important;
148 |       color: black !important;
149 |       filter:none !important;
150 |       -ms-filter: none !important;
151 |    }
152 | 
153 |    body {
154 |       font-size:12pt;
155 |       max-width:100%;
156 |    }
157 | 
158 |    a, a:visited {
159 |       text-decoration: underline;
160 |    }
161 | 
162 |    hr {
163 |       visibility: hidden;
164 |       page-break-before: always;
165 |    }
166 | 
167 |    pre, blockquote {
168 |       padding-right: 1em;
169 |       page-break-inside: avoid;
170 |    }
171 | 
172 |    tr, img {
173 |       page-break-inside: avoid;
174 |    }
175 | 
176 |    img {
177 |       max-width: 100% !important;
178 |    }
179 | 
180 |    @page :left {
181 |       margin: 15mm 20mm 15mm 10mm;
182 |    }
183 | 
184 |    @page :right {
185 |       margin: 15mm 10mm 15mm 20mm;
186 |    }
187 | 
188 |    p, h2, h3 {
189 |       orphans: 3; widows: 3;
190 |    }
191 | 
192 |    h2, h3 {
193 |       page-break-after: avoid;
194 |    }
195 | }
196 | 


--------------------------------------------------------------------------------
/man/IRIS-class.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/utilities.R
 3 | \docType{class}
 4 | \name{IRIS-class}
 5 | \alias{IRIS-class}
 6 | \title{Each IRIS object has a number of slots which store information. Key slots to access
 7 | are listed below.}
 8 | \description{
 9 | Each IRIS object has a number of slots which store information. Key slots to access
10 | are listed below.
11 | }
12 | \section{Slots}{
13 | 
14 | \describe{
15 | \item{\code{countList}}{A list of spatial count data matrix. Each spatial count data with rows as the genes and column as measured spatial locations}
16 | 
17 | \item{\code{locationList}}{A list of spatial location matrix. Each spatial location with rows as the measured spatial locations matched with those in the spatial_countMat_list and columns as theccccczzzz}
18 | 
19 | \item{\code{spatialDomain}}{A meta data frame of spatial domain labels detected by IRIS.}
20 | 
21 | \item{\code{project}}{The name of the project, default is "IRIS".}
22 | 
23 | \item{\code{IRIS_Prop}}{A meta data frame of concatenated V matrix estimated by IRIS.}
24 | 
25 | \item{\code{internal_info}}{The neccessary information that are used by IRIS computation.}
26 | }}
27 | 
28 | 


--------------------------------------------------------------------------------
/man/IRIS-package.Rd:
--------------------------------------------------------------------------------
 1 | \name{IRIS-package}
 2 | \alias{IRIS-package}
 3 | \alias{IRIS}
 4 | \docType{package}
 5 | \title{\packageTitle{IRIS}}
 6 | \description{\packageDescription{IRIS}}
 7 | \section{Package Content}{\packageIndices{IRIS}}
 8 | \author{\packageAuthor{IRIS}}
 9 | \section{Maintainer}{\packageMaintainer{IRIS}}
10 | \keyword{package}
11 | 


--------------------------------------------------------------------------------
/man/IRIS.visualize.domain.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/visualization.R
 3 | \name{IRIS.visualize.domain}
 4 | \alias{IRIS.visualize.domain}
 5 | \title{Visualize the spatial domains}
 6 | \usage{
 7 | IRIS.visualize.domain(IRIS_domain, spatial_location, colors = NULL, numCols)
 8 | }
 9 | \arguments{
10 | \item{IRIS_domain}{Data frame, spatial domains infered by IRIS across multiple slices. The column "IRIS_domain" contains the domain label. With each row representing one spatial location from each slice.}
11 | 
12 | \item{spatial_location}{Data frame, spatial location information for each spot in IRIS_domain in each tissue slice. The row names must be consistent with the row names in the data frame IRIS_domain. The data contains two columns, with the first column representing the x coordinates, with the second column representing the y coordinates}
13 | 
14 | \item{colors}{Vector of color names that you want to use, if NULL, we will use the default color.}
15 | 
16 | \item{numCols}{Numeric, number of figure panels, it depends on the number of tissue slices you want to visualize.}
17 | }
18 | \value{
19 | Returns a ggplot2 figure.
20 | }
21 | \description{
22 | Visualize the spatial domains
23 | }
24 | 


--------------------------------------------------------------------------------
/man/IRIS.visualize.eachProp.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/visualization.R
 3 | \name{IRIS.visualize.eachProp}
 4 | \alias{IRIS.visualize.eachProp}
 5 | \title{Visualize the spatial distribution of cell type proportion}
 6 | \usage{
 7 | IRIS.visualize.eachProp(
 8 |   proportion,
 9 |   spatial_location,
10 |   ct.visualize = ct.visualize,
11 |   colors = c("lightblue", "lightyellow", "red"),
12 |   numCols
13 | )
14 | }
15 | \arguments{
16 | \item{proportion}{Data frame, cell type proportion estimated by IRIS in either original resolution or enhanced resolution.}
17 | 
18 | \item{spatial_location}{Data frame, spatial location information.}
19 | 
20 | \item{ct.visualize}{Vector of selected cell type names that are interested to visualize}
21 | 
22 | \item{colors}{Vector of color names that you want to use, if NULL, we will use the default color scale c("lightblue","lightyellow","red")}
23 | 
24 | \item{numCols}{Numeric, number of columns in the figure panel, it depends on the number of cell types you want to visualize.}
25 | }
26 | \value{
27 | Returns a ggplot2 figure.
28 | }
29 | \description{
30 | Visualize the spatial distribution of cell type proportion
31 | }
32 | 


--------------------------------------------------------------------------------
/man/IRIS_Marker_iter.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/RcppExports.R
 3 | \name{IRIS_Marker_iter}
 4 | \alias{IRIS_Marker_iter}
 5 | \title{IRIS_ref function}
 6 | \usage{
 7 | IRIS_Marker_iter(XList, BIn, AList, VList, StrList, MuIn)
 8 | }
 9 | \arguments{
10 | \item{XList}{The input list of normalized spatial data}
11 | 
12 | \item{BIn}{The input list of cell type specific basis matrix B}
13 | 
14 | \item{AList}{The constructed Ajacency matrix for each tissue slice}
15 | 
16 | \item{VList}{List of initial matrix of cell type compositions V}
17 | 
18 | \item{StrList}{List of initial spatial domains for each tissue slice}
19 | 
20 | \item{MuIn}{Initial matrix of mean cell type proportion across slices}
21 | }
22 | \value{
23 | A list
24 | }
25 | \description{
26 | IRIS_ref function
27 | }
28 | 


--------------------------------------------------------------------------------
/man/IRIS_ref_iter.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/RcppExports.R
 3 | \name{IRIS_ref_iter}
 4 | \alias{IRIS_ref_iter}
 5 | \title{IRIS_ref function}
 6 | \usage{
 7 | IRIS_ref_iter(XList, BIn, AList, VList, StrList, MuIn)
 8 | }
 9 | \arguments{
10 | \item{XList}{The input list of normalized spatial data}
11 | 
12 | \item{BIn}{The input list of cell type specific basis matrix B}
13 | 
14 | \item{AList}{The constructed Ajacency matrix for each tissue slice}
15 | 
16 | \item{VList}{List of initial matrix of cell type compositions V}
17 | 
18 | \item{StrList}{List of initial spatial domains for each tissue slice}
19 | 
20 | \item{MuIn}{Initial matrix of mean cell type proportion across slices}
21 | }
22 | \value{
23 | A list
24 | }
25 | \description{
26 | IRIS_ref function
27 | }
28 | 


--------------------------------------------------------------------------------
/man/IRIS_spatial.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/IRIS.run.R
 3 | \name{IRIS_spatial}
 4 | \alias{IRIS_spatial}
 5 | \title{Accurate and Efficient Integrative Reference-Informed Spatial Domain Detection for Spatial Transcriptomics}
 6 | \usage{
 7 | IRIS_spatial(IRIS_object, numCluster)
 8 | }
 9 | \arguments{
10 | \item{IRIS_object}{IRIS object create by the createIRISObject function}
11 | 
12 | \item{numCluster}{A numeric value indicating the number of clusters}
13 | }
14 | \value{
15 | Returns a IRIS object with domain labels stored in IRIS_object@spatial_domain for each tissue slice.
16 | }
17 | \description{
18 | Accurate and Efficient Integrative Reference-Informed Spatial Domain Detection for Spatial Transcriptomics
19 | }
20 | 


--------------------------------------------------------------------------------
/man/IRISfree-class.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/utilities.R
 3 | \docType{class}
 4 | \name{IRISfree-class}
 5 | \alias{IRISfree-class}
 6 | \title{Each IRISfree object has a number of slots which store information. Key slots to access
 7 | are listed below.}
 8 | \description{
 9 | Each IRISfree object has a number of slots which store information. Key slots to access
10 | are listed below.
11 | }
12 | \section{Slots}{
13 | 
14 | \describe{
15 | \item{\code{countList}}{A list of spatial count data matrix. Each spatial count data with rows as the genes and column as measured spatial locations}
16 | 
17 | \item{\code{locationList}}{A list of spatial location matrix. Each spatial location with rows as the measured spatial locations matched with those in the spatial_countMat_list and columns as theccccczzzz}
18 | 
19 | \item{\code{spatialDomain}}{A meta data frame of spatial domain labels detected by IRIS.}
20 | 
21 | \item{\code{project}}{The name of the project, default is "IRIS".}
22 | 
23 | \item{\code{IRIS_Prop}}{A meta data frame of concatenated V matrix estimated by IRIS.}
24 | 
25 | \item{\code{internal_info}}{The neccessary information that are used by IRIS computation.}
26 | }}
27 | 
28 | 


--------------------------------------------------------------------------------
/man/createA.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/IRIS.run.R
 3 | \name{createA}
 4 | \alias{createA}
 5 | \title{Construct the adjacency matrix for each tissue slice}
 6 | \usage{
 7 | createA(locationList)
 8 | }
 9 | \arguments{
10 | \item{locationList}{a list of spatial location matrix}
11 | }
12 | \value{
13 | Return a list of Ajacency matrix
14 | }
15 | \description{
16 | Construct the adjacency matrix for each tissue slice
17 | }
18 | 


--------------------------------------------------------------------------------
/man/createIRISObject.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/utilities.R
 3 | \name{createIRISObject}
 4 | \alias{createIRISObject}
 5 | \title{Create the IRIS object}
 6 | \usage{
 7 | createIRISObject(
 8 |   spatial_countMat_list,
 9 |   spatial_location_list,
10 |   sc_count,
11 |   sc_meta,
12 |   ct.varname,
13 |   sample.varname,
14 |   markerList = NULL,
15 |   version = "IRIS",
16 |   minCountGene = 100,
17 |   minCountSpot = 5
18 | )
19 | }
20 | \arguments{
21 | \item{spatial_countMat_list}{A list of raw spatial resolved transcriptomics data. In each spatial transcriptomics data, it is a sparse matrix with each column is a spatial location, and each row is a gene.}
22 | 
23 | \item{spatial_location_list}{A list of spatial location data frames, with two columns representing the x and y coordinates of the spatial location (The column names must contain "x" and "y"). The rownames of this data frame should match eaxctly with the columns of the corresponding spatial_count in the spatial_countMat_list.}
24 | 
25 | \item{sc_count}{Reference scRNA-seq count data, each column is a cell and each row is a gene.}
26 | 
27 | \item{sc_meta}{A data frame of meta data providing information on each cell in the sc_count, with each row representing the cell type and/or sample information of a specific cell. The row names of this data frame should match exactly with the column names of the sc_count data}
28 | 
29 | \item{ct.varname}{character, the name of the column in metaData that provides the cell type annotation information for IRIS to perform informed domain detection.}
30 | 
31 | \item{sample.varname}{character,the name of the column in metaData that specifies the sample information. If NULL, we just use the whole as one sample.}
32 | 
33 | \item{markerList}{a list of marker genes, with each element of the list being the vector of cell type specific marker genes, default is NULL}
34 | 
35 | \item{version}{A character indicating whether to use IRIS, IRISfree or IRISsingle. The default version is "IRIS". We highly recommend using the original IRIS version.}
36 | 
37 | \item{minCountGene}{Minimum counts for each gene in the spatial count data}
38 | 
39 | \item{minCountSpot}{Minimum counts for each spatial location in the spatial count data}
40 | }
41 | \value{
42 | Returns IRIS object with filtered spatial count list, location list and reference scRNA-seq dataset.
43 | }
44 | \description{
45 | Create the IRIS object
46 | }
47 | 


--------------------------------------------------------------------------------
/man/createscRef.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/IRIS.run.R
 3 | \name{createscRef}
 4 | \alias{createscRef}
 5 | \title{Construct the mean gene expression basis matrix (B), this is the faster version}
 6 | \usage{
 7 | createscRef(
 8 |   countMat,
 9 |   metadata,
10 |   ct.select = NULL,
11 |   ct.varname,
12 |   sample.varname = NULL
13 | )
14 | }
15 | \arguments{
16 | \item{countMat}{single-cell RNA-seq count data as the reference}
17 | 
18 | \item{metadata}{meta data containing the cell type annotations in the scRNA-seq reference data. The rows matched with the columns of countMat}
19 | 
20 | \item{ct.select}{vector of cell type names that you are interested in to deconvolute, default as NULL. If NULL, then use all cell types provided by single cell dataset;}
21 | 
22 | \item{ct.varname}{character, the name of the column in metaData that specifies the cell type annotation information}
23 | 
24 | \item{sample.varname}{character,the name of the column in metaData that specifies the sample information. If NULL, we just use the whole as one sample.}
25 | }
26 | \value{
27 | Return a list of basis (B) matrix
28 | }
29 | \description{
30 | Construct the mean gene expression basis matrix (B), this is the faster version
31 | }
32 | 


--------------------------------------------------------------------------------
/man/getConcated.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/IRIS.run.R
 3 | \name{getConcated}
 4 | \alias{getConcated}
 5 | \title{Construct the concatenated matrix from V across tissue_slices}
 6 | \usage{
 7 | getConcated(VList, locationList, sliceNames)
 8 | }
 9 | \arguments{
10 | \item{VList}{a list of V matrix across all tissue slices}
11 | 
12 | \item{locationList}{a list of location matrix matched with the spatial locations in the VList}
13 | 
14 | \item{sliceNames}{a vector of slice names corresponding to the input tissue slices}
15 | }
16 | \value{
17 | Return a list of Ajacency matrix
18 | }
19 | \description{
20 | Construct the concatenated matrix from V across tissue_slices
21 | }
22 | 


--------------------------------------------------------------------------------
/man/getMu_and_STR.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/IRIS.run.R
 3 | \name{getMu_and_STR}
 4 | \alias{getMu_and_STR}
 5 | \title{get the Mu and spatial domain label list}
 6 | \usage{
 7 | getMu_and_STR(
 8 |   CommonCellTypes,
 9 |   TotalClusters,
10 |   MatrixCombined,
11 |   nSlices,
12 |   sliceNames
13 | )
14 | }
15 | \arguments{
16 | \item{CommonCellTypes}{cell types in the reference matrix}
17 | 
18 | \item{TotalClusters}{number of total spatial odmains across all tissue slices}
19 | 
20 | \item{MatrixCombined}{a concatenated matrix of V matrix across tissue slices}
21 | 
22 | \item{nSlices}{number of total slices analyzed}
23 | 
24 | \item{sliceNames}{names of the tissue slices in the count list}
25 | }
26 | \value{
27 | Return a list of Mu and the spatial domain labels for each tissue slice
28 | }
29 | \description{
30 | get the Mu and spatial domain label list
31 | }
32 | 


--------------------------------------------------------------------------------
/man/kmeansFunc_Initialize.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/IRIS.run.R
 3 | \name{kmeansFunc_Initialize}
 4 | \alias{kmeansFunc_Initialize}
 5 | \title{Initialize the spatial domain labels}
 6 | \usage{
 7 | kmeansFunc_Initialize(data, k)
 8 | }
 9 | \arguments{
10 | \item{data}{Contatnated matrix from all tissue slices.}
11 | 
12 | \item{k}{number of spatial domains}
13 | }
14 | \value{
15 | a list of the kmeans clustering results
16 | }
17 | \description{
18 | Initialize the spatial domain labels
19 | }
20 | 


--------------------------------------------------------------------------------
/man/kmeansFunc_Iter.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/IRIS.run.R
 3 | \name{kmeansFunc_Iter}
 4 | \alias{kmeansFunc_Iter}
 5 | \title{Cluster the spatial domain labels in each iterartion}
 6 | \usage{
 7 | kmeansFunc_Iter(data, k, centers_old = NULL)
 8 | }
 9 | \arguments{
10 | \item{data}{Contatnated matrix from all tissue slices.}
11 | 
12 | \item{k}{number of spatial domains}
13 | 
14 | \item{centers_old}{centers from last iteration}
15 | }
16 | \value{
17 | a list of the kmeans clustering results and the centers for this iteration
18 | }
19 | \description{
20 | Cluster the spatial domain labels in each iterartion
21 | }
22 | 


--------------------------------------------------------------------------------
/man/sc_QC.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/utilities.R
 3 | \name{sc_QC}
 4 | \alias{sc_QC}
 5 | \title{Quality control of scRNA-seq count data}
 6 | \usage{
 7 | sc_QC(
 8 |   sc_count,
 9 |   sc_meta,
10 |   ct.varname,
11 |   sample.varname = NULL,
12 |   min.cells = 0,
13 |   min.genes = 0
14 | )
15 | }
16 | \arguments{
17 | \item{sc_count}{Raw scRNAseq count data, each column is a cell and each row is a gene.}
18 | 
19 | \item{sc_meta}{data frame, metaData with "ct.varname" specify the cell type annotation information and "sample.varname" specify the sample information}
20 | 
21 | \item{ct.varname}{character, the name of the column in metaData that specifies the cell type annotation information}
22 | 
23 | \item{sample.varname}{character,the name of the column in metaData that specifies the sample information. If NULL, we just use the whole as one sample.}
24 | 
25 | \item{min.cells}{numeric, we filtered out the non-expressed cells.}
26 | 
27 | \item{min.genes}{numeric we filtered out the non-expressed genes}
28 | }
29 | \value{
30 | Return the filtered scRNA-seq data and meta data stored in a S4 class (SingleCellExperiment)
31 | }
32 | \description{
33 | Quality control of scRNA-seq count data
34 | }
35 | 


--------------------------------------------------------------------------------
/man/selectInfo.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/IRIS.run.R
 3 | \name{selectInfo}
 4 | \alias{selectInfo}
 5 | \title{Select Informative Genes used in the deconvolution}
 6 | \usage{
 7 | selectInfo(Basis, sc_eset, commonGene, ct.select, ct.varname)
 8 | }
 9 | \arguments{
10 | \item{Basis}{Reference basis matrix.}
11 | 
12 | \item{sc_eset}{scRNAseq data along with meta data stored in the S4 class format (SingleCellExperiment).}
13 | 
14 | \item{commonGene}{common genes between scRNAseq count data and spatial resolved transcriptomics data.}
15 | 
16 | \item{ct.select}{vector of cell type names that you are interested in to deconvolute, default as NULL. If NULL, then use all cell types provided by single cell dataset;}
17 | 
18 | \item{ct.varname}{character, the name of the column in metaData that specifies the cell type annotation information}
19 | }
20 | \value{
21 | a vector of informative genes selected
22 | }
23 | \description{
24 | Select Informative Genes used in the deconvolution
25 | }
26 | 


--------------------------------------------------------------------------------
/src/IRIS_ref_iter.cpp:
--------------------------------------------------------------------------------
  1 | #include <iostream>
  2 | #include <fstream>
  3 | #define ARMA_64BIT_WORD 1
  4 | #include <RcppArmadillo.h>
  5 | // [[Rcpp::depends(RcppArmadillo)]]
  6 | // [[Rcpp::plugins(cpp11)]]
  7 | 
  8 | #include <R.h>
  9 | #include <Rmath.h>
 10 | #include <cmath>
 11 | #include <stdio.h>
 12 | #include <stdlib.h>
 13 | #include <cstring>
 14 | #include <ctime>
 15 | #include <Rcpp.h>
 16 | 
 17 | using namespace std;
 18 | using namespace arma;
 19 | using namespace Rcpp;
 20 | 
 21 | #define ARMA_DONT_PRINT_ERRORS
 22 | 
 23 | // calculate objective function
 24 | double calculateObject(List &XList,List &VList,List &AList,List &StrList,arma::mat &B,arma::mat &Mu,double beta,double lambda){
 25 |     double obj = 0;
 26 |     int nSlice = XList.size();
 27 |     for(int islice = 0; islice < nSlice; ++islice){
 28 |         double objt = 0;
 29 |         arma::sp_mat Xt = XList(islice);
 30 |         arma::mat Vt = VList(islice);
 31 |         arma::sp_mat At = AList(islice);
 32 |         arma::sp_mat colsum_At = arma::sum(At, 1);
 33 |         arma::sp_mat Dt((int)Vt.n_rows,(int)Vt.n_rows);
 34 |         Dt.diag() = colsum_At;
 35 |         arma::sp_mat Lt = Dt - At;
 36 |         double Obj_NMF = norm(Xt - B * Vt.t(),"fro");
 37 |         arma::vec vecStr_t = StrList(islice);
 38 |         arma::vec UniqueStr_t = arma::unique(vecStr_t);
 39 |         double Obj_V = 0.0;
 40 |         for(int istr : UniqueStr_t){
 41 |             uvec indexStr = find(vecStr_t == istr);
 42 |             int NspotsInStr = indexStr.size();
 43 |             arma::vec vecOnetnr = ones<vec>(NspotsInStr);
 44 |             arma::vec VconstraintStr = Vt.rows(indexStr).t() * vecOnetnr / NspotsInStr - Mu.col(istr);
 45 |             double Obj_VStr = norm(VconstraintStr,2); // norm is the sqrt norm
 46 |             Obj_V = Obj_V + Obj_VStr * Obj_VStr;
 47 | 
 48 |         }
 49 |         //double Obj_NMF = norm(mainNMF,"fro");
 50 |         objt = Obj_NMF * Obj_NMF + beta * Obj_V + lambda * trace(Vt.t() * Lt * Vt);
 51 |         obj = obj + objt;
 52 |     }
 53 |     return obj;
 54 | 
 55 | }
 56 | 
 57 | 
 58 | arma::mat calc_VtDt(arma::sp_mat &colsum_At, arma::mat &Vt, arma::uvec &indexStr){
 59 |     arma::vec colsum_At_dense = vec(colsum_At.col(0));
 60 |     arma::mat res = Vt.rows(indexStr);
 61 |     res.each_col() %= colsum_At_dense.elem(indexStr);
 62 |     return(res);
 63 | }
 64 | 
 65 | 
 66 | //*******************************************************************//
 67 | // IRIS for Accurate and Scalable Spatial Domain Detection via Integrated Reference-Informed Segmentation for Spatial transcriptomics //
 68 | //*******************************************************************//
 69 | //' IRIS_ref function 
 70 | //' @param XList The input list of normalized spatial data
 71 | //' @param BIn The input list of cell type specific basis matrix B
 72 | //' @param AList The constructed Ajacency matrix for each tissue slice
 73 | //' @param VList List of initial matrix of cell type compositions V
 74 | //' @param StrList List of initial spatial domains for each tissue slice
 75 | //' @param MuIn Initial matrix of mean cell type proportion across slices
 76 | //'
 77 | //' @return A list
 78 | //'
 79 | //' @export
 80 | // [[Rcpp::export]]
 81 | SEXP IRIS_ref_iter(Rcpp::List &XList, SEXP BIn,Rcpp::List &AList,Rcpp::List VList, Rcpp::List StrList,SEXP MuIn)
 82 | {    
 83 |     try {
 84 |         arma::mat B = as<mat>(BIn); 
 85 |         double beta = 1000;
 86 |         double lambda = 2000;
 87 |         arma::mat Mu = as<mat>(MuIn);// with each row represents the cell type and each column represents the structure
 88 |         int nSlice = XList.size();
 89 |         // initialize the objective function
 90 |         double obj = 0;         
 91 |         // iterate through the slices
 92 |         arma::mat Mu_Slice = zeros<mat>((int)Mu.n_rows,(int)Mu.n_cols);
 93 |         for(int islice = 0; islice < nSlice; ++islice){
 94 |             arma::sp_mat Xt = XList(islice);
 95 |             arma::mat Vt = VList(islice);
 96 |             int Nt = (int)Xt.n_cols; // number of spatial sample points for the t-th slice
 97 |             arma::vec vecOnet = ones<vec>(Nt);
 98 |             arma::sp_mat At = AList(islice);
 99 |             arma::sp_mat colsum_At = arma::sum(At, 1);
100 |             arma::sp_mat Dt((int)Vt.n_rows,(int)Vt.n_rows);
101 |             Dt.diag() = colsum_At;
102 |             // update Vt
103 |             arma::vec vecStr_t = StrList(islice);
104 |             arma::vec UniqueStr_t = unique(vecStr_t);
105 |             arma::mat Mu_Str = zeros<mat>((int)Mu.n_rows,(int)Mu.n_cols);
106 |             for(int istr : UniqueStr_t){
107 |                 uvec indexStr = find(vecStr_t == istr);
108 |                 uvec notIndexStr = find(vecStr_t != istr);
109 |                 int NspotsInStr = indexStr.size();
110 |                 arma::vec vecOnetnr = ones<vec>(NspotsInStr);
111 |                 arma::mat vecOnetnrMat = ones<mat>(NspotsInStr,NspotsInStr);
112 |                 arma::mat VtDt = calc_VtDt(colsum_At,Vt,indexStr);
113 |                 arma::mat VtAt = At.cols(indexStr).t() * Vt;
114 |                 arma::mat nomUpdateVtStr = (Xt.cols(indexStr).t() * B + beta / NspotsInStr * (vecOnetnr * Mu.col(istr).t()) + lambda * VtAt);
115 |                 arma::mat denomUpdateVtStr = (Vt.rows(indexStr) * B.t() * B + beta / NspotsInStr / NspotsInStr * vecOnetnrMat * Vt.rows(indexStr) + lambda * VtDt);
116 |                 arma::mat updateVtStr = nomUpdateVtStr / denomUpdateVtStr;
117 |                 Vt.rows(indexStr) = Vt.rows(indexStr) % updateVtStr;
118 |                 arma::vec mean_VtStr = mean(Vt.rows(indexStr), 0).t();
119 |                 Mu_Str.col(istr) = mean_VtStr; 
120 |             }
121 |             VList(islice) = Vt;
122 |             Mu_Slice = Mu_Slice + Mu_Str;
123 |         }
124 |         // update mu
125 |         Mu = Mu_Slice / nSlice;
126 |         // calculate objective function
127 |         obj = calculateObject(XList,VList,AList,StrList,B,Mu,beta,lambda);
128 |        return List::create(
129 |                            Named("VList") = VList,
130 |                            Named("Mu") = Mu,
131 |                            Named("Obj") = obj);
132 |         }//end try 
133 |         catch (std::exception &ex)
134 |         {
135 |             forward_exception_to_r(ex);
136 |         }
137 |         catch (...)
138 |         {
139 |             ::Rf_error("C++ exception (unknown reason)...");
140 |         }
141 |         return R_NilValue;
142 | } // end funcs
143 | 
144 | 
145 | //*******************************************************************//
146 | // IRIS for Accurate and Scalable Spatial Domain Detection via Integrated Reference-Informed Segmentation for Spatial transcriptomics //
147 | //*******************************************************************//
148 | //' IRIS_ref function 
149 | //' @param XList The input list of normalized spatial data
150 | //' @param BIn The input list of cell type specific basis matrix B
151 | //' @param AList The constructed Ajacency matrix for each tissue slice
152 | //' @param VList List of initial matrix of cell type compositions V
153 | //' @param StrList List of initial spatial domains for each tissue slice
154 | //' @param MuIn Initial matrix of mean cell type proportion across slices
155 | //'
156 | //' @return A list
157 | //'
158 | //' @export
159 | // [[Rcpp::export]]
160 | SEXP IRIS_Marker_iter(Rcpp::List &XList, SEXP BIn,Rcpp::List &AList,Rcpp::List VList, Rcpp::List StrList,SEXP MuIn)
161 | {    
162 |     try {
163 |         arma::mat B = as<mat>(BIn); 
164 |         double beta = 1000;
165 |         double lambda = 2000;
166 |         arma::mat Mu = as<mat>(MuIn);// with each row represents the cell type and each column represents the structure
167 |         int nSlice = XList.size();
168 |         // initialize the objective function
169 |         double obj = 0;         
170 |         // iterate through the slices
171 |         arma::mat Mu_Slice = zeros<mat>((int)Mu.n_rows,(int)Mu.n_cols);
172 |         arma::mat XtVt_sum = zeros<mat>((int)B.n_rows,(int)B.n_cols);
173 |         arma::mat BVtV_sum = zeros<mat>((int)B.n_rows,(int)B.n_cols);
174 |         for(int islice = 0; islice < nSlice; ++islice){
175 |             arma::sp_mat Xt = XList(islice);
176 |             arma::mat Vt = VList(islice);
177 |             int Nt = (int)Xt.n_cols; // number of spatial sample points for the t-th slice
178 |             arma::vec vecOnet = ones<vec>(Nt);
179 |             arma::sp_mat At = AList(islice);
180 |             arma::sp_mat colsum_At = arma::sum(At, 1);
181 |             arma::sp_mat Dt((int)Vt.n_rows,(int)Vt.n_rows);
182 |             Dt.diag() = colsum_At;
183 |             // update Vt
184 |             arma::vec vecStr_t = StrList(islice);
185 |             arma::vec UniqueStr_t = unique(vecStr_t);
186 |             arma::mat Mu_Str = zeros<mat>((int)Mu.n_rows,(int)Mu.n_cols);
187 |             for(int istr : UniqueStr_t){
188 |                 uvec indexStr = find(vecStr_t == istr);
189 |                 uvec notIndexStr = find(vecStr_t != istr);
190 |                 int NspotsInStr = indexStr.size();
191 |                 arma::vec vecOnetnr = ones<vec>(NspotsInStr);
192 |                 arma::mat vecOnetnrMat = ones<mat>(NspotsInStr,NspotsInStr);
193 |                 arma::mat VtDt = calc_VtDt(colsum_At,Vt,indexStr);
194 |                 arma::mat VtAt = At.cols(indexStr).t() * Vt;
195 |                 arma::mat nomUpdateVtStr = (Xt.cols(indexStr).t() * B + beta / NspotsInStr * (vecOnetnr * Mu.col(istr).t()) + lambda * VtAt);
196 |                 arma::mat denomUpdateVtStr = (Vt.rows(indexStr) * B.t() * B + beta / NspotsInStr / NspotsInStr * vecOnetnrMat * Vt.rows(indexStr) + lambda * VtDt);
197 |                 arma::mat updateVtStr = nomUpdateVtStr / denomUpdateVtStr;
198 |                 Vt.rows(indexStr) = Vt.rows(indexStr) % updateVtStr;
199 |                 arma::vec mean_VtStr = mean(Vt.rows(indexStr), 0).t();
200 |                 Mu_Str.col(istr) = mean_VtStr; 
201 |             }
202 |             VList(islice) = Vt;
203 |             Mu_Slice = Mu_Slice + Mu_Str;
204 |             XtVt_sum = XtVt_sum + Xt * Vt;
205 |             BVtV_sum = BVtV_sum + B * Vt.t() * Vt;
206 |         }
207 |         // update B
208 |         B %= XtVt_sum / BVtV_sum;
209 |         // update mu
210 |         Mu = Mu_Slice / nSlice;
211 |         // calculate objective function
212 |         obj = calculateObject(XList,VList,AList,StrList,B,Mu,beta,lambda);
213 |        return List::create(
214 |                            Named("VList") = VList,
215 |                            Named("B") = B,
216 |                            Named("Mu") = Mu,
217 |                            Named("Obj") = obj);
218 |         }//end try 
219 |         catch (std::exception &ex)
220 |         {
221 |             forward_exception_to_r(ex);
222 |         }
223 |         catch (...)
224 |         {
225 |             ::Rf_error("C++ exception (unknown reason)...");
226 |         }
227 |         return R_NilValue;
228 | } // end funcs
229 | 
230 | 
231 | 


--------------------------------------------------------------------------------
/src/Makevars:
--------------------------------------------------------------------------------
 1 | 
 2 | ## With R 3.1.0 or later, you can uncomment the following line to tell R to 
 3 | ## enable compilation with C++11 (where available)
 4 | ##
 5 | ## Also, OpenMP support in Armadillo prefers C++11 support. However, for wider
 6 | ## availability of the package we do not yet enforce this here.  It is however
 7 | ## recommended for client packages to set it.
 8 | ##
 9 | ## And with R 3.4.0, and RcppArmadillo 0.7.960.*, we turn C++11 on as OpenMP
10 | ## support within Armadillo prefers / requires it
11 | CXX_STD = CXX11
12 | 
13 | PKG_CXXFLAGS = $(SHLIB_OPENMP_CXXFLAGS) 
14 | PKG_LIBS = $(SHLIB_OPENMP_CXXFLAGS) $(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS)
15 | 


--------------------------------------------------------------------------------
/src/Makevars.win:
--------------------------------------------------------------------------------
 1 | 
 2 | ## With R 3.1.0 or later, you can uncomment the following line to tell R to 
 3 | ## enable compilation with C++11 (where available)
 4 | ##
 5 | ## Also, OpenMP support in Armadillo prefers C++11 support. However, for wider
 6 | ## availability of the package we do not yet enforce this here.  It is however
 7 | ## recommended for client packages to set it.
 8 | ##
 9 | ## And with R 3.4.0, and RcppArmadillo 0.7.960.*, we turn C++11 on as OpenMP
10 | ## support within Armadillo prefers / requires it
11 | CXX_STD = CXX11
12 | 
13 | PKG_CXXFLAGS = $(SHLIB_OPENMP_CXXFLAGS) 
14 | PKG_LIBS = $(SHLIB_OPENMP_CXXFLAGS) $(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS)
15 | 


--------------------------------------------------------------------------------
/src/RcppExports.cpp:
--------------------------------------------------------------------------------
 1 | // Generated by using Rcpp::compileAttributes() -> do not edit by hand
 2 | // Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393
 3 | 
 4 | #include <RcppArmadillo.h>
 5 | #include <Rcpp.h>
 6 | 
 7 | using namespace Rcpp;
 8 | 
 9 | #ifdef RCPP_USE_GLOBAL_ROSTREAM
10 | Rcpp::Rostream<true>&  Rcpp::Rcout = Rcpp::Rcpp_cout_get();
11 | Rcpp::Rostream<false>& Rcpp::Rcerr = Rcpp::Rcpp_cerr_get();
12 | #endif
13 | 
14 | // IRIS_ref_iter
15 | SEXP IRIS_ref_iter(Rcpp::List& XList, SEXP BIn, Rcpp::List& AList, Rcpp::List VList, Rcpp::List StrList, SEXP MuIn);
16 | RcppExport SEXP _IRIS_IRIS_ref_iter(SEXP XListSEXP, SEXP BInSEXP, SEXP AListSEXP, SEXP VListSEXP, SEXP StrListSEXP, SEXP MuInSEXP) {
17 | BEGIN_RCPP
18 |     Rcpp::RObject rcpp_result_gen;
19 |     Rcpp::RNGScope rcpp_rngScope_gen;
20 |     Rcpp::traits::input_parameter< Rcpp::List& >::type XList(XListSEXP);
21 |     Rcpp::traits::input_parameter< SEXP >::type BIn(BInSEXP);
22 |     Rcpp::traits::input_parameter< Rcpp::List& >::type AList(AListSEXP);
23 |     Rcpp::traits::input_parameter< Rcpp::List >::type VList(VListSEXP);
24 |     Rcpp::traits::input_parameter< Rcpp::List >::type StrList(StrListSEXP);
25 |     Rcpp::traits::input_parameter< SEXP >::type MuIn(MuInSEXP);
26 |     rcpp_result_gen = Rcpp::wrap(IRIS_ref_iter(XList, BIn, AList, VList, StrList, MuIn));
27 |     return rcpp_result_gen;
28 | END_RCPP
29 | }
30 | // IRIS_Marker_iter
31 | SEXP IRIS_Marker_iter(Rcpp::List& XList, SEXP BIn, Rcpp::List& AList, Rcpp::List VList, Rcpp::List StrList, SEXP MuIn);
32 | RcppExport SEXP _IRIS_IRIS_Marker_iter(SEXP XListSEXP, SEXP BInSEXP, SEXP AListSEXP, SEXP VListSEXP, SEXP StrListSEXP, SEXP MuInSEXP) {
33 | BEGIN_RCPP
34 |     Rcpp::RObject rcpp_result_gen;
35 |     Rcpp::RNGScope rcpp_rngScope_gen;
36 |     Rcpp::traits::input_parameter< Rcpp::List& >::type XList(XListSEXP);
37 |     Rcpp::traits::input_parameter< SEXP >::type BIn(BInSEXP);
38 |     Rcpp::traits::input_parameter< Rcpp::List& >::type AList(AListSEXP);
39 |     Rcpp::traits::input_parameter< Rcpp::List >::type VList(VListSEXP);
40 |     Rcpp::traits::input_parameter< Rcpp::List >::type StrList(StrListSEXP);
41 |     Rcpp::traits::input_parameter< SEXP >::type MuIn(MuInSEXP);
42 |     rcpp_result_gen = Rcpp::wrap(IRIS_Marker_iter(XList, BIn, AList, VList, StrList, MuIn));
43 |     return rcpp_result_gen;
44 | END_RCPP
45 | }
46 | 
47 | static const R_CallMethodDef CallEntries[] = {
48 |     {"_IRIS_IRIS_ref_iter", (DL_FUNC) &_IRIS_IRIS_ref_iter, 6},
49 |     {"_IRIS_IRIS_Marker_iter", (DL_FUNC) &_IRIS_IRIS_Marker_iter, 6},
50 |     {NULL, NULL, 0}
51 | };
52 | 
53 | RcppExport void R_init_IRIS(DllInfo *dll) {
54 |     R_registerRoutines(dll, NULL, CallEntries, NULL, NULL);
55 |     R_useDynamicSymbols(dll, FALSE);
56 | }
57 | 


--------------------------------------------------------------------------------
/vignettes/.gitignore:
--------------------------------------------------------------------------------
1 | *.html
2 | *.R
3 | 


--------------------------------------------------------------------------------
/vignettes/SCC_IRIS.html:
--------------------------------------------------------------------------------
  1 | <!DOCTYPE html>
  2 | 
  3 | <html>
  4 | 
  5 | <head>
  6 | 
  7 | <meta charset="utf-8" />
  8 | <meta name="generator" content="pandoc" />
  9 | <meta http-equiv="X-UA-Compatible" content="IE=EDGE" />
 10 | 
 11 | <meta name="viewport" content="width=device-width, initial-scale=1" />
 12 | 
 13 | <meta name="author" content="Ying Ma" />
 14 | 
 15 | 
 16 | <title>Human squamous cell carcinoma (SCC) ST data analysis with IRIS</title>
 17 | 
 18 | <script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to
 19 | // be compatible with the behavior of Pandoc < 2.8).
 20 | document.addEventListener('DOMContentLoaded', function(e) {
 21 |   var hs = document.querySelectorAll("div.section[class*='level'] > :first-child");
 22 |   var i, h, a;
 23 |   for (i = 0; i < hs.length; i++) {
 24 |     h = hs[i];
 25 |     if (!/^h[1-6]$/i.test(h.tagName)) continue;  // it should be a header h1-h6
 26 |     a = h.attributes;
 27 |     while (a.length > 0) h.removeAttribute(a[0].name);
 28 |   }
 29 | });
 30 | </script>
 31 | 
 32 | 
 33 | <style type="text/css">code{white-space: pre;}</style>
 34 | <style type="text/css" data-origin="pandoc">
 35 | pre > code.sourceCode { white-space: pre; position: relative; }
 36 | pre > code.sourceCode > span { line-height: 1.25; }
 37 | pre > code.sourceCode > span:empty { height: 1.2em; }
 38 | .sourceCode { overflow: visible; }
 39 | code.sourceCode > span { color: inherit; text-decoration: inherit; }
 40 | div.sourceCode { margin: 1em 0; }
 41 | pre.sourceCode { margin: 0; }
 42 | @media screen {
 43 | div.sourceCode { overflow: auto; }
 44 | }
 45 | @media print {
 46 | pre > code.sourceCode { white-space: pre-wrap; }
 47 | pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
 48 | }
 49 | pre.numberSource code
 50 | { counter-reset: source-line 0; }
 51 | pre.numberSource code > span
 52 | { position: relative; left: -4em; counter-increment: source-line; }
 53 | pre.numberSource code > span > a:first-child::before
 54 | { content: counter(source-line);
 55 | position: relative; left: -1em; text-align: right; vertical-align: baseline;
 56 | border: none; display: inline-block;
 57 | -webkit-touch-callout: none; -webkit-user-select: none;
 58 | -khtml-user-select: none; -moz-user-select: none;
 59 | -ms-user-select: none; user-select: none;
 60 | padding: 0 4px; width: 4em;
 61 | color: #aaaaaa;
 62 | }
 63 | pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
 64 | div.sourceCode
 65 | { }
 66 | @media screen {
 67 | pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
 68 | }
 69 | code span.al { color: #ff0000; font-weight: bold; } 
 70 | code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } 
 71 | code span.at { color: #7d9029; } 
 72 | code span.bn { color: #40a070; } 
 73 | code span.bu { color: #008000; } 
 74 | code span.cf { color: #007020; font-weight: bold; } 
 75 | code span.ch { color: #4070a0; } 
 76 | code span.cn { color: #880000; } 
 77 | code span.co { color: #60a0b0; font-style: italic; } 
 78 | code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } 
 79 | code span.do { color: #ba2121; font-style: italic; } 
 80 | code span.dt { color: #902000; } 
 81 | code span.dv { color: #40a070; } 
 82 | code span.er { color: #ff0000; font-weight: bold; } 
 83 | code span.ex { } 
 84 | code span.fl { color: #40a070; } 
 85 | code span.fu { color: #06287e; } 
 86 | code span.im { color: #008000; font-weight: bold; } 
 87 | code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } 
 88 | code span.kw { color: #007020; font-weight: bold; } 
 89 | code span.op { color: #666666; } 
 90 | code span.ot { color: #007020; } 
 91 | code span.pp { color: #bc7a00; } 
 92 | code span.sc { color: #4070a0; } 
 93 | code span.ss { color: #bb6688; } 
 94 | code span.st { color: #4070a0; } 
 95 | code span.va { color: #19177c; } 
 96 | code span.vs { color: #4070a0; } 
 97 | code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } 
 98 | 
 99 | a.sourceLine {
100 | pointer-events: auto;
101 | }
102 | </style>
103 | <script>
104 | // apply pandoc div.sourceCode style to pre.sourceCode instead
105 | (function() {
106 |   var sheets = document.styleSheets;
107 |   for (var i = 0; i < sheets.length; i++) {
108 |     if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue;
109 |     try { var rules = sheets[i].cssRules; } catch (e) { continue; }
110 |     for (var j = 0; j < rules.length; j++) {
111 |       var rule = rules[j];
112 |       // check if there is a div.sourceCode rule
113 |       if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") continue;
114 |       var style = rule.style.cssText;
115 |       // check if color or background-color is set
116 |       if (rule.style.color === '' && rule.style.backgroundColor === '') continue;
117 |       // replace div.sourceCode by a pre.sourceCode rule
118 |       sheets[i].deleteRule(j);
119 |       sheets[i].insertRule('pre.sourceCode{' + style + '}', j);
120 |     }
121 |   }
122 | })();
123 | </script>
124 | 
125 | 
126 | 
127 | <style type="text/css">@font-face{font-family:"Open Sans";font-style:normal;font-weight:400;src:local("Open Sans"),local("OpenSans"),url(data:font/woff;base64,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) format("woff")}@font-face{font-family:"Open Sans";font-style:normal;font-weight:700;src:local("Open Sans Bold"),local("OpenSans-Bold"),url(data:font/woff;base64,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) format("woff")}*{box-sizing:border-box}body{padding:0;margin:0;font-family:"Open Sans","Helvetica Neue",Helvetica,Arial,sans-serif;font-size:16px;line-height:1.5;color:#606c71}a{color:#1e6bb8;text-decoration:none}a:hover{text-decoration:underline}.page-header{color:#fff;text-align:center;background-color:#159957;background-image:linear-gradient(120deg,#155799,#159957);padding:1.5rem 2rem}.page-header :last-child{margin-bottom:.5rem}@media screen and (max-width:42em){.page-header{padding:1rem 1rem}}.project-name{margin-top:0;margin-bottom:.1rem;font-size:2rem}@media screen and (max-width:42em){.project-name{font-size:1.75rem}}.project-tagline{margin-bottom:2rem;font-weight:400;opacity:.7;font-size:1.5rem}@media screen and (max-width:42em){.project-tagline{font-size:1.2rem}}.project-author,.project-date{font-weight:400;opacity:.7;font-size:1.2rem}@media screen and (max-width:42em){.project-author,.project-date{font-size:1rem}}.main-content,.toc{max-width:64rem;padding:2rem 4rem;margin:0 auto;font-size:1.1rem}.toc{padding-bottom:0}.toc .toc-box{padding:1.5rem;background-color:#f3f6fa;border:solid 1px #dce6f0;border-radius:.3rem}.toc .toc-box .toc-title{margin:0 0 .5rem;text-align:center}.toc .toc-box>ul{margin:0;padding-left:1.5rem}@media screen and (min-width:42em) and (max-width:64em){.toc{padding:2rem 2rem 0}}@media screen and (max-width:42em){.toc{padding:2rem 1rem 0;font-size:1rem}}.main-content :first-child{margin-top:0}@media screen and (min-width:42em) and (max-width:64em){.main-content{padding:2rem}}@media screen and (max-width:42em){.main-content{padding:2rem 1rem;font-size:1rem}}.main-content img{max-width:100%}.main-content h1,.main-content h2,.main-content h3,.main-content h4,.main-content h5,.main-content h6{margin-top:2rem;margin-bottom:1rem;font-weight:400;color:#159957}.main-content p{margin-bottom:1em}.main-content code{padding:2px 4px;font-family:Consolas,"Liberation Mono",Menlo,Courier,monospace;color:#567482;background-color:#f3f6fa;border-radius:.3rem}.main-content pre{padding:.8rem;margin-top:0;margin-bottom:1rem;font:1rem Consolas,"Liberation Mono",Menlo,Courier,monospace;color:#567482;word-wrap:normal;background-color:#f3f6fa;border:solid 1px #dce6f0;border-radius:.3rem;line-height:1.45;overflow:auto}@media screen and (max-width:42em){.main-content pre{font-size:.9rem}}.main-content pre>code{padding:0;margin:0;color:#567482;word-break:normal;white-space:pre;background:0 0;border:0}@media screen and (max-width:42em){.main-content pre>code{font-size:.9rem}}.main-content pre code,.main-content pre tt{display:inline;max-width:initial;padding:0;margin:0;overflow:initial;line-height:inherit;word-wrap:normal;background-color:transparent;border:0}.main-content pre code:after,.main-content pre code:before,.main-content pre tt:after,.main-content pre tt:before{content:normal}.main-content ol,.main-content ul{margin-top:0}.main-content blockquote{padding:0 1rem;margin-left:0;color:#819198;border-left:.3rem solid #dce6f0;font-size:1.2rem}.main-content blockquote>:first-child{margin-top:0}.main-content blockquote>:last-child{margin-bottom:0}@media screen and (max-width:42em){.main-content blockquote{font-size:1.1rem}}.main-content table{width:100%;overflow:auto;word-break:normal;word-break:keep-all;-webkit-overflow-scrolling:touch;border-collapse:collapse;border-spacing:0;margin:1rem 0}.main-content table th{font-weight:700;background-color:#159957;color:#fff}.main-content table td,.main-content table th{padding:.5rem 1rem;border-bottom:1px solid #e9ebec;text-align:left}.main-content table tr:nth-child(odd){background-color:#f2f2f2}.main-content dl{padding:0}.main-content dl dt{padding:0;margin-top:1rem;font-size:1rem;font-weight:700}.main-content dl dd{padding:0;margin-bottom:1rem}.main-content hr{height:2px;padding:0;margin:1rem 0;background-color:#eff0f1;border:0}code span.kw { color: #a71d5d; font-weight: normal; } 
128 | code span.dt { color: #795da3; } 
129 | code span.dv { color: #0086b3; } 
130 | code span.bn { color: #0086b3; } 
131 | code span.fl { color: #0086b3; } 
132 | code span.ch { color: #4070a0; } 
133 | code span.st { color: #183691; } 
134 | code span.co { color: #969896; font-style: italic; } 
135 | code span.ot { color: #007020; } 
136 | </style>
137 | 
138 | 
139 | 
140 | 
141 | 
142 | </head>
143 | 
144 | <body>
145 | 
146 | 
147 | 
148 | 
149 | <section class="page-header">
150 | <h1 class="title toc-ignore project-name">Human squamous cell carcinoma
151 | (SCC) ST data analysis with IRIS</h1>
152 | <h4 class="author project-author">Ying Ma</h4>
153 | <h4 class="date project-date">Jan 09, 2024</h4>
154 | </section>
155 | 
156 | 
157 | 
158 | <section class="main-content">
159 | <p>This is the analysis of the Human squamous cell carcinoma (SCC) ST
160 | data analysis with IRIS.</p>
161 | <p>Due to the storage issue of github, the required input dataset is
162 | stored here: on the <a href="https://drive.google.com/drive/u/1/folders/13X_IbFjO_wIsRvohtxfEkpcONW3zCY2U">google
163 | drive</a>. Please see more details on the required data input from the
164 | <a href="https://yingma0107.github.io/IRIS/documentation/04_IRIS_Example.html">main
165 | tutorial</a>.</p>
166 | <div id="load-the-list-of-spatial-transcriptomics-data-across-multiple-slices" class="section level2">
167 | <h2>load the list of spatial transcriptomics data across multiple
168 | slices</h2>
169 | <div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" tabindex="-1"></a><span class="fu">library</span>(IRIS)</span>
170 | <span id="cb1-2"><a href="#cb1-2" tabindex="-1"></a><span class="do">### read in the list of spatial transcriptomics dataset across multiple tissue slices</span></span>
171 | <span id="cb1-3"><a href="#cb1-3" tabindex="-1"></a>sp_input <span class="ot">=</span> <span class="fu">readRDS</span>(<span class="st">&quot;./countList_SCC_ST.RDS&quot;</span>)</span>
172 | <span id="cb1-4"><a href="#cb1-4" tabindex="-1"></a><span class="do">#### extract the count data list and location list</span></span>
173 | <span id="cb1-5"><a href="#cb1-5" tabindex="-1"></a>spatial_countMat_list <span class="ot">=</span> sp_input<span class="sc">$</span>spatial_countMat_list</span>
174 | <span id="cb1-6"><a href="#cb1-6" tabindex="-1"></a>spatial_location_list <span class="ot">=</span> sp_input<span class="sc">$</span>spatial_location_list</span></code></pre></div>
175 | </div>
176 | <div id="load-the-reference-scrna-seq-data" class="section level2">
177 | <h2>load the reference scRNA-seq data</h2>
178 | <div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb2-1"><a href="#cb2-1" tabindex="-1"></a><span class="do">#### read in the example reference scRNA-seq data, </span></span>
179 | <span id="cb2-2"><a href="#cb2-2" tabindex="-1"></a>sc_input <span class="ot">=</span> <span class="fu">readRDS</span>(<span class="st">&quot;./scRef_input_SCC.RDS&quot;</span>)</span>
180 | <span id="cb2-3"><a href="#cb2-3" tabindex="-1"></a><span class="do">#### extract the count data, metadata, column name indicating cell type annotation, and column name indicating samples/subjects.</span></span>
181 | <span id="cb2-4"><a href="#cb2-4" tabindex="-1"></a>sc_count <span class="ot">=</span> sc_input<span class="sc">$</span>sc_count</span>
182 | <span id="cb2-5"><a href="#cb2-5" tabindex="-1"></a>sc_meta <span class="ot">=</span> sc_input<span class="sc">$</span>sc_meta</span>
183 | <span id="cb2-6"><a href="#cb2-6" tabindex="-1"></a>ct.varname <span class="ot">=</span> sc_input<span class="sc">$</span>ct.varname</span>
184 | <span id="cb2-7"><a href="#cb2-7" tabindex="-1"></a>sample.varname <span class="ot">=</span> sc_input<span class="sc">$</span>sample.varname</span></code></pre></div>
185 | </div>
186 | <div id="integrative-and-reference-informed-spatial-domain-detection-with-iris" class="section level2">
187 | <h2>integrative and reference-informed spatial domain detection with
188 | IRIS</h2>
189 | <div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb3-1"><a href="#cb3-1" tabindex="-1"></a><span class="do">##### create IRIS object</span></span>
190 | <span id="cb3-2"><a href="#cb3-2" tabindex="-1"></a>IRIS_object <span class="ot">&lt;-</span> <span class="fu">createIRISObject</span>(</span>
191 | <span id="cb3-3"><a href="#cb3-3" tabindex="-1"></a>  <span class="at">spatial_countMat_list =</span> spatial_countMat_list,</span>
192 | <span id="cb3-4"><a href="#cb3-4" tabindex="-1"></a>  <span class="at">spatial_location_list =</span> spatial_location_list,</span>
193 | <span id="cb3-5"><a href="#cb3-5" tabindex="-1"></a>  <span class="at">sc_count =</span> sc_count,</span>
194 | <span id="cb3-6"><a href="#cb3-6" tabindex="-1"></a>  <span class="at">sc_meta =</span> sc_meta,</span>
195 | <span id="cb3-7"><a href="#cb3-7" tabindex="-1"></a>  <span class="at">ct.varname =</span> ct.varname,</span>
196 | <span id="cb3-8"><a href="#cb3-8" tabindex="-1"></a>  <span class="at">sample.varname =</span> sample.varname,</span>
197 | <span id="cb3-9"><a href="#cb3-9" tabindex="-1"></a>  <span class="at">minCountGene =</span> <span class="dv">100</span>,</span>
198 | <span id="cb3-10"><a href="#cb3-10" tabindex="-1"></a>  <span class="at">minCountSpot =</span><span class="dv">5</span>) </span>
199 | <span id="cb3-11"><a href="#cb3-11" tabindex="-1"></a><span class="do">#### preselect the number of spatial domains </span></span>
200 | <span id="cb3-12"><a href="#cb3-12" tabindex="-1"></a>numCluster <span class="ot">=</span> <span class="dv">12</span></span>
201 | <span id="cb3-13"><a href="#cb3-13" tabindex="-1"></a><span class="do">#### perform the integrative and refernce-informed domain detection</span></span>
202 | <span id="cb3-14"><a href="#cb3-14" tabindex="-1"></a>IRIS_object <span class="ot">&lt;-</span> <span class="fu">IRIS_spatial</span>(IRIS_object,<span class="at">numCluster =</span> numCluster)</span></code></pre></div>
203 | <p>The results of detected domains are stored in
204 | <code>IRIS_object@spatialDomain</code>.</p>
205 | <div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb4-1"><a href="#cb4-1" tabindex="-1"></a><span class="fu">print</span>(IRIS_object<span class="sc">@</span>spatialDomain[<span class="dv">1</span><span class="sc">:</span><span class="dv">4</span>,])</span>
206 | <span id="cb4-2"><a href="#cb4-2" tabindex="-1"></a>       Slice spotName  x  y IRIS_domain</span>
207 | <span id="cb4-3"><a href="#cb4-3" tabindex="-1"></a><span class="dv">10</span>x26 Slice1    <span class="dv">10</span>x26 <span class="dv">10</span> <span class="dv">26</span>           <span class="dv">6</span></span>
208 | <span id="cb4-4"><a href="#cb4-4" tabindex="-1"></a><span class="dv">10</span>x28 Slice1    <span class="dv">10</span>x28 <span class="dv">10</span> <span class="dv">28</span>           <span class="dv">6</span></span>
209 | <span id="cb4-5"><a href="#cb4-5" tabindex="-1"></a><span class="dv">10</span>x30 Slice1    <span class="dv">10</span>x30 <span class="dv">10</span> <span class="dv">30</span>           <span class="dv">6</span></span>
210 | <span id="cb4-6"><a href="#cb4-6" tabindex="-1"></a><span class="dv">10</span>x32 Slice1    <span class="dv">10</span>x32 <span class="dv">10</span> <span class="dv">32</span>           <span class="dv">3</span></span></code></pre></div>
211 | </div>
212 | </section>
213 | 
214 | 
215 | 
216 | <!-- code folding -->
217 | 
218 | 
219 | <!-- dynamically load mathjax for compatibility with self-contained -->
220 | <script>
221 |   (function () {
222 |     var script = document.createElement("script");
223 |     script.type = "text/javascript";
224 |     script.src  = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
225 |     document.getElementsByTagName("head")[0].appendChild(script);
226 |   })();
227 | </script>
228 | 
229 | </body>
230 | </html>
231 | 


--------------------------------------------------------------------------------
/vignettes/my-vignette.Rmd:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: "my-vignette"
 3 | output: rmarkdown::html_vignette
 4 | vignette: >
 5 |   %\VignetteIndexEntry{my-vignette}
 6 |   %\VignetteEngine{knitr::rmarkdown}
 7 |   %\VignetteEncoding{UTF-8}
 8 | ---
 9 | 
10 | ```{r, include = FALSE}
11 | knitr::opts_chunk$set(
12 |   collapse = TRUE,
13 |   comment = "#>"
14 | )
15 | ```
16 | 
17 | ```{r setup}
18 | library(IRIS)
19 | ```
20 | 


--------------------------------------------------------------------------------