++ + + ++
Work in Progress¤
The full API of
+ocelotis likely to change a lot before its first proper release. +This API page for ocelot.calculate is just a demo to help us make sure thatmkdocstringsis working.
ocelot.calculate.mean_distance(data_gaia, membership_probabilities=None, key_parallax='parallax', key_parallax_error='parallax_error', key_r_est='r_est', key_r_low='r_lo', key_r_high='r_hi', key_result_flag='result_flag', calculate_cbj_mean_distance=False, **kwargs)
+
+¤Produces mean parallax and distance statistics, including a basic handling of error.
+Done in a very basic, frequentist way, whereby means are weighted based on the magnitude of the inverse errors on +parameters and the membership probabilities (if specified).
+Args: + data_gaia (pd.DataFrame): Gaia data for the cluster in the standard format (e.g. as in DR2.) + membership_probabilities (optional, np.ndarray): membership probabilities for the cluster. When specified, + they can increase or decrease the effect of certain stars on the mean. + key_parallax (str): Gaia parameter name. + key_parallax_error (str): Gaia parameter name. + key_r_est (str): Gaia parameter name. Corresponds to Bailer-Jones+18 distance column names. + key_r_low (str): Gaia parameter name. Corresponds to Bailer-Jones+18 distance column names. + key_r_high (str): Gaia parameter name. Corresponds to Bailer-Jones+18 distance column names. + key_result_flag (str): Gaia parameter name. Corresponds to Bailer-Jones+18 distance column names. + calculate_cbj_mean_distance (bool): whether or not to even bother calculating a mean CBJ distance. + Default: False
+Returns: + a dict, formatted with: + { + "parallax": weighted mean parallax + "parallax_error": error on the above + "inverse_parallax": inverse of the weighted mean parallax, a naive distance estimate + "distance": weighted mean distance + "distance_error": (naive, non-Bayesian) weighted error on mean_distance + }
+ +ocelot/calculate/calculate.py74 + 75 + 76 + 77 + 78 + 79 + 80 + 81 + 82 + 83 + 84 + 85 + 86 + 87 + 88 + 89 + 90 + 91 + 92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 | |
ocelot.calculate.mean_proper_motion(data_gaia, membership_probabilities=None, key_pmra='pmra', key_pmra_error='pmra_error', key_pmdec='pmdec', key_pmdec_error='pmdec_error', **kwargs)
+
+¤Calculates the weighted mean proper motion of a cluster, including error.
+Done in a very basic, frequentist way, whereby means are weighted based on the magnitude of the inverse errors on +parameters and the membership probabilities (if specified).
+Args: + data_gaia (pd.DataFrame): Gaia data for the cluster in the standard format (e.g. as in DR2.) + membership_probabilities (optional, np.ndarray): membership probabilities for the cluster. When specified, + they can increase or decrease the effect of certain stars on the mean. + key_pmra (str): Gaia parameter name. + key_pmra_error (str): Gaia parameter name. + key_pmdec (str): Gaia parameter name. + key_pmdec_error (str): Gaia parameter name.
+Returns: + a dict, formatted with: + { + "pmra": weighted mean proper motion in the right ascension direction * cos declination + "pmra_error": error on the above + "pmdec": weighted mean proper motion in the declination direction + "pmdec_error": error on the above + }
+ +ocelot/calculate/calculate.py148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 | |
ocelot.calculate.mean_radius(data_gaia, membership_probabilities=None, already_inferred_parameters=None, key_ra='ra', key_ra_error='ra_error', key_dec='dec', key_dec_error='dec_error', distance_to_use='inverse_parallax', middle_ras_raise_error=True, **kwargs)
+
+¤Produces various radius statistics on a given cluster, finding its sky location and three radii: the core, tidal +and 50% radius.
+Done in a very basic, frequentist way, whereby means are weighted based on the membership probabilities (if +specified).
+N.B. unlike the above functions, errors do not change the mean as this would potentially bias the +estimates towards being dominated by large, centrally-located stars within clusters (that have generally lower +velocities.) Hence, estimates here will be less precise but hopefully more accurate.
+Todo: add error estimation to this function (hard)
+Todo: add galactic l, b to the output of this function
+Args: + data_gaia (pd.DataFrame): Gaia data for the cluster in the standard format (e.g. as in DR2.) + membership_probabilities (optional, np.ndarray): membership probabilities for the cluster. When specified, + they can increase or decrease the effect of certain stars on the mean. + already_inferred_parameters (optional, dict): a parameter dictionary of the mean distance and proper motion. + Otherwise, this function calculates a version. + key_ra (str): Gaia parameter name. + key_ra_error (str): Gaia parameter name. + key_dec (str): Gaia parameter name. + key_dec_error (str): Gaia parameter name. + distance_to_use (str): which already inferred distance to use to convert angular radii to parsecs. + Default: "inverse_parallax" + middle_ras_raise_error (bool): whether or not a cluster having right ascensions in all ranges [0, 90), [90, 270] + and (270, 360] raises an error. The error here indicates that this cluster has extreme spherical + discontinuities (e.g. it's near a coordinate pole) and that the mean ra and mean dec will be inaccurate. + Default: True
+Returns: + a dict, formatted with: + { + # Position + "ra": ra of the cluster + "ra_error": error on the above + "dec": dec of the cluster + "dec_error": error on the above
+ # Angular radii
+ "ang_radius_50": median ang. distance from the center, i.e.angular radius of the cluster with 50% of members
+ "ang_radius_50_error": error on the above
+ "ang_radius_c": angular King's core radius of the cluster
+ "ang_radius_c_error": error on the above
+ "ang_radius_t": maximum angular distance from the center, i.e. angular King's tidal radius of the cluster
+ "ang_radius_t_error": error on the above
+
+ # Parsec radii
+ "radius_50": median distance from the center, i.e.radius of the cluster with 50% of members
+ "radius_50_error": error on the above
+ "radius_c": King's core radius of the cluster
+ "radius_c_error": error on the above
+ "radius_t": maximum distance from the center, i.e. King's tidal radius of the cluster
+ "radius_t_error": error on the above
+ }
+ocelot/calculate/calculate.py197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 | |
ocelot.calculate.mean_internal_velocity_dispersion(data_gaia, membership_probabilities=None, already_inferred_parameters=None, key_pmra='pmra', key_pmra_error='pmra_error', key_pmdec='pmdec', key_pmdec_error='pmdec_error', distance_to_use='inverse_parallax', **kwargs)
+
+¤Estimates the internal velocity dispersion of a cluster.
+Done in a very basic, frequentist way, whereby means are weighted based on the membership probabilities (if +specified).
+N.B. unlike the above functions, errors do not change the mean as this would potentially bias the +estimates towards being dominated by large, centrally-located stars within clusters (that have generally lower +velocities.) Hence, estimates here will be less precise but hopefully more accurate.
+Todo: add error on velocity dispersion estimation to this function (hard)
+Args: + data_gaia (pd.DataFrame): Gaia data for the cluster in the standard format (e.g. as in DR2.) + membership_probabilities (optional, np.ndarray): membership probabilities for the cluster. When specified, + they can increase or decrease the effect of certain stars on the mean. + already_inferred_parameters (optional, dict): a parameter dictionary of the mean distance and proper motion. + Otherwise, this function calculates a version. + key_pmra (str): Gaia parameter name. + key_pmra_error (str): Gaia parameter name. + key_pmdec (str): Gaia parameter name. + key_pmdec_error (str): Gaia parameter name. + distance_to_use (str): which already inferred distance to use to convert proper motions to m/s velocities. + Default: "inverse_parallax"
+Returns: + a dict, formatted with: + { + "v_ra_dec": mean velocity dispersion of the cluster + "v_ra_dec_error": error on the above + }
+ +ocelot/calculate/calculate.py318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 | |
ocelot.calculate.all_statistics(data_gaia, membership_probabilities=None, parameter_inference_mode='mean', override_membership_probabilities_being_off=False, middle_ras_raise_error=True, **kwargs)
+
+¤Wraps all subfunctions in ocelot.calculate and calculates all the stats you could possibly ever want.
+Args: + data_gaia (pd.DataFrame): Gaia data for the cluster in the standard format (e.g. as in DR2.) + membership_probabilities (optional, np.ndarray): membership probabilities for the cluster. When specified, + they can increase or decrease the effect of certain stars on the mean. + parameter_inference_mode (str): mode to use when inferring parameters. + override_membership_probabilities_being_off (bool): little check to stop membership probabilities from being + used for now, as these actually mess up the + middle_ras_raise_error (bool): whether or not a cluster having right ascensions in all ranges [0, 90), [90, 270] + and (270, 360] raises an error. The error here indicates that this cluster has extreme spherical + discontinuities (e.g. it's near a coordinate pole) and that the mean ra and mean dec will be inaccurate. + Default: True + **kwargs: keyword arguments to pass to the calculation functions this one calls.
+Returns: + a dict, containing the following parameters for the cluster: + 'n_stars', 'ra', 'ra_error', 'dec', 'dec_error', 'ang_radius_50', 'ang_radius_50_error', 'ang_radius_c', + 'ang_radius_c_error', 'ang_radius_t', 'ang_radius_t_error', 'radius_50', 'radius_50_error', 'radius_c', + 'radius_c_error', 'radius_t', 'radius_t_error', 'parallax', 'parallax_error', 'inverse_parallax', + 'inverse_parallax_l68', 'inverse_parallax_u68', 'distance', 'distance_error', 'pmra', 'pmra_error', 'pmdec', + 'pmdec_error', 'v_internal_tangential', 'v_internal_tangential_error', 'parameter_inference_mode' + where parameter_inference_mode is the only one added by this function itself, and is a copy of the keyword arg + this function holds.
+ +ocelot/calculate/calculate.py383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 | |
ocelot.calculate.king_surface_density(r_values, r_core, r_tidal, normalise=False)
+
+¤Computes the King surface density (King 1962, equation 14) given the three parameters. Can take vectorised input. +Will return the surface density per square unit expected at a distance r_values from the core of the cluster.
+Valid only for: + 0 <= r < r_tidal (0 elsewhere - this is checked internally) + 0 < r_core < r_tidal (raises an error if not the case)
+Args: + r_values (float or np.ndarray): r values to compute the surface density at. + r_core (float): the core radius of the cluster. + r_tidal (float): the tidal radius of the cluster. + normalise (bool): whether or not to return the normalised King surface density profile, calculated + numerically. + Default: False
+Returns: + a float or array of floats of the surface density for the cluster.
+ +ocelot/calculate/profile.py6 + 7 + 8 + 9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 | |
ocelot.calculate.king_surface_density_fast(r_values, r_core, r_tidal)
+
+¤Computes the King surface density (King 1962, equation 14) given the three parameters. Can take vectorised input. +Fast version intended for use with random sampling - it has no checks and cannot be normalised! Be careful!
+Valid only for: + 0 <= r < r_tidal (NOT CHECKED in this function!) + 0 < r_core < r_tidal (NOT CHECKED in this function!)
+Args: + r_values (np.ndarray): r values to compute the surface density at. Must be a numpy array! + r_core (float): the core radius of the cluster. + r_tidal (float): the tidal radius of the cluster.
+Returns: + a float or array of floats of the surface density for the cluster.
+ +ocelot/calculate/profile.py72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 | |
ocelot.calculate.sample_2d_king_profile(r_core, r_tidal, n_samples, seed=None, oversampling_factor=10, return_generator=False)
+
+¤Samples a 2D King profile to return n_samples sample radii.
+Valid only for: + 0 < r_core < r_tidal
+Args: + r_core (float): the core radius of the cluster. + r_tidal (float): the tidal radius of the cluster. + n_samples (int): the number of samples to generate. + seed (int, optional): the seed of the random number generator. Default: None. + oversampling_factor (float): how many times n_samples to generate each step, which helps to make sure that + enough samples are quickly generated in just one or two loops. Default: 10. + return_generator (bool): whether or not to return the numpy random number generator created. Default: False
+Returns: + an array of sample radii of size n_samples, plus the random generator if return_generator==True.
+ +ocelot/calculate/profile.py97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 | |
ocelot.calculate.sample_1d_king_profile(r_core, r_tidal, n_samples, seed=None, oversampling_factor=10)
+
+¤Samples a 1D King profile (e.g. useful to get line of sight distances from the center of a cluster.) Uses a +little trick - assumes that we're looking at the cluster side-on and removes the not-line-of-sight axis as if we +were looking at it from the front. (This is because I cba to work out a 1D profile and more to the point, I couldn't +fucking find one)
+Todo: change this to using the strip density g(x), which I think could do this better...
+Valid only for: + 0 < r_core < r_tidal
+Args: + r_core (float): the core radius of the cluster. + r_tidal (float): the tidal radius of the cluster. + n_samples (int): the number of samples to generate. + seed (int, optional): the seed of the random number generator. Default: None. + oversampling_factor (float): how many times n_samples to generate each step, which helps to make sure that + enough samples are quickly generated in just one or two loops. Default: 10.
+Returns: + an array of sample radii of size n_samples
+ +ocelot/calculate/profile.py146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 | |