API - pycf3 module

Python client for several cosmic distance calculators.

Calculators:

  • Cosmicflows-3 Distance-Velocity Calculator at distances

  • Numerical Action Methods model

More information: http://edd.ifa.hawaii.edu/CF3calculator/

For citation check:

https://github.com/quatrope/pycf3/blob/master/README.rst

class pycf3.AbstractClient(session: requests.sessions.Session = NOTHING, cache: Union[diskcache.core.Cache, diskcache.fanout.FanoutCache] = NOTHING, cache_expire: Optional[float] = None)

Abstract base class for all clients.

Parameters
calculate_distance(velocity, *, ra=None, dec=None, glon=None, glat=None, sgl=None, sgb=None, **get_kwargs)

Calculate a distance based on the given velocity and location.

The mandatory parameters are velocity and a position expressed in two components depending on the chosen coordinate system:

  • ra and dec for an equatorial system.

  • glon and glat for a galactic system.

  • sgl and sgb for a supergalactic system.

Coordinates cannot be mixed between systems, and must be expressed in J2000 as 360° decimal.

The returned distance(s) are expressed in Mpc, and potentially can be more than one value.

Parameters
  • velocity (int or float) – Model velocity in km/s.

  • ra (int or float (optional)) – Right ascension. If you provide ra you need to provide also dec.

  • dec (int or float (optional)) – Declination. dec must be >= -90 and <= 90. If you provide dec you need to provide also ra.

  • glon (int or float (optional)) – Galactic longitude. If you provide glon you need to provide also glat.

  • glat (int or float (optional)) – Galactic latitude. glat must be >= -90 and <= 90. If you provide glat you need to provide also glon.

  • sgl (int or float (optional)) – Super-galactic longitude. If you provide sgl you need to provide also sgb.

  • sgb (int or float (optional)) – Super-galactic latitude. sgb must be >= -90 and <= 90. If you provide sgb you need to provide also sgl.

  • get_kwargs – Optional arguments that request.get takes.

Returns

Result object that automatically parses the entire model returned by the remote calculator.

Return type

pycf3.Result

calculate_velocity(distance, *, ra=None, dec=None, glon=None, glat=None, sgl=None, sgb=None, **get_kwargs)

Calculate a velocity based on the given distance and location.

The mandatory parameters are distance and a position expressed in two components depending on the chosen coordinate system:

  • ra and dec for an equatorial system.

  • glon and glat for a galactic system.

  • sgl and sgb for a supergalactic system.

Coordinates cannot be mixed between systems, and must be expressed in J2000 as 360° decimal.

The returned velocity are expressed in Km/s.

Parameters
  • distance (int or float) – Distance(s) in Mpc.

  • ra (int or float (optional)) – Right ascension. If you provide ra you need to provide also dec.

  • dec (int or float (optional)) – Declination. dec must be >= -90 and <= 90. If you provide dec you need to provide also ra.

  • glon (int or float (optional)) – Galactic longitude. If you provide glon you need to provide also glat.

  • glat (int or float (optional)) – Galactic latitude. glat must be >= -90 and <= 90. If you provide glat you need to provide also glon.

  • sgl (int or float (optional)) – Super-galactic longitude. If you provide sgl you need to provide also sgb.

  • sgb (int or float (optional)) – Super-galactic latitude. sgb must be >= -90 and <= 90. If you provide sgb you need to provide also sgl.

  • get_kwargs – Optional arguments that request.get takes.

Returns

Result object that automatically parses the entire model returned by the remote calculator.

Return type

pycf3.Result

Search by equatorial coordinates.

The coordinates are expressed in J2000 as 360° decimal.

Deprecated since version 2020.12: “Use calculate_velocity or calculate_distance instead”

Parameters
  • ra (int or float (default: 187.78917)) – Right ascension.

  • dec (int or float (default: 13.33386)) – Declination. dec must be >= -90 and <= 90

  • distance (int, float or None (default: None)) – Distance(s) in Mpc.

  • velocity (int, float or None (default: None)) – Velocity in km/s. The returned distance potentially can be more than ine value.

  • get_kwargs – Optional arguments that request.get takes.

Returns

Result object that automatically parses the entire model returned by the remote calculator.

Return type

pycf3.Result

Search by galactic coordinates.

The coordinates are expressed in J2000 as 360° decimal.

Deprecated since version 2020.12: “Use calculate_velocity or calculate_distance instead”

Parameters
  • glon (int or float (default: 282.96547)) – Galactic longitude.

  • glat (int or float (default: 75.41360)) – Galactic latitude. dec must be >= -90 and <= 90

  • distance (int, float or None (default: None)) – Distance(s) in Mpc.

  • velocity (int, float or None (default: None)) – Velocity in km/s. The returned distance potentially can be more than ine value.

  • get_kwargs – Optional arguments that request.get takes.

Returns

Result object that automatically parses the entire model returned by the remote calculator.

Return type

pycf3.Result

Search super-galactic coordinates.

The coordinates are expressed in J2000 as 360° decimal.

Deprecated since version 2020.12: “Use calculate_velocity or calculate_distance instead”

Parameters
  • sgl (int or float (default: 102)) – Super-galactic longitude.

  • sgb (int or float (default: -2)) – Super-galactic latitude. dec must be >= -90 and <= 90

  • distance (int, float or None (default: None)) – Distance(s) in Mpc.

  • velocity (int, float or None (default: None)) – Velocity in km/s. The returned distance potentially can be more than ine value.

  • get_kwargs – Optional arguments that request.get takes.

Returns

Result object that automatically parses the entire model returned by the remote calculator.

Return type

pycf3.Result

class pycf3.CF3(session: requests.sessions.Session = NOTHING, cache: Union[diskcache.core.Cache, diskcache.fanout.FanoutCache] = NOTHING, cache_expire: Optional[float] = None)

Client for the Cosmicflows-3 Distance-Velocity Calculator 3.

It computes expectation distances or velocities based on smoothed velocity field from the Wiener filter model of Graziani et al. 2019 4.

More information: http://edd.ifa.hawaii.edu/CF3calculator/ .

Parameters

References

3

Kourkchi, E., Courtois, H. M., Graziani, R., Hoffman, Y., Pomarede, D., Shaya, E. J., & Tully, R. B. (2020). Cosmicflows-3: Two Distance-Velocity Calculators. The Astronomical Journal, 159(2), 67.

4

Graziani, R., Courtois, H. M., Lavaux, G., Hoffman, Y., Tully, R. B., Copin, Y., & Pomarède, D. (2019). The peculiar velocity field up to z∼ 0.05 by forward-modelling Cosmicflows-3 data. Monthly Notices of the Royal Astronomical Society, 488(4), 5438-5451.

MAX_DISTANCE = 200

Maximum distance to adjust the velocity.

MAX_VELOCITY = 15000

Maximum velocity to adjust the distance.

exception pycf3.CFDeprecationWarning

Custom class to inform that some functionality is in desuse.

exception pycf3.MixedCoordinateSystemError

Raised when the parameters are from different coordinates systems.

class pycf3.NAM(session: requests.sessions.Session = NOTHING, cache: Union[diskcache.core.Cache, diskcache.fanout.FanoutCache] = NOTHING, cache_expire: Optional[float] = None)

Client for the NAM Distance-Velocity Calculator 1.

Compute expectation distances or velocities based on smoothed velocity field from the Numerical Action Methods model of Shaya et al. 2017. 2.

More information: http://edd.ifa.hawaii.edu/NAMcalculator.

Parameters

References

1

Kourkchi, E., Courtois, H. M., Graziani, R., Hoffman, Y., Pomarede, D., Shaya, E. J., & Tully, R. B. (2020). Cosmicflows-3: Two Distance-Velocity Calculators. The Astronomical Journal, 159(2), 67.

2

Shaya, E. J., Tully, R. B., Hoffman, Y., & Pomarède, D. (2017). Action dynamics of the local supercluster. The Astrophysical Journal, 850(2), 207.

MAX_DISTANCE = 38

Maximum distance to adjust the velocity.

MAX_VELOCITY = 2400

Maximum velocity to adjust the distance.

class pycf3.NoCache

Implements a minimalist no-cache for disk-cache.

expire(now=None, retry=False)

Return 0.

get(key, default=None, *args, **kwargs)

Return the default.

set(key, value, *args, **kwargs)

Return True.

class pycf3.Result(calculator, url, coordinate, calculated_by, alpha, delta, distance, velocity, response_)

Parsed result.

Parameters
  • calculator (str) – The used calculator.

  • url (str) – The url of the calculator.

  • coordinate (Coordinate) – Coordinate system used to create this result.

  • alpha (int or float) – \(\alpha\) value for the coordinate system.

  • delta (int or float) – \(\delta\) value for the coordinate system.

  • distance (int, float or None) – Distance used to calculate the velocity in Mpc.

  • velocity (int, float or None) – Velocity used to calculate the distance in Km/s.

response_

Original response object create by the requests library. More information: https://2.python-requests.org

Type

requests.Response

observed_distance_

Observed distances.

Type

numpy.ndarray

observed_velocity_

Observed velocity

Type

float

adjusted_distance_

Cosmologically adjusted distances.

Type

numpy.ndarray

adjusted_velocity_

Cosmologically adjusted velocity, \(V^c_{ls}\).

Type

float

calculated_at_

Coordinates in all the three supported systems.

Type

pycf3.CalculatedAt

property json_

Proxy to response_.json().

property search_at_

Proxy to response.calculated_at_.

Deprecated since version 2020.12: “Use calculated_at instead”

property search_by

Proxy to response.calculated_by.

Deprecated since version 2020.12: “Use calculated_by instead”

class pycf3.RetrySession(retries=3, backoff_factor=0.3, status_forcelist=(500, 502, 504), **session_options)

Session with retry.

Parameters
  • retries (int (default: 3)) – Total number of retries to allow. It’s a good idea to set this to some sensibly-high value to account for unexpected edge cases and avoid infinite retry loops. Set to 0 to fail on the first retry.

  • backoff_factor (float (default: 0.3)) –

    A backoff factor to apply between attempts after the second try (most errors are resolved immediately by a second try without a delay). urllib3 will sleep for:

    {backoff factor} * (2 ** ({number of total retries} - 1))

    seconds. If the backoff_factor is 0.1, then sleep() will sleep for [0.0s, 0.2s, 0.4s, ...] between retries. It will never be longer than urllib3.Retry.BACKOFF_MAX.

  • status_forcelist (iterable (default: 500, 502, 504)) – A set of integer HTTP status codes that we should force a retry on. A retry is initiated if the request method is in method_whitelist and the response status code is in status_forcelist. By default, this is 500, 502, 504.