Asynchronous Client with Callback¶

class SpayaClientCallback(callback, url, authorization, parameters=None, error_callback=None, settings=None)¶

This async client send SMILES to the Spaya websocket and gives the results through a callback

Examples

>>> import asyncio
... from iktos.spaya import (
...     BearerToken, SpayaClientCallback, RetrosynthesisResult
... )
...
... async def generator(client: SpayaClientCallback):
...     # Generate and start scoring SMILES
...     for smiles in ["O=C1CCCCO1", "O=C1CCCNN1",]:
...         await client.start_retrosynthesis(smiles)
...
... async def callback(smiles: str, result: RetrosynthesisResult):
...     # Handle the results
...     print(f"{smiles}: {result.rscore} / {result.nb_steps}")
...
... async def generate_and_score(url: str):
...     async with SpayaClientCallback(url=url,
...                                    authorization=BearerToken("myT0ken"),
...                                    callback=callback) as client:
...         # Generate SMILES
...         await generator(client)
...
...         # Block until the ends
...         await client.wait_result()
...
... asyncio.run(generate_and_score(url="https://spaya.ai"))

Parameters

callback (Callable[[str, iktos.spaya.model.RetrosynthesisResult], Awaitable]) – An async callable(smiles, result)
url (str) – URL to the Spaya API
authorization (iktos.spaya.authorization.Authorization) – Login authorization
parameters (Optional[iktos.spaya.model.RetrosynthesisParameters]) – Retrosynthesis algorithm parameters
error_callback (Optional[Callable[[SpayaClientCallback, BaseException], Awaitable]]) – Callback called in case of error or disconnection
settings (Optional[iktos.spaya.model.SettingsCallback]) – Client settings

async close()¶

Close the websocket and stop the callback

Return type: None

async clustering(smiles, dataframe_smiles_column='smiles', min_relative_size=None, max_cluster=None, max_coverage=None, alpha=None, min_route_rscore=None, extra_smiles=None)¶

Get clusters for batches of SMILES, these SMILES should have been retrosynthesised first.

Parameters

smiles (Union[str, List[str], pandas.core.frame.DataFrame]) – a list of smiles or a dataframe
dataframe_smiles_column (str) – smiles column name in dataframe
min_relative_size (Optional[float]) – minimum relative number of atoms (compared to average size) for intermediates, values in [0 ; 1]
max_cluster (Optional[int]) – Maximum number of clusters to create
max_coverage (Optional[float]) – stopping criteria on the % of initial smiles in a cluster. values in [0 ; 1]
alpha (Optional[float]) – relative importance of the size of the intermediate in the clusters’ scoring, values in [0 ; 1]
min_route_rscore (Optional[float]) – Minimum rscore to filter routes, values in [0 ; 1]
extra_smiles (Optional[List[Tuple[iktos.spaya.model.RetrosynthesisParameters, List[str]]]]) – a list of different parameters and SMILES to add to this clustering. Only max_nb_iterations and early_stopping_timeout can be different

Returns

List of clusters. One cluster contains routes that are grouped by the smiles they lead to

Return type

iktos.spaya.model.ClusteringResult

Examples

>>> import asyncio
... from iktos.spaya import BearerToken, SpayaClientAsync
...
... async def get_clusters():
...     # 1- Create client with authorization
...     async with SpayaClientAsync(
...         url="https://spaya.ai",
...         authorization=BearerToken("myT0ken"),
...         parameters=RetrosynthesisParameters(
...             early_stopping_timeout=1
...         )
...     ) as client:
...         # 2- Start a retrosynthesis and wait for the results
...         smiles_list = ["O=C1CCCCO1", "O=C1CCCNN1"]
...         await client.start_retrosynthesis(smiles_list)
...         await client.wait_result()
...
...         # 3- Get clusters
...         best_routes = await client.clustering(
...             smiles=smiles_list,
...             min_relative_size=0.1,
...             max_cluster=10,
...             max_coverage=0.95,
...             alpha=0.,
...             extra_smiles=[
...                 (
...                     RetrosynthesisParameters(early_stopping_timeout=3),
...                     ["Cc1occc(=O)c1O", "CN1C=CCSC1=N"]
...                 )
...             ]
...         )
...
...         # 4- Show results
...         for cluster in best_routes.clusters:
...             print(f"{cluster.key}:"
...             print(f"  mean_depths:{cluster.mean_depths}")
...             print(f"  mean_max_score:{cluster.mean_max_score}")
...             print(f"  smiles:{cluster.smiles}")
...
... asyncio.run(get_clusters())

Return type

ClusteringResult

Parameters

smiles (Union[str, List[str], pandas.core.frame.DataFrame]) –
dataframe_smiles_column (str) –
min_relative_size (Optional[float]) –
max_cluster (Optional[int]) –
max_coverage (Optional[float]) –
alpha (Optional[float]) –
min_route_rscore (Optional[float]) –
extra_smiles (Optional[List[Tuple[iktos.spaya.model.RetrosynthesisParameters, List[str]]]]) –

consume()¶

Update, return all finished SMILES results and remove them

Returns: A generator of SMILES result
Return type: AsyncGenerator[Tuple[str, RetrosynthesisResult], None]

async get_commercial_compounds(smiles, provider=None, catalog=None, packaging_g_min=None, packaging_g_max=None, price_per_g_min=None, price_per_g_max=None, delivery_date_max_day=None, delivery_included=None)¶

Access to commercial compounds

Parameters

smiles (Union[str, List[str], iktos.spaya.model.Route, pandas.core.series.Series]) – Molecules represented as either, a SMILES, a list of SMILES, a Route, or a Series.
provider (Optional[List[str]]) – List of desired commercial compounds providers. None or an empty list select them all
catalog (Optional[List[iktos.spaya.model.Catalog]]) – Select the type of compounds (building block / screening / virtual). A null value or an empty list select them all
packaging_g_min (Optional[float]) – Minimum packaging in gramme for a commercial compounds
packaging_g_max (Optional[float]) – Maximum packaging in gramme for a commercial compounds
price_per_g_min (Optional[float]) – Minimum price per gramme for a commercial compounds
price_per_g_max (Optional[float]) – Maximum price per gramme for a commercial compounds
delivery_date_max_day (Optional[int]) – Maximum delivery time in day. A null value select them all
delivery_included (Optional[bool]) – If True the comparaison will done with the maximum delivery date. If False the comparaison will done with the minimum delivery date”,

Returns

A dictionnary SMILES -> commercial compounds found

Return type

Dict[str, List[CommercialCompound]]

async get_commercial_compounds_providers()¶

Returns: List of available commercial compounds providers.
Return type: List[str]

async get_name_reactions(filter_name_reactions=None)¶

Get the possible value for name_reactions

Parameters: filter_name_reactions (Optional[str]) – optional case unsensitive regex
Returns: List of name reactions found.
Return type: List[str]

async get_retrosynthesis_quota()¶

Returns: The number of retrosynthesis left or None if illimited
Return type: Optional[int]

async get_status()¶

Returns: Current spaya api status
Return type: Status

property is_empty¶

True if all SMILES have been consumed

Return type: bool

property is_retro_finished¶

True if all SMILES have been processed

Return type: bool

property parameters¶

Retrosynthesis algorithm parameters

Return type: RetrosynthesisParameters

pop_finished(smiles)¶

Remove and return a Spaya RScore of a finished SMILES

Parameters: smiles (str) – SMILES to access
Returns: A retrosynthesis result or None if the SMILES is not finished
Raises: KeyError – if the SMILES is not in the client
Return type: Optional[RetrosynthesisResult]

pop_finished_to_dataframe(df, smiles_column='smiles', rscore_column='rscore', nb_steps_column='nb_steps')¶

Remove and complete a dataframe with a Spaya RScore and number of steps for each finished smiles

Parameters

df (pandas.core.frame.DataFrame) – dataframe to complete with RScore and number of steps
smiles_column (str) – smiles column name
rscore_column (str) – rscore column name
nb_steps_column (str) – number of steps column name

Returns

A completed dataframe

Return type

DataFrame

property progression¶

Progression (as percentage) of SMILES not consumed

Return type: float

remove(smiles)¶

Remove a SMILES from the client without removing the SMILES from the retrosynthesis queue

Parameters: smiles (str) – SMILES to remove
Raises: KeyError – if the SMILES is not in the client
Return type: None

async routes(smiles, top_k_routes=None, dataframe_smiles_column='smiles')¶

Get routes for batches of SMILES, these SMILES should have been retrosynthesised first.

Parameters

smiles (Union[str, List[str], pandas.core.frame.DataFrame]) – a list of smiles
top_k_routes (Optional[int]) – Number of routes to fetch per molecule
dataframe_smiles_column (str) – smiles column name in dataframe

Returns

A dictionnary of smiles and their routes

Raises

ValueError – The SMILES are not DONE, and still need to be retrosynthesised

Return type

Dict[str, List[iktos.spaya.model.Route]]

Examples

>>> # 1. Using a list of smiles
... import asyncio
... from iktos.spaya import BearerToken, SpayaClientAsync
...
... async def get_route():
...     # 1.1- Create client with authorization
...     async with SpayaClientAsync(
...         url="https://spaya.ai",
...         authorization=BearerToken("myT0ken")
...     ) as client:
...         # 1.2- Start a retrosynthesis and wait for the results
...         smiles_list = ["O=C1CCCCO1", "O=C1CCCNN1"]
...         await client.start_retrosynthesis(smiles_list)
...         await client.wait_result()
...
...         # 1.3- Get best 2 routes for each smiles
...         best_routes = await client.routes(
...             smiles=smiles_list,
...             top_k_routes=2,
...         )
...
...         # 1.4- Show results
...         for smiles_str, routes_list in best_routes.items():
...             for route in routes_list:
...                 print(f"{smiles_str}: {route.rscore} / {route.nb_steps}"
...                       f" -> {route.tree}")
...
... asyncio.run(get_route())

>>> # 2. Using a DataFrame
... import asyncio
... from iktos.spaya import BearerToken, SpayaClientAsync
...
... async def get_route():
...     # 2.1- Create client with authorization
...     async with SpayaClientAsync(
...         url="https://spaya.ai",
...         authorization=BearerToken("myT0ken")
...     ) as client:
...         # 2.2- Start a retrosynthesis and wait for the results
...         df = DataFrame({"input_smiles": ["O=C1CCCCO1", "O=C1CCCNN1",]})
...         await client.start_retrosynthesis(
...             smiles=df,
...             dataframe_smiles_column="input_smiles"
...         )
...         await client.wait_result()
...
...         # 1.3- Get best 2 routes for each smiles
...         best_routes = await client.routes(
...             smiles=df,
...             top_k_routes=2,
...             dataframe_smiles_column="input_smiles",
...         )
...
...         # 1.4- Show results
...         for smiles_str, routes_list in best_routes.items():
...             for route in routes_list:
...                 print(f"{smiles_str}: {route.rscore} / {route.nb_steps}"
...                       f" -> {route.tree}")
...
... asyncio.run(get_route())

Return type

Dict[str, List[Route]]

Parameters

smiles (Union[str, List[str], pandas.core.frame.DataFrame]) –
top_k_routes (Optional[int]) –
dataframe_smiles_column (str) –

async start_callback()¶

Start the task consuming the result and calling the callback function

Return type: None

async start_retrosynthesis(smiles, dataframe_smiles_column='smiles')¶

Add SMILES to score

Parameters

smiles (Union[str, List[str], pandas.core.frame.DataFrame]) – SMILES to score
dataframe_smiles_column (str) – smiles column name in dataframe

Return type

None

property unfinished_smiles¶

All smiles submited and not finished

Return type: Dict[str, RetrosynthesisResult]

property url¶

Spaya URL

Return type: str

async wait_result(callback_progression=None)¶

Block until all the SMILES are scored

Parameters: callback_progression (Optional[Callable[[float], Awaitable]]) – a callable with progression as parameter
Return type: None