Cosmicflows-4 Distance-Velocity API¶
This notebook explains how you can simply interact with Cosmicflows calculators within your Python code.
Note: This API can be also queried in any programming language of choice.
- Communication method: POST, GET
- Input data: JSON
CF4 DV-calculator API: http://edd.ifa.hawaii.edu/CF4calculator/api.php
- Processing large lists of galaxies provided in JSON format. Below,
CF4_list
facilitates the data preparation for API calls. Refer to Example 3 in this notebook for further details. The maximum number of galaxies per query is limited to 500.
Python Example¶
Simply copy the following functions into your code¶
The following code snippets provide interface functions to query each of the calculators.
Required packages:
- requests (to handle the online API requests)
- json (to translate between Python dictionaries and json format)
import requests
import json
def CF4(alpha, delta, system='supergalactic',
parameter='distance', value=20):
"""
Inputs:
alpha: (float) [deg]
first coordinate parameter (RA, Glon, SGL)
delta: (float) [deg]
second coordinate parameter (Dec, Glat, SGB)
system: (string)
coordinate system:
Options are:
"equatorial"
"galactic"
"supergalactic"
parameter: (string)
the quantity whose value is provided
Options are:
"distance"
"velocity"
value: (float)
the value of the input quantity
distance in [Mpc] and velocity in [km/s]
Output:
A python dictionary which contains the distance and velocity of the
given object and the coordinate of the object in different systems
"""
coordinate = [float(alpha), float(delta)]
query = {
'coordinate': coordinate,
'system': system,
'parameter': parameter,
'value': float(value)
}
headers = {'Content-type': 'application/json'}
API_url = 'http://edd.ifa.hawaii.edu/CF4calculator/api.php'
try:
r = requests.get(API_url, data=json.dumps(query), headers=headers)
output = json.loads(r.text) # a python dictionary
except:
print("Something went wrong!")
print("Please check your intput parameters ...")
output = None
return output
Large lists of galaxies¶
- The following function, makes API calls with a large list of galaxies.
- See "example 5" to learn how to submit a list of galaxies and process the returned results.
import requests
import json
def CF4_list(alpha_lst, delta_lst, system='supergalactic',
parameter='distance', values=[20]):
"""
Inputs:
alpha: [array] (float) [deg]
first coordinate parameter (RA, Glon, SGL)
delta: [array] (float) [deg]
second coordinate parameter (Dec, Glat, SGB)
system: (string)
coordinate system:
Options are:
"equatorial"
"galactic"
"supergalactic"
parameter: (string)
the quantity whose value is provided
Options are:
"distance"
"velocity"
value: [array] (float)
the value of the input quantity
distance in [Mpc] and velocity in [km/s]
Output:
A python dictionary which contains the distance and velocity of the
given object and the coordinate of the object in different systems
"""
if len(alpha_lst)!=len(delta_lst) or len(delta_lst)!=len(values):
return {"message": "Inconsistent sizes of the input arrays !"}
payload = {}
payload["galaxies"] = []
for i in range(len(alpha_lst)):
coordinate = [float(alpha_lst[i]), float(delta_lst[i])]
galDict = {
'coordinate': coordinate,
'system': system,
'parameter': parameter,
'value': float(values[i])
}
payload["galaxies"].append(galDict)
headers = {'Content-type': 'application/json'}
API_url = 'http://edd.ifa.hawaii.edu/CF4calculator/api.php'
try:
r = requests.get(API_url, data=json.dumps(payload), headers=headers)
output = json.loads(r.text) # a python dictionary
except:
print("Something went wrong!")
print("Please check your intput parameters ...")
output = None
return output
Example 1¶
Sending a request to the Cosmicflows-4 D-V calculator (d < 500 Mpc)¶
http://edd.ifa.hawaii.edu/CF4calculator

example_1 = CF4(102, -2, system='supergalactic', parameter='velocity', value=1000)
example_1
{'message': 'Success', 'RA': 187.78917, 'Dec': 13.33386, 'Glon': 282.96547, 'Glat': 75.4136, 'SGL': 102.0, 'SGB': -2.0, 'observed': {'velocity': 1000.0, 'distance': [16.48, 18.14, 22.96]}}
Here, example_1 is a Python dictionary. The keys of the output dictionary are self explanatory.
There is an additional key, message that holds the message of the backend code that generates the output values. In case of an unsuccessful API, message holds the cause of error that helps to correct the mistaken outputs.
In the following cell we show how to extract distance from the output of the calucaltor. Please note that the generated distance is always provided as a list, becuase multiple distances can be associated to one radial velocity.
distance_1 = example_1["observed"]["distance"]
distance_1
[16.48, 18.14, 22.96]
Example 2¶

How to extract the radial velocity of an object with a given distance
SGL = 102 deg
SGB = -2 deg
Coordinate system = supergalactic
input distance = 250 Mpc
Calculator: CF4 (http://edd.ifa.hawaii.edu/CF4calculator)
example_2 = CF4(102, -2, system='supergalactic', parameter='distance', value=250)
example_2
{'message': 'Success', 'RA': 187.78917, 'Dec': 13.33386, 'Glon': 282.96547, 'Glat': 75.4136, 'SGL': 102.0, 'SGB': -2.0, 'observed': {'velocity': 19190.43, 'distance': [250.0]}, 'peculiar_velocity': {'SG_Vx': -461.45, 'SG_Vy': 775.58, 'SG_Vz': -3.99}}
The peculiar velocity of a test particle in the CF4 field is stored as peculiar_velocity
. The velocity components are presented along the three coordinate axes of the Supergalactic Cartesian system.
Loading the sample data set¶
We use pandas
package to read data from a csv file.
import pandas as pd
import numpy as np
# reading the list into a pandas dataFrame
data = pd.read_csv("../test_api.csv")
# modifying the headers
for col in data.columns:
newcol = col.split("(")[0].strip()
data.rename(columns={col:newcol}, inplace=True)
data
id | RA | Dec | Vls | |
---|---|---|---|---|
0 | 27 | 6.1965 | -20.7324 | 16092 |
1 | 76 | 9.8597 | 6.7340 | 12139 |
2 | 119 | 14.0672 | -1.2561 | 13460 |
3 | 147 | 17.1579 | 2.2684 | 13163 |
4 | 151 | 17.2130 | -15.4072 | 16064 |
5 | 168 | 18.7404 | 0.4311 | 13597 |
6 | 189 | 20.8597 | 1.7049 | 9720 |
7 | 193 | 21.2814 | 8.6992 | 14676 |
8 | 194 | 21.4952 | -1.3394 | 5495 |
9 | 195 | 21.7281 | 19.2139 | 12841 |
Function CF4_list
¶
(define above) preprocesses a list of galaxies and sends a large JSON payload that includes a possibly large list of galaxies. To avoid overloading, the maximum number of galaxies per query is limited to 500.
Returned distances are stored in a list, because in some cases multiple distances are mapped into the same distance.
Note: The returned results are presented in the JSON format. In the following cell, we assume that all queried values in the list are valid and there is no error in the output results. In this case, the output JSON results could be simply transformed to a pandas dataframe.
N = len(data)
print("Number of objects: ", N)
## list of values
ra = data.RA.values # deg
dec = data.Dec.values # deg
vls = data.Vls.values # km/s
output = CF4_list(ra, dec, system='equatorial', parameter='velocity',
values=vls)
## output is a python dictionary, that holds the results for all indivual galaxies in a
## list under the "results" key.
# assuming that all input values are valid and no error messages is present in the "ouput" dictionary
results = pd.DataFrame.from_dict(output["results"])
results.head()
Number of objects: 10
message | RA | Dec | Glon | Glat | SGL | SGB | observed | |
---|---|---|---|---|---|---|---|---|
0 | Success | 6.19650 | -20.7324 | 77.93223 | -81.17223 | 274.47665 | 1.29298 | {'velocity': 16092.0, 'distance': [219.99]} |
1 | Success | 9.85969 | 6.7340 | 117.59732 | -56.01341 | 301.90532 | 5.54791 | {'velocity': 12139.0, 'distance': [160.54]} |
2 | Success | 14.06719 | -1.2561 | 125.69723 | -64.10191 | 295.32585 | -0.64141 | {'velocity': 13460.0, 'distance': [180.51]} |
3 | Success | 17.15789 | 2.2684 | 131.62935 | -60.31268 | 299.55862 | -2.65912 | {'velocity': 13163.0, 'distance': [176.03]} |
4 | Success | 17.21300 | -15.4072 | 142.85777 | -77.60009 | 282.44606 | -7.34966 | {'velocity': 16064.0, 'distance': [221.26]} |
Preparing the output table¶
Here, we append a few columns of the results table to the input data table.
data["Glon"] = results["Glon"]
data["Glat"] = results["Glat"]
data["SGL"] = results["SGL"]
data["SGB"] = results["SGB"]
data["velocity_observed"] = results.apply(lambda row: row.observed["velocity"], axis=1)
data["distance_observed"] = results.apply(lambda row: row.observed["distance"], axis=1)
data.head()
id | RA | Dec | Vls | Glon | Glat | SGL | SGB | velocity_observed | distance_observed | |
---|---|---|---|---|---|---|---|---|---|---|
0 | 27 | 6.1965 | -20.7324 | 16092 | 77.93223 | -81.17223 | 274.47665 | 1.29298 | 16092.0 | [219.99] |
1 | 76 | 9.8597 | 6.7340 | 12139 | 117.59732 | -56.01341 | 301.90532 | 5.54791 | 12139.0 | [160.54] |
2 | 119 | 14.0672 | -1.2561 | 13460 | 125.69723 | -64.10191 | 295.32585 | -0.64141 | 13460.0 | [180.51] |
3 | 147 | 17.1579 | 2.2684 | 13163 | 131.62935 | -60.31268 | 299.55862 | -2.65912 | 13163.0 | [176.03] |
4 | 151 | 17.2130 | -15.4072 | 16064 | 142.85777 | -77.60009 | 282.44606 | -7.34966 | 16064.0 | [221.26] |
# saving the resulting dataFrame that contains a distance column
data.to_csv('output_api.csv')
A copy of the output file is stored here: output_api.csv.
Example 4¶
Using curl
to make API requests¶
- Prepare a JSON payload and save it in the same directory as this notebook. We call this file
input.json
. - Use
curl
or other favorite clients to send API requests - In this example, coordinates of 3 galaxies have been included in the payload
- In the case of the third galaxy, Latitude is not valid as it should be between -90 and 90 degrees, which would be reflected in the corresponding record in the output JSON file
%%writefile "input.json"
{
"galaxies":[
{
"coordinate":[
6.19,
-20.73
],
"system":"equatorial",
"parameter":"distance",
"value":10
},
{
"coordinate":[
102,
-2
],
"system":"supergalactic",
"parameter":"velocity",
"value":1000
},
{
"coordinate":[
50,
120
],
"system":"supergalactic",
"parameter":"velocity",
"value":1000
}
]
}
Overwriting input.json
Making an API call¶
out_file = "output.json"
! curl -d @input.json -H "Content-Type application/json" \
http://edd.ifa.hawaii.edu/CF4calculator/api.php > {out_file}
% Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 1075 0 550 100 525 155 148 0:00:03 0:00:03 --:--:-- 303
Loading the results¶
Here, out_dict
is a python dictionary.
out_dict = json.load(open(out_file, "r"))
out_dict
{'results': [{'message': 'Success', 'RA': 6.19, 'Dec': -20.73, 'Glon': 77.91346, 'Glat': -81.16636, 'SGL': 274.47712, 'SGB': 1.29949, 'observed': {'velocity': 989.33, 'distance': [10.0]}, 'peculiar_velocity': {'SG_Vx': -288.85, 'SG_Vy': 96.51, 'SG_Vz': -345.08}}, {'message': 'Success', 'RA': 187.78917, 'Dec': 13.33386, 'Glon': 282.96547, 'Glat': 75.4136, 'SGL': 102.0, 'SGB': -2.0, 'observed': {'velocity': 1000.0, 'distance': [16.48, 18.14, 22.96]}}, {'message': 'Wrong Input (value out of range), Latitutde must be between -90 and 90 degrees'}]}
How to acknowledge this work¶
*If you use the results of this work in your research or other applications, please cite