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:
- class pycf3.AbstractClient(session: Session = NOTHING, cache: Union[Cache, FanoutCache] = NOTHING, cache_expire: Optional[float] = None)¶
Abstract base class for all clients.
- Parameters:
session (
pycf3.Session
(default:None
)) – The session to use to send the requests. By default apyc3.RetrySession
with 3 retry is created. More info: https://2.python-requests.org, https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html.cache (
diskcache.Cache
,diskcache.Fanout
,) –pycf3.NoCache
orNone
(default:None
) Any instance ofdiskcache.Cache
,diskcache.Fanout
orNone
(Default). If it’sNone
adiskcache.Cache
istance is created with the parameterdirectory = pycf3.DEFAULT_CACHE_DIR
. More information: http://www.grantjenks.com/docs/diskcachecache_expire (
float
or None (default=``None``)) – Seconds until item expires (defaultNone
, no expiry) More information: http://www.grantjenks.com/docs/diskcache
- 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
anddec
for an equatorial system.glon
andglat
for a galactic system.sgl
andsgb
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
orfloat
) – Model velocity in km/s.ra (
int
orfloat
(optional)) – Right ascension. If you providera
you need to provide alsodec
.dec (
int
orfloat
(optional)) – Declination.dec
must be >= -90 and <= 90. If you providedec
you need to provide alsora
.glon (
int
orfloat
(optional)) – Galactic longitude. If you provideglon
you need to provide alsoglat
.glat (
int
orfloat
(optional)) – Galactic latitude.glat
must be >= -90 and <= 90. If you provideglat
you need to provide alsoglon
.sgl (
int
orfloat
(optional)) – Super-galactic longitude. If you providesgl
you need to provide alsosgb
.sgb (
int
orfloat
(optional)) – Super-galactic latitude.sgb
must be >= -90 and <= 90. If you providesgb
you need to provide alsosgl
.get_kwargs – Optional arguments that
request.get
takes.
- Returns:
Result object that automatically parses the entire model returned by the remote calculator.
- Return type:
- 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
anddec
for an equatorial system.glon
andglat
for a galactic system.sgl
andsgb
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
orfloat
) – Distance(s) in Mpc.ra (
int
orfloat
(optional)) – Right ascension. If you providera
you need to provide alsodec
.dec (
int
orfloat
(optional)) – Declination.dec
must be >= -90 and <= 90. If you providedec
you need to provide alsora
.glon (
int
orfloat
(optional)) – Galactic longitude. If you provideglon
you need to provide alsoglat
.glat (
int
orfloat
(optional)) – Galactic latitude.glat
must be >= -90 and <= 90. If you provideglat
you need to provide alsoglon
.sgl (
int
orfloat
(optional)) – Super-galactic longitude. If you providesgl
you need to provide alsosgb
.sgb (
int
orfloat
(optional)) – Super-galactic latitude.sgb
must be >= -90 and <= 90. If you providesgb
you need to provide alsosgl
.get_kwargs – Optional arguments that
request.get
takes.
- Returns:
Result object that automatically parses the entire model returned by the remote calculator.
- Return type:
- equatorial_search(ra=187.78917, dec=13.33386, distance=None, velocity=None, **get_kwargs)¶
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
orfloat
(default:187.78917
)) – Right ascension.dec (
int
orfloat
(default:13.33386
)) – Declination. dec must be >= -90 and <= 90distance (
int
,float
orNone
(default:None
)) – Distance(s) in Mpc.velocity (
int
,float
orNone
(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:
- galactic_search(glon=282.96547, glat=75.4136, distance=None, velocity=None, **get_kwargs)¶
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
orfloat
(default:282.96547
)) – Galactic longitude.glat (
int
orfloat
(default:75.41360
)) – Galactic latitude. dec must be >= -90 and <= 90distance (
int
,float
orNone
(default:None
)) – Distance(s) in Mpc.velocity (
int
,float
orNone
(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:
- supergalactic_search(sgl=102.0, sgb=-2.0, distance=None, velocity=None, **get_kwargs)¶
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
orfloat
(default:102
)) – Super-galactic longitude.sgb (
int
orfloat
(default:-2
)) – Super-galactic latitude. dec must be >= -90 and <= 90distance (
int
,float
orNone
(default:None
)) – Distance(s) in Mpc.velocity (
int
,float
orNone
(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:
- class pycf3.CF3(session: Session = NOTHING, cache: Union[Cache, 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:
session (
pycf3.Session
(default:None
)) – The session to use to send the requests. By default apyc3.RetrySession
with 3 retry is created. More info: https://2.python-requests.org, https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html.cache (
diskcache.Cache
,diskcache.Fanout
,) –pycf3.NoCache
orNone
(default:None
) Any instance ofdiskcache.Cache
,diskcache.Fanout
orNone
(Default). If it’sNone
adiskcache.Cache
istance is created with the parameterdirectory = pycf3.DEFAULT_CACHE_DIR
. More information: http://www.grantjenks.com/docs/diskcachecache_expire (
float
or None (default=``None``)) – Seconds until item expires (defaultNone
, no expiry) More information: http://www.grantjenks.com/docs/diskcache
References
- 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: Session = NOTHING, cache: Union[Cache, 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:
session (
pycf3.Session
(default:None
)) – The session to use to send the requests. By default apyc3.RetrySession
with 3 retry is created. More info: https://2.python-requests.org, https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html.cache (
diskcache.Cache
,diskcache.Fanout
,) –pycf3.NoCache
orNone
(default:None
) Any instance ofdiskcache.Cache
,diskcache.Fanout
orNone
(Default). If it’sNone
adiskcache.Cache
istance is created with the parameterdirectory = pycf3.DEFAULT_CACHE_DIR
. More information: http://www.grantjenks.com/docs/diskcachecache_expire (
float
or None (default=``None``)) – Seconds until item expires (defaultNone
, no expiry) More information: http://www.grantjenks.com/docs/diskcache
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
orfloat
) – \(\alpha\) value for the coordinate system.delta (
int
orfloat
) – \(\delta\) value for the coordinate system.distance (
int
,float
orNone
) – Distance used to calculate the velocity in Mpc.velocity (
int
,float
orNone
) – 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 to0
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
, thensleep()
will sleep for[0.0s, 0.2s, 0.4s, ...]
between retries. It will never be longer thanurllib3.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 is500, 502, 504
.