cc-mapping 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
cc_mapping/utils.py ADDED
@@ -0,0 +1,192 @@
1
+ """
2
+ Utility functions for the cc_mapping package.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from typing import List
8
+
9
+ import anndata as ad
10
+ import numpy as np
11
+ import pandas as pd
12
+
13
+
14
+ def create_boolean_label_combination(
15
+ adata: ad.AnnData,
16
+ obs_key_1: str,
17
+ match_values_1: List[str],
18
+ obs_key_2: str,
19
+ match_values_2: List[str],
20
+ operator: str,
21
+ output_obs_key: str,
22
+ true_label: str,
23
+ false_label: str,
24
+ overwrite: bool = False,
25
+ ) -> ad.AnnData:
26
+ """
27
+ Combine two categorical observation columns using boolean operators.
28
+
29
+ Creates a new binary label based on whether cells match specified values
30
+ in both input observation columns, using the specified boolean operator.
31
+
32
+ Parameters
33
+ ----------
34
+ adata : ad.AnnData
35
+ AnnData object with observations to combine.
36
+ obs_key_1 : str
37
+ First observation column name in adata.obs.
38
+ match_values_1 : List[str]
39
+ Values in obs_key_1 to match (considered "true" for boolean logic).
40
+ obs_key_2 : str
41
+ Second observation column name in adata.obs.
42
+ match_values_2 : List[str]
43
+ Values in obs_key_2 to match (considered "true" for boolean logic).
44
+ operator : str
45
+ Boolean operator - 'AND', 'OR', or 'XOR'.
46
+ output_obs_key : str
47
+ Name for new combined observation column.
48
+ true_label : str
49
+ Label for cells matching the boolean criteria.
50
+ false_label : str
51
+ Label for cells not matching the boolean criteria.
52
+ overwrite : bool, default False
53
+ If True, overwrites existing output_key. If False, raises error if
54
+ output_key exists.
55
+
56
+ Returns
57
+ -------
58
+ ad.AnnData
59
+ Modified AnnData object with new observation column.
60
+
61
+ Raises
62
+ ------
63
+ KeyError
64
+ If obs_key_1 or obs_key_2 don't exist in adata.obs.
65
+ ValueError
66
+ If operator is not 'AND', 'OR', or 'XOR'.
67
+ KeyError
68
+ If output_obs_key already exists in adata.obs and overwrite=False.
69
+ TypeError
70
+ If match_values_1 or match_values_2 are not lists.
71
+ ValueError
72
+ If any values in match_values_1 not found in obs_key_1.
73
+ ValueError
74
+ If any values in match_values_2 not found in obs_key_2.
75
+
76
+ Examples
77
+ --------
78
+ AND: Both conditions must be true
79
+
80
+ >>> adata = create_boolean_label_combination(
81
+ ... adata,
82
+ ... obs_key_1='treatment',
83
+ ... match_values_1=['control'],
84
+ ... obs_key_2='cell_cycle',
85
+ ... match_values_2=['G0'],
86
+ ... operator='AND',
87
+ ... output_obs_key='control_G0',
88
+ ... true_label='control_G0',
89
+ ... false_label='other'
90
+ ... )
91
+
92
+ OR: Either condition true
93
+
94
+ >>> adata = create_boolean_label_combination(
95
+ ... adata,
96
+ ... obs_key_1='treatment',
97
+ ... match_values_1=['control', 'vehicle'],
98
+ ... obs_key_2='cell_cycle',
99
+ ... match_values_2=['G0', 'G1'],
100
+ ... operator='OR',
101
+ ... output_obs_key='quiescent_or_control',
102
+ ... true_label='positive',
103
+ ... false_label='other'
104
+ ... )
105
+
106
+ XOR: Exactly one condition true (exclusive or)
107
+
108
+ >>> adata = create_boolean_label_combination(
109
+ ... adata,
110
+ ... obs_key_1='marker_A',
111
+ ... match_values_1=['positive'],
112
+ ... obs_key_2='marker_B',
113
+ ... match_values_2=['positive'],
114
+ ... operator='XOR',
115
+ ... output_obs_key='single_positive',
116
+ ... true_label='single_positive',
117
+ ... false_label='double_or_negative'
118
+ ... )
119
+ """
120
+ # Validate observation columns exist
121
+ if obs_key_1 not in adata.obs.columns:
122
+ raise KeyError(
123
+ f"obs_key_1 '{obs_key_1}' not found in adata.obs. "
124
+ f"Available columns: {list(adata.obs.columns)}"
125
+ )
126
+
127
+ if obs_key_2 not in adata.obs.columns:
128
+ raise KeyError(
129
+ f"obs_key_2 '{obs_key_2}' not found in adata.obs. "
130
+ f"Available columns: {list(adata.obs.columns)}"
131
+ )
132
+
133
+ # Validate operator
134
+ valid_operators = ['AND', 'OR', 'XOR']
135
+ operator = operator.upper()
136
+ if operator not in valid_operators:
137
+ raise ValueError(
138
+ f"operator must be one of {valid_operators}, got '{operator}'"
139
+ )
140
+
141
+ # Validate output_obs_key doesn't already exist (unless overwrite=True)
142
+ if output_obs_key in adata.obs.columns and not overwrite:
143
+ raise KeyError(
144
+ f"output_obs_key '{output_obs_key}' already exists in adata.obs. "
145
+ "Set overwrite=True to replace it, or choose a different name."
146
+ )
147
+
148
+ # Validate match values are lists
149
+ if not isinstance(match_values_1, list):
150
+ raise TypeError(
151
+ f"match_values_1 must be a list, got {type(match_values_1)}"
152
+ )
153
+
154
+ if not isinstance(match_values_2, list):
155
+ raise TypeError(
156
+ f"match_values_2 must be a list, got {type(match_values_2)}"
157
+ )
158
+
159
+ # Validate all values exist in their respective observation columns
160
+ unique_obs_1 = set(adata.obs[obs_key_1].unique())
161
+ for val in match_values_1:
162
+ if val not in unique_obs_1:
163
+ raise ValueError(
164
+ f"Value '{val}' not found in obs_key_1 '{obs_key_1}'. "
165
+ f"Available values: {sorted(unique_obs_1)}"
166
+ )
167
+
168
+ unique_obs_2 = set(adata.obs[obs_key_2].unique())
169
+ for val in match_values_2:
170
+ if val not in unique_obs_2:
171
+ raise ValueError(
172
+ f"Value '{val}' not found in obs_key_2 '{obs_key_2}'. "
173
+ f"Available values: {sorted(unique_obs_2)}"
174
+ )
175
+
176
+ # Create boolean masks
177
+ mask1 = adata.obs[obs_key_1].isin(match_values_1)
178
+ mask2 = adata.obs[obs_key_2].isin(match_values_2)
179
+
180
+ # Apply boolean operator
181
+ if operator == 'AND':
182
+ final_mask = mask1 & mask2
183
+ elif operator == 'OR':
184
+ final_mask = mask1 | mask2
185
+ elif operator == 'XOR':
186
+ final_mask = mask1 ^ mask2
187
+
188
+ # Create new categorical column
189
+ new_labels = np.where(final_mask, true_label, false_label)
190
+ adata.obs[output_obs_key] = pd.Categorical(new_labels)
191
+
192
+ return adata
cc_mapping/utils_v0.py ADDED
@@ -0,0 +1,385 @@
1
+ from __future__ import annotations
2
+
3
+ import re
4
+ import anndata as ad
5
+ from collections import Counter
6
+ from math import floor
7
+ from typing import List
8
+
9
+ import numpy as np
10
+ import pandas as pd
11
+
12
+
13
+ def get_str_idx(
14
+ strings_to_find: str | list[str] | np.ndarray[str],
15
+ string_list: list[str] | np.ndarray[str],
16
+ regex: bool = False,
17
+ regex_flags: list[str] = None,
18
+ ) -> list[np.ndarray]:
19
+ """
20
+ Takes in a string or list of strings and returns the indices and the names of the matching strings in the string list.
21
+ Regex can be used to find strings that match a pattern.
22
+
23
+ If the string list contains no duplicates, then a dictionary is used to speed up the search when searching for multiple strings.
24
+
25
+ Args:
26
+ strings_to_find (str | list[str] | np.ndarray[str]): A string or iterable of strings to search for.
27
+ string_list (list[str] | np.ndarray[str]): An iterable of strings to search through.
28
+ regex (bool, optional): Whether to use regular expressions for searching. Defaults to False.
29
+ regex_flags (list[str], optional): List of regex flags to use if regex is True. Defaults to None.
30
+
31
+ Raises:
32
+ ValueError: If the search array contains duplicate strings.
33
+ ValueError: If the string list contains non-string elements.
34
+
35
+ Returns:
36
+ list[np.ndarray]: Indices and names of the matching strings in the string list.
37
+ """
38
+ if regex:
39
+ reFlags = []
40
+ for flag in regex_flags:
41
+ reFlags.append(getattr(re, flag))
42
+
43
+ search_func = lambda regex, string_to_search: re.search(
44
+ regex, string_to_search, *reFlags
45
+ )
46
+ else:
47
+ search_func = (
48
+ lambda matching_string, string_to_search: matching_string
49
+ == string_to_search
50
+ )
51
+
52
+ if isinstance(strings_to_find, str):
53
+ strings_to_find = [strings_to_find]
54
+
55
+ if np.unique(strings_to_find).shape[0] != len(strings_to_find):
56
+ raise ValueError("Search array of strings contains duplicate strings")
57
+
58
+ if not np.all([isinstance(string, str) for string in string_list]):
59
+ raise ValueError("String list must contain only strings")
60
+
61
+ # if the string list contains no duplicates, then we can use a dictionary to speed up the search
62
+ if np.unique(string_list).shape[0] == len(string_list) and not regex:
63
+ string_list_dict = {string: idx for idx, string in enumerate(string_list)}
64
+ feat_idx_names = np.array(
65
+ [
66
+ [string_list_dict[string], string]
67
+ for string in strings_to_find
68
+ if string in string_list_dict
69
+ ]
70
+ )
71
+ else:
72
+ match_list = []
73
+
74
+ # creates a search function based on whether or not the user wants to use regex that returns true if there is a match
75
+ for string in strings_to_find:
76
+ feat_idx_names = [
77
+ [idx, item]
78
+ for idx, item in enumerate(string_list)
79
+ if search_func(string, item)
80
+ ]
81
+
82
+ if feat_idx_names != []:
83
+ match_list.append(feat_idx_names)
84
+
85
+ if len(match_list) == 0:
86
+ raise KeyError("No Matching Values")
87
+
88
+ feat_idx_names = np.vstack(match_list)
89
+
90
+ feature_idxs, feature_names = feat_idx_names[:, 0].astype(int), feat_idx_names[:, 1]
91
+ return feature_idxs, feature_names
92
+
93
+
94
+ def equalize_conditions(adata: ad.AnnData, obs_str: str, ignore_min_list: list[str] = None) -> ad.AnnData:
95
+ """
96
+ Equalizes the conditions in the given AnnData object based on the specified observation string.
97
+
98
+ Args:
99
+ adata (ad.AnnData): The AnnData object containing the data.
100
+ obs_str (str): The observation string specifying the condition to equalize.
101
+ ignore_min_list (list[str], optional): A list of observation values to ignore when equalizing. Defaults to None.
102
+
103
+ Returns:
104
+ ad.AnnData: The modified AnnData object with equalized conditions.
105
+ """
106
+ obs_values = adata.obs[obs_str].copy()
107
+
108
+ obs_counts = Counter(obs_values)
109
+
110
+ if ignore_min_list is not None:
111
+ for obs_val in ignore_min_list:
112
+ obs_counts.pop(obs_val)
113
+
114
+ min_obs_count = np.min(list(obs_counts.values()))
115
+
116
+ idx_list = []
117
+ for obs_val in obs_counts.keys():
118
+ obs_idxs, _ = get_str_idx(obs_val, obs_values)
119
+
120
+ np.random.seed(0)
121
+ selected_obs_idxs = list(
122
+ np.random.choice(obs_idxs, size=min_obs_count, replace=False)
123
+ )
124
+ idx_list.extend(selected_obs_idxs)
125
+
126
+ adata = adata[idx_list, :].copy()
127
+
128
+ return adata
129
+
130
+
131
+ def create_boolean_label_combination(
132
+ adata: ad.AnnData,
133
+ obs_key_1: str,
134
+ match_values_1: List[str],
135
+ obs_key_2: str,
136
+ match_values_2: List[str],
137
+ operator: str,
138
+ output_obs_key: str,
139
+ true_label: str,
140
+ false_label: str,
141
+ overwrite: bool = False,
142
+ ) -> ad.AnnData:
143
+ """
144
+ Combine two categorical observation columns using boolean operators.
145
+
146
+ Creates a new binary label based on whether cells match specified values
147
+ in both input observation columns, using the specified boolean operator.
148
+
149
+ Parameters
150
+ ----------
151
+ adata : ad.AnnData
152
+ AnnData object with observations to combine.
153
+ obs_key_1 : str
154
+ First observation column name in adata.obs.
155
+ match_values_1 : List[str]
156
+ Values in obs_key_1 to match (considered "true" for boolean logic).
157
+ obs_key_2 : str
158
+ Second observation column name in adata.obs.
159
+ match_values_2 : List[str]
160
+ Values in obs_key_2 to match (considered "true" for boolean logic).
161
+ operator : str
162
+ Boolean operator - 'AND', 'OR', or 'XOR'.
163
+ output_obs_key : str
164
+ Name for new combined observation column.
165
+ true_label : str
166
+ Label for cells matching the boolean criteria.
167
+ false_label : str
168
+ Label for cells not matching the boolean criteria.
169
+ overwrite : bool, default False
170
+ If True, overwrites existing output_key. If False, raises error if
171
+ output_key exists.
172
+
173
+ Returns
174
+ -------
175
+ ad.AnnData
176
+ Modified AnnData object with new observation column.
177
+
178
+ Raises
179
+ ------
180
+ KeyError
181
+ If obs_key_1 or obs_key_2 don't exist in adata.obs.
182
+ ValueError
183
+ If operator is not 'AND', 'OR', or 'XOR'.
184
+ KeyError
185
+ If output_obs_key already exists in adata.obs and overwrite=False.
186
+ TypeError
187
+ If match_values_1 or match_values_2 are not lists.
188
+ ValueError
189
+ If any values in match_values_1 not found in obs_key_1.
190
+ ValueError
191
+ If any values in match_values_2 not found in obs_key_2.
192
+
193
+ Examples
194
+ --------
195
+ AND: Both conditions must be true
196
+
197
+ >>> adata = create_boolean_label_combination(
198
+ ... adata,
199
+ ... obs_key_1='treatment',
200
+ ... match_values_1=['control'],
201
+ ... obs_key_2='cell_cycle',
202
+ ... match_values_2=['G0'],
203
+ ... operator='AND',
204
+ ... output_obs_key='control_G0',
205
+ ... true_label='control_G0',
206
+ ... false_label='other'
207
+ ... )
208
+
209
+ OR: Either condition true
210
+
211
+ >>> adata = create_boolean_label_combination(
212
+ ... adata,
213
+ ... obs_key_1='treatment',
214
+ ... match_values_1=['control', 'vehicle'],
215
+ ... obs_key_2='cell_cycle',
216
+ ... match_values_2=['G0', 'G1'],
217
+ ... operator='OR',
218
+ ... output_obs_key='quiescent_or_control',
219
+ ... true_label='positive',
220
+ ... false_label='other'
221
+ ... )
222
+
223
+ XOR: Exactly one condition true (exclusive or)
224
+
225
+ >>> adata = create_boolean_label_combination(
226
+ ... adata,
227
+ ... obs_key_1='marker_A',
228
+ ... match_values_1=['positive'],
229
+ ... obs_key_2='marker_B',
230
+ ... match_values_2=['positive'],
231
+ ... operator='XOR',
232
+ ... output_obs_key='single_positive',
233
+ ... true_label='single_positive',
234
+ ... false_label='double_or_negative'
235
+ ... )
236
+ """
237
+ # Validate observation columns exist
238
+ if obs_key_1 not in adata.obs.columns:
239
+ raise KeyError(
240
+ f"obs_key_1 '{obs_key_1}' not found in adata.obs. "
241
+ f"Available columns: {list(adata.obs.columns)}"
242
+ )
243
+
244
+ if obs_key_2 not in adata.obs.columns:
245
+ raise KeyError(
246
+ f"obs_key_2 '{obs_key_2}' not found in adata.obs. "
247
+ f"Available columns: {list(adata.obs.columns)}"
248
+ )
249
+
250
+ # Validate operator
251
+ valid_operators = ['AND', 'OR', 'XOR']
252
+ operator = operator.upper()
253
+ if operator not in valid_operators:
254
+ raise ValueError(
255
+ f"operator must be one of {valid_operators}, got '{operator}'"
256
+ )
257
+
258
+ # Validate output_obs_key doesn't already exist (unless overwrite=True)
259
+ if output_obs_key in adata.obs.columns and not overwrite:
260
+ raise KeyError(
261
+ f"output_obs_key '{output_obs_key}' already exists in adata.obs. "
262
+ "Set overwrite=True to replace it, or choose a different name."
263
+ )
264
+
265
+ # Validate match values are lists
266
+ if not isinstance(match_values_1, list):
267
+ raise TypeError(
268
+ f"match_values_1 must be a list, got {type(match_values_1)}"
269
+ )
270
+
271
+ if not isinstance(match_values_2, list):
272
+ raise TypeError(
273
+ f"match_values_2 must be a list, got {type(match_values_2)}"
274
+ )
275
+
276
+ # Validate all values exist in their respective observation columns
277
+ unique_obs_1 = set(adata.obs[obs_key_1].unique())
278
+ for val in match_values_1:
279
+ if val not in unique_obs_1:
280
+ raise ValueError(
281
+ f"Value '{val}' not found in obs_key_1 '{obs_key_1}'. "
282
+ f"Available values: {sorted(unique_obs_1)}"
283
+ )
284
+
285
+ unique_obs_2 = set(adata.obs[obs_key_2].unique())
286
+ for val in match_values_2:
287
+ if val not in unique_obs_2:
288
+ raise ValueError(
289
+ f"Value '{val}' not found in obs_key_2 '{obs_key_2}'. "
290
+ f"Available values: {sorted(unique_obs_2)}"
291
+ )
292
+
293
+ # Create boolean masks
294
+ mask1 = adata.obs[obs_key_1].isin(match_values_1)
295
+ mask2 = adata.obs[obs_key_2].isin(match_values_2)
296
+
297
+ # Apply boolean operator
298
+ if operator == 'AND':
299
+ final_mask = mask1 & mask2
300
+ elif operator == 'OR':
301
+ final_mask = mask1 | mask2
302
+ elif operator == 'XOR':
303
+ final_mask = mask1 ^ mask2
304
+
305
+ # Create new categorical column
306
+ new_labels = np.where(final_mask, true_label, false_label)
307
+ adata.obs[output_obs_key] = pd.Categorical(new_labels)
308
+
309
+ return adata
310
+
311
+
312
+ def equalize_within_two_conditions(
313
+ adata: ad.AnnData, first_obs_str: str, second_obs_str: str, ignore_min_list: list[str] = None
314
+ ) -> ad.AnnData:
315
+ """
316
+ Equalizes the number of observations within two conditions in a single-cell dataset.
317
+
318
+ Args:
319
+ adata (ad.AnnData): Annotated data matrix.
320
+ first_obs_str (str): Name of the first condition.
321
+ second_obs_str (str): Name of the second condition.
322
+ ignore_min_list (list[str], optional): List of observation values to ignore when calculating the minimum count. Defaults to None.
323
+
324
+ Returns:
325
+ ad.AnnData: Annotated data matrix with equalized observations.
326
+ """
327
+ f_obs_values = adata.obs[first_obs_str].copy()
328
+ f_obs_counts = Counter(f_obs_values)
329
+ unique_f_obs_values = sorted(f_obs_counts.keys())
330
+
331
+ if ignore_min_list is not None:
332
+ for obs_val in ignore_min_list:
333
+ f_obs_counts.pop(obs_val)
334
+
335
+ first_min_obs_count = np.min(f_obs_counts.values())
336
+
337
+ s_obs_values = adata.obs[second_obs_str].copy()
338
+ s_obs_counts = Counter(s_obs_values)
339
+ num_unique_s_obs_values = len(s_obs_counts.keys())
340
+
341
+ f_obs_per_s_obs = int(first_min_obs_count / num_unique_s_obs_values)
342
+
343
+ fs_obs_array = np.array([f_obs_values, s_obs_values], dtype=str).T
344
+
345
+ idx_list = []
346
+ for f_obs in unique_f_obs_values:
347
+ f_obs_idxs, _ = get_str_idx(f_obs, fs_obs_array[:, 0])
348
+ single_f_obs_array = fs_obs_array[f_obs_idxs, :]
349
+
350
+ s_obs_counts = Counter(single_f_obs_array[:, 1])
351
+
352
+ s_obs_counts_keys = list(s_obs_counts.keys())
353
+ s_obs_counts_values = np.array(list(s_obs_counts.values()))
354
+
355
+ argsorted_s_obs_counts = np.argsort(s_obs_counts_values)
356
+
357
+ sorted_s_obs_counts_values = s_obs_counts_values[argsorted_s_obs_counts]
358
+ sorted_s_obs_counts_keys = s_obs_counts_keys[argsorted_s_obs_counts]
359
+
360
+ for idx, (s_obs_key, s_obs_count) in enumerate(
361
+ zip(sorted_s_obs_counts_keys, sorted_s_obs_counts_values, strict=False)
362
+ ):
363
+ s_obs_idxs, _ = get_str_idx(s_obs_key, single_f_obs_array[:, 1])
364
+
365
+ if s_obs_count > f_obs_per_s_obs:
366
+ num_idxs_to_add = f_obs_per_s_obs
367
+
368
+ else:
369
+ num_idxs_to_add = s_obs_count
370
+
371
+ difference = f_obs_per_s_obs - s_obs_count
372
+
373
+ # if a s_obs_key does not have enough observations, then we need to add the difference to the total needed from the other s_obs_keys
374
+ # TODO: this can lead to a situation where the last s_obs_key may not have enough observations to equalize the conditions
375
+ f_obs_per_s_obs += floor(difference / num_unique_s_obs_values - idx)
376
+
377
+ np.random.seed(0)
378
+ selected_obs_idxs = list(
379
+ np.random.choice(s_obs_idxs, size=num_idxs_to_add, replace=False)
380
+ )
381
+ idx_list.extend(selected_obs_idxs)
382
+
383
+ adata = adata[idx_list, :].copy()
384
+
385
+ return adata
@@ -0,0 +1,19 @@
1
+ Copyright (c) 2018 The Python Packaging Authority
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining a copy
4
+ of this software and associated documentation files (the "Software"), to deal
5
+ in the Software without restriction, including without limitation the rights
6
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7
+ copies of the Software, and to permit persons to whom the Software is
8
+ furnished to do so, subject to the following conditions:
9
+
10
+ The above copyright notice and this permission notice shall be included in all
11
+ copies or substantial portions of the Software.
12
+
13
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19
+ SOFTWARE.