Filtering and sorting

Filters

Dace proposes for certain queries the use of filters through the filters argument.

The filters work in the same way as those offered on the DACE online site. They consist of a dictionary type object (key-value), where the key is the parameter that we want to filter and the value will be the desired filtering operation.

Here is an example :

# A python dictionary defining a filter
# In key the parameter to filter : obj_id_catname
# In value the filtering operation: contains

# This will filter all data containing "HD" in the obj_id_catname parameter
filters: dict = {
    'obj_id_catname': {
        'contains': ['HD']
    }
}

Filterable parameters

There are different filterable parameters and those are retrievable for each module using the query_database function.

Here is an example to get the filterable parameters of the exoplanet module :

from dace_query.exoplanet import Exoplanet
result: dict = Exoplanet.query_database(limit=10, output_format='dict')

# The parameters for the exoplanet module
exoplanet_parameter_names = list(result.keys()))

Available filters

contains - not contains

This filter filters the chosen parameter if it contains or not the value sought.

These two filters can be applied to string type parameters.

Example : It returns planets that do not contain “HD” in their name.

from dace_query.exoplanet import Exoplanet

# not contains
filters: dict = {
    'obj_id_catname': {
        'notContains': ['HD']
    }
}
values = Exoplanet.query_database(filters=filters, limit=10)

# contains
filters: dict = {
    'obj_id_catname': {
        'contains': ['HD']
    }
}
values = Exoplanet.query_database(filters=filters, limit=10)

equal - notEqual

This filter filters the chosen parameter if it is equal or not to the value sought.

These two filters can be applied to string, float and int type parameters.

Example : It returns planets with names equal to “Kepler-444 A e” and “Gliese 433 c”.

from dace_query.exoplanet import Exoplanet

# not equal
filters: dict = {
    'obj_id_catname': {
        'notEqual': ['Kepler-444 A e', 'Gliese 433 c']
    }
}
values = Exoplanet.query_database(filters=filters, limit=10)

# equal
filters: dict = {
    'obj_id_catname': {
        'equal': ['Kepler-444 A e', 'Gliese 433 c']
    }
}
values = Exoplanet.query_database(filters=filters, limit=10)

empty

This filter filters the chosen parameter depending on whether its value is empty or not.

This filter can be applied to string and boolean type parameters.

Example : It returns planets where publication link is available.

from dace_query.exoplanet import Exoplanet
filters: dict = {
'pub_ads_link': {
        'empty': False
    }
}
values = Exoplanet.query_database(filters=filters, limit=10)

min - max

This filter filters the chosen parameter if its value is between the specified minimum and maximum.

This filter can be applied to float and int type parameters.

Example : It returns planets with mass between 0.01 and 0.04 Jupiter mass.

from dace_query.exoplanet import Exoplanet
filters: dict = {
    'obj_phys_mass_mjup': {
        'min': 0.01,
        'max': 0.04
    }
}
values = Exoplanet.query_database(filters=filters, limit=10)

is

This filter filters the chosen parameter depending on whether its value is True or False.

This filter can be applied to boolean type parameters.

Example: It returns spectroscopic observations where the spectrum is available.

from dace_query.spectroscopy import Spectroscopy
filters: dict = {
    'db_spectrum_available': {
        'is': True
    }
}
values = Spectroscopy.query_database(filters=filters, limit=10)

Advanced usage example

The parameters to be filtered and the filters themselves can be combined.

Here is an example :

It returns planets :

• with name containing “TOI” and “HD” but not equal to “TOI-755 b’

• ( and ) with orbital period between “2.5” and “3” days

• ( and ) detected by the “RV” (Radial Velocity) method

from dace_query.exoplanet import Exoplanet
filters: dict = {
    'obj_id_catname': {
        'contains':
            ['TOI', 'HD'],
        'notEqual': ['TOI-755 b']
    },
    'obj_orb_period_day': {
        'min': 2.5,
        'max': 3
    },
    'pub_info_detectiontype': {
        'equal': ['RV']
    }
}
values = Exoplanet.query_database(filters=filters, limit=10)

Sort order

Dace proposes for certain queries to sort parameters through the sort argument.

The sort works in the same way as the one offered on the DACE online site.

It consists of a dictionary type object (key-value), where the key is the parameter that we want to sort and the value will be the desired sort order.

Example : It returns recently discovered planets, sorted descending by the discovered year.

from dace_query.exoplanet import Exoplanet
sort: dict = {'pub_info_discovered_year': 'desc'}

values = Exoplanet.query_database(sort=sort, limit=10)

Example : It returns planets with the smallest orbital period, sorted ascending by the orbital period.

from dace.exoplanet import Exoplanet
sort: dict = {'obj_orb_period_day': 'asc'}
values = Exoplanet.query_database(sort=sort, limit=10)

Advanced usage example

The sort filter can be applied on multiple parameters at the same time.

Here is an example :

It returns planets:

• sorted ascending by the radius

• ( and then ) sorted descending by name

from dace_query.exoplanet import Exoplanet
sort: dict = {
    'obj_phys_radius_rjup': 'asc',
    'obj_id_catname': 'desc'
}
values = Exoplanet.query_database(sort=sort, limit=10)